Skip to content

Feature: add support for programmatic tool calling in Responses API #790

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
e4se wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Feature: add support for programmatic tool calling in Responses API #790

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bbda5b0
Support streaming compaction output
e4se Jul 6, 2026
489107f
Merge pull request #1 from e4se/stream-compaction-output
e4se Jul 6, 2026
f3a75d6
Merge branch 'openai-php:main' into main
e4se Jul 18, 2026
e234096
Add programmatic tool calling support
e4se Jul 20, 2026
c08cd7c
Merge branch 'openai-php:main' into main
e4se Jul 20, 2026
4c89505
Merge remote-tracking branch 'origin/main' into add-programmatic-tool…
e4se Jul 20, 2026
75e7b0f
Add fixtures for programmatic DTOs
e4se Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions src/Actions/Conversations/ItemObjects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@
use OpenAI\Responses\Responses\Output\OutputMcpApprovalRequest;
use OpenAI\Responses\Responses\Output\OutputMcpCall;
use OpenAI\Responses\Responses\Output\OutputMcpListTools;
use OpenAI\Responses\Responses\Output\OutputProgram;
use OpenAI\Responses\Responses\Output\OutputProgramOutput;
use OpenAI\Responses\Responses\Output\OutputReasoning;
use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;

Expand All @@ -42,10 +44,12 @@
* @phpstan-import-type OutputCodeInterpreterToolCallType from OutputCodeInterpreterToolCall
* @phpstan-import-type OutputLocalShellCallType from OutputLocalShellCall
* @phpstan-import-type OutputCustomToolCallType from OutputCustomToolCall
* @phpstan-import-type OutputProgramType from OutputProgram
* @phpstan-import-type OutputProgramOutputType from OutputProgramOutput
*
* @phpstan-type ItemObjectTypes MessageType|ComputerToolCallOutputType|FunctionToolCallOutputType|LocalShellCallOutputType|McpApprovalResponseType|CustomToolCallOutputType|OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType
* @phpstan-type ItemObjectTypes MessageType|ComputerToolCallOutputType|FunctionToolCallOutputType|LocalShellCallOutputType|McpApprovalResponseType|CustomToolCallOutputType|OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType|OutputProgramType|OutputProgramOutputType
* @phpstan-type ConversationItemObjectTypes array<int, ItemObjectTypes>
* @phpstan-type ConversationItemObjectReturnType array<int, Message|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|CustomToolCallOutput>
* @phpstan-type ConversationItemObjectReturnType array<int, Message|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|CustomToolCallOutput|OutputProgram|OutputProgramOutput>
*/
final class ItemObjects
{
Expand All @@ -56,7 +60,7 @@ final class ItemObjects
public static function parse(array $outputItems): array
{
return array_map(
fn (array $item): Message|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|CustomToolCallOutput => match ($item['type']) {
fn (array $item): Message|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|CustomToolCallOutput|OutputProgram|OutputProgramOutput => match ($item['type']) {
'message' => Message::from($item),
'file_search_call' => OutputFileSearchToolCall::from($item),
'function_call' => OutputFunctionToolCall::from($item),
Expand All @@ -75,6 +79,8 @@ public static function parse(array $outputItems): array
'local_shell_call_output' => LocalShellCallOutput::from($item),
'custom_tool_call_output' => CustomToolCallOutput::from($item),
'mcp_approval_response' => McpApprovalResponse::from($item),
'program' => OutputProgram::from($item),
'program_output' => OutputProgramOutput::from($item),
},
$outputItems,
);
Expand Down
12 changes: 9 additions & 3 deletions src/Actions/Responses/ItemObjects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
use OpenAI\Responses\Responses\Output\OutputMcpCall;
use OpenAI\Responses\Responses\Output\OutputMcpListTools;
use OpenAI\Responses\Responses\Output\OutputMessage;
use OpenAI\Responses\Responses\Output\OutputProgram;
use OpenAI\Responses\Responses\Output\OutputProgramOutput;
use OpenAI\Responses\Responses\Output\OutputReasoning;
use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;

Expand All @@ -44,9 +46,11 @@
* @phpstan-import-type OutputCodeInterpreterToolCallType from OutputCodeInterpreterToolCall
* @phpstan-import-type OutputLocalShellCallType from OutputLocalShellCall
* @phpstan-import-type OutputCustomToolCallType from OutputCustomToolCall
* @phpstan-import-type OutputProgramType from OutputProgram
* @phpstan-import-type OutputProgramOutputType from OutputProgramOutput
*
* @phpstan-type ResponseItemObjectTypes array<int, InputMessageType|ComputerToolCallOutputType|FunctionToolCallOutputType|LocalShellCallOutputType|McpApprovalResponseType|CustomToolCallOutputType|OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType>
* @phpstan-type ResponseItemObjectReturnType array<int, InputMessage|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall>
* @phpstan-type ResponseItemObjectTypes array<int, InputMessageType|ComputerToolCallOutputType|FunctionToolCallOutputType|LocalShellCallOutputType|McpApprovalResponseType|CustomToolCallOutputType|OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType|OutputProgramType|OutputProgramOutputType>
* @phpstan-type ResponseItemObjectReturnType array<int, InputMessage|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputProgram|OutputProgramOutput>
*/
final class ItemObjects
{
Expand All @@ -57,7 +61,7 @@ final class ItemObjects
public static function parse(array $outputItems): array
{
return array_map(
fn (array $item): InputMessage|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall => match ($item['type']) {
fn (array $item): InputMessage|ComputerToolCallOutput|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputProgram|OutputProgramOutput => match ($item['type']) {
'message' => $item['role'] === 'assistant' ? OutputMessage::from($item) : InputMessage::from($item),
'file_search_call' => OutputFileSearchToolCall::from($item),
'function_call' => OutputFunctionToolCall::from($item),
Expand All @@ -76,6 +80,8 @@ public static function parse(array $outputItems): array
'local_shell_call_output' => LocalShellCallOutput::from($item),
'custom_tool_call_output' => CustomToolCallOutput::from($item),
'mcp_approval_response' => McpApprovalResponse::from($item),
'program' => OutputProgram::from($item),
'program_output' => OutputProgramOutput::from($item),
},
$outputItems,
);
Expand Down
12 changes: 9 additions & 3 deletions src/Actions/Responses/OutputObjects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
use OpenAI\Responses\Responses\Output\OutputMcpCall;
use OpenAI\Responses\Responses\Output\OutputMcpListTools;
use OpenAI\Responses\Responses\Output\OutputMessage;
use OpenAI\Responses\Responses\Output\OutputProgram;
use OpenAI\Responses\Responses\Output\OutputProgramOutput;
use OpenAI\Responses\Responses\Output\OutputReasoning;
use OpenAI\Responses\Responses\Output\OutputToolSearchCall;
use OpenAI\Responses\Responses\Output\OutputToolSearchOutput;
Expand All @@ -34,13 +36,15 @@
* @phpstan-import-type OutputImageGenerationToolCallType from OutputImageGenerationToolCall
* @phpstan-import-type OutputCodeInterpreterToolCallType from OutputCodeInterpreterToolCall
* @phpstan-import-type OutputCompactionType from OutputCompaction
* @phpstan-import-type OutputProgramType from OutputProgram
* @phpstan-import-type OutputProgramOutputType from OutputProgramOutput
* @phpstan-import-type OutputLocalShellCallType from OutputLocalShellCall
* @phpstan-import-type OutputCustomToolCallType from OutputCustomToolCall
* @phpstan-import-type OutputToolSearchCallType from OutputToolSearchCall
* @phpstan-import-type OutputToolSearchOutputType from OutputToolSearchOutput
*
* @phpstan-type ResponseOutputObjectTypes array<int, OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType|OutputToolSearchCallType|OutputToolSearchOutputType|OutputCompactionType>
* @phpstan-type ResponseOutputObjectReturnType array<int, OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput|OutputCompaction>
* @phpstan-type ResponseOutputObjectTypes array<int, OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputProgramType|OutputProgramOutputType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType|OutputToolSearchCallType|OutputToolSearchOutputType|OutputCompactionType>
* @phpstan-type ResponseOutputObjectReturnType array<int, OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputProgram|OutputProgramOutput|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput|OutputCompaction>
*/
final class OutputObjects
{
Expand All @@ -51,10 +55,12 @@ final class OutputObjects
public static function parse(array $outputItems): array
{
return array_map(
fn (array $item): OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput|OutputCompaction => match ($item['type']) {
fn (array $item): OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputProgram|OutputProgramOutput|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput|OutputCompaction => match ($item['type']) {
'message' => OutputMessage::from($item),
'file_search_call' => OutputFileSearchToolCall::from($item),
'function_call' => OutputFunctionToolCall::from($item),
'program' => OutputProgram::from($item),
'program_output' => OutputProgramOutput::from($item),
'web_search_call' => OutputWebSearchToolCall::from($item),
'computer_call' => OutputComputerToolCall::from($item),
'reasoning' => OutputReasoning::from($item),
Expand Down
2 changes: 1 addition & 1 deletion src/Actions/Responses/ToolChoiceObjects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ public static function parse(array|string $toolChoice): string|FunctionToolChoic
{
return is_array($toolChoice)
? match ($toolChoice['type']) {
'file_search', 'web_search', 'web_search_preview', 'computer_use_preview' => HostedToolChoice::from($toolChoice),
'file_search', 'web_search', 'web_search_preview', 'computer_use_preview', 'programmatic_tool_calling' => HostedToolChoice::from($toolChoice),
'function' => FunctionToolChoice::from($toolChoice),
}
: $toolChoice;
Expand Down
9 changes: 6 additions & 3 deletions src/Actions/Responses/ToolObjects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
use OpenAI\Responses\Responses\Tool\FunctionTool;
use OpenAI\Responses\Responses\Tool\ImageGenerationTool;
use OpenAI\Responses\Responses\Tool\NamespaceTool;
use OpenAI\Responses\Responses\Tool\ProgrammaticToolCallingTool;
use OpenAI\Responses\Responses\Tool\RemoteMcpTool;
use OpenAI\Responses\Responses\Tool\ToolSearchTool;
use OpenAI\Responses\Responses\Tool\WebSearchTool;
Expand All @@ -23,12 +24,13 @@
* @phpstan-import-type FunctionToolType from FunctionTool
* @phpstan-import-type ImageGenerationToolType from ImageGenerationTool
* @phpstan-import-type NamespaceToolType from NamespaceTool
* @phpstan-import-type ProgrammaticToolCallingToolType from ProgrammaticToolCallingTool
* @phpstan-import-type RemoteMcpToolType from RemoteMcpTool
* @phpstan-import-type ToolSearchToolType from ToolSearchTool
* @phpstan-import-type WebSearchToolType from WebSearchTool
*
* @phpstan-type ResponseToolObjectTypes array<int, CodeInterpreterToolType|ComputerUseToolType|CustomToolType|FileSearchToolType|FunctionToolType|ImageGenerationToolType|NamespaceToolType|RemoteMcpToolType|ToolSearchToolType|WebSearchToolType>
* @phpstan-type ResponseToolObjectReturnType array<int, CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|RemoteMcpTool|ToolSearchTool|WebSearchTool>
* @phpstan-type ResponseToolObjectTypes array<int, CodeInterpreterToolType|ComputerUseToolType|CustomToolType|FileSearchToolType|FunctionToolType|ImageGenerationToolType|NamespaceToolType|ProgrammaticToolCallingToolType|RemoteMcpToolType|ToolSearchToolType|WebSearchToolType>
* @phpstan-type ResponseToolObjectReturnType array<int, CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|ProgrammaticToolCallingTool|RemoteMcpTool|ToolSearchTool|WebSearchTool>
*/
final class ToolObjects
{
Expand All @@ -39,7 +41,7 @@ final class ToolObjects
public static function parse(array $toolItems): array
{
return array_map(
fn (array $tool): CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|RemoteMcpTool|ToolSearchTool|WebSearchTool => match ($tool['type']) {
fn (array $tool): CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|ProgrammaticToolCallingTool|RemoteMcpTool|ToolSearchTool|WebSearchTool => match ($tool['type']) {
'file_search' => FileSearchTool::from($tool),
'web_search', 'web_search_preview', 'web_search_preview_2025_03_11' => WebSearchTool::from($tool),
'function' => FunctionTool::from($tool),
Expand All @@ -50,6 +52,7 @@ public static function parse(array $toolItems): array
'tool_search' => ToolSearchTool::from($tool),
'namespace' => NamespaceTool::from($tool),
'custom' => CustomTool::from($tool),
'programmatic_tool_calling' => ProgrammaticToolCallingTool::from($tool),
},
$toolItems,
);
Expand Down
4 changes: 3 additions & 1 deletion src/Responses/Conversations/ConversationItem.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
use OpenAI\Responses\Responses\Output\OutputMcpApprovalRequest;
use OpenAI\Responses\Responses\Output\OutputMcpCall;
use OpenAI\Responses\Responses\Output\OutputMcpListTools;
use OpenAI\Responses\Responses\Output\OutputProgram;
use OpenAI\Responses\Responses\Output\OutputProgramOutput;
use OpenAI\Responses\Responses\Output\OutputReasoning;
use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;
use OpenAI\Testing\Responses\Concerns\Fakeable;
Expand All @@ -44,7 +46,7 @@ final class ConversationItem implements ResponseContract
use Fakeable;

private function __construct(
public readonly Message|OutputFileSearchToolCall|OutputFunctionToolCall|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputWebSearchToolCall|OutputComputerToolCall|ComputerToolCallOutput|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall $item
public readonly Message|OutputFileSearchToolCall|OutputFunctionToolCall|FunctionToolCallOutput|LocalShellCallOutput|McpApprovalResponse|CustomToolCallOutput|OutputWebSearchToolCall|OutputComputerToolCall|ComputerToolCallOutput|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputProgram|OutputProgramOutput $item
) {}

/**
Expand Down
Loading