• Engineering post: https://openai.com/index/equip-responses-api-computer-environment
• Agents SDK docs: https://developers.openai.com/api/docs/guides/agents

Workflow

Step 1: Define tool schemas

• Declare explicit input and output schemas (Zod or JSON Schema). Schemas reduce argument coercion, simplify validation, and make UI wiring predictable.

Example (Zod):

const getWeatherSchema = z.object({ location: z.string(), units: z.enum(['celsius','fahrenheit']).default('fahrenheit') });

• Supply these schemas to Vercel AI SDK inputSchema/outputSchema so object-generation UI and agent harness components can render forms and validate outputs before execution.

Step 2: Implement deterministic tool handlers

• Keep handlers small, deterministic, and idempotent. Wrap side effects with confirmations and rate-limited retries.
• Validate inputs with your schema library server-side before executing. Return structured success/error objects (e.g., {status: 'ok', data: ...} or {status: 'error', code, message}).
• For long-running or containerized tasks, return concise artifact references (file ids, short summaries) rather than inlining large outputs.

Step 3: Orchestrator loop — OpenAI Responses (practical)

• Send messages + tool definitions to Responses API. When the model returns a function_call, validate name and args server-side.
• Execute the tool and immediately send back the paired function_call_output containing the same call id. The model continues after receiving that result.
• Implementation checklist:
  • Validate tool name against a server-side allowlist.
  • Validate and coerce arguments using schema libraries (Zod/JSON Schema) before execution.
  • Preserve and return call id on the paired result.
  • Execute independent calls in parallel but tag results with ids; serialize dependent calls.
  • Summarize or persist large results and return artifact ids.

Notes and best practices:

• Use the OpenAI shell tool and hosted container workspace when your agent needs files, a filesystem, or restricted network access. The container solves common problems like where to place intermediate files and how to keep prompts compact. See the OpenAI engineering post for design rationale and caveats: https://openai.com/index/equip-responses-api-computer-environment
• Prefer the Agents SDK higher-level primitives (Runner, SandboxAgent, Manifest entries) for production agents where available — they encapsulate sandboxing and harness patterns and reduce bespoke harness code.

Step 4: Orchestrator loop — Anthropic (practical)

• When Claude emits tool_use blocks, execute each client-callable tool and return tool_result blocks that include the original tool_use_id so the model can continue.
• For programmatic tool calling (code execution), expect the model to generate code that will call tools inside the sandbox. Those internal calls are surfaced as tool_use events to your orchestrator; fulfill them and return matching tool_result objects.
• Implementation checklist:
  • Check the required code execution tool version (code_execution_20260120) and the model list that supports it before deploying PTC.
  • Validate and sanitize any inputs that will be interpolated into sandbox-executed code to reduce injection risk.
  • Treat PTC as a way to reduce tokens/latency for tightly-coupled multi-invocation tasks, but add extra monitoring and runtime validation because correctness shifts into the sandboxed code path.
  • Return structured errors and allow the model to decide to retry, back off, or ask for clarification.

Examples and patterns

• Minimal OpenAI client example (conceptual):

import OpenAI from 'openai'; const client = new OpenAI(); const tools = [{ name: 'get_weather', description: 'Get current weather', parameters: { type: 'object', properties: { location: { type: 'string' }, units: { type: 'string', enum: ['celsius','fahrenheit'], default: 'fahrenheit' } }, required: ['location'] } }]; const res = await client.responses.create({ model: 'gpt-5.4', tools, input: [{ role: 'user', content: "What's the weather in Paris?" }] }); // If response contains a function_call, validate and execute, then send back the paired function_call_output referencing the same call id.

• Anthropic programmatic tool calling (concrete notes):

// Programmatic tool calling lets Claude execute code in a sandbox that runs multiple tool calls locally. The code execution feature must be enabled and compatible with the model version you choose. Data retention for PTC follows the feature's retention policy and is not ZDR by default; verify compliance for sensitive workloads. Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

• Vercel AI SDK v6 (ToolLoopAgent example & install):

// Install (beta): // npm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta // Pin to specific beta versions for production testing.

import { ToolLoopAgent } from 'ai'; import { weatherTool } from '@/tool/weather';

export const weatherAgent = new ToolLoopAgent({ model: 'anthropic/claude-sonnet-4.5', instructions: 'You are a helpful weather assistant.', tools: { weather: weatherTool } }); const result = await weatherAgent.generate({ prompt: 'What is the weather in San Francisco?' });

• Parallel tool execution pattern:

  • Identify independent tool calls (no shared side effects or data dependencies).
  • Execute them concurrently and return each result with the original call id so the model can match replies.
  • For dependent steps, serialize execution and return intermediate results in order.

• Multi-tool composition guidance (updated):

  • For short multi-step tasks, prefer the Responses API function_call loop (explicit function_call → execute → function_call_output) so the model and orchestrator remain synchronized.
  • For longer, tightly-coupled multi-invocation workflows, consider Anthropic PTC or provider-side programmatic execution (OpenAI Agents SDK / hosted container) to reduce round trips and token consumption — but add runtime monitoring, input/output validation, and explicit artifact summarization.

• Error recovery: retries with exponential backoff for transient errors; for permanent failures, return structured errors so the model can adapt or ask for clarification.

Edge cases and gotchas (updated)

• Hallucinated tool names: always verify model-specified tool names against a server-side registry and refuse unknown names.
• Id pairing and ordering: preserve exact id values (function_call call_id / Anthropic tool_use_id) and return paired results promptly. Mismatched ids or delayed replies are a leading source of orchestration bugs (OpenAI engineering posts).
• Argument coercion: models may send strings for numeric fields. Use Zod/JSON Schema coercion or explicit parsing; if coercion fails, return a structured error the model can act on.
• Streaming deltas: tool calls and outputs may arrive incrementally when streaming. Accumulate and validate final payloads before executing side effects, or use transactional semantics in your handlers.
• Provider-run tool privacy: provider-run tools may retain or process results differently. Consult provider docs (OpenAI, Anthropic) and opt for client-run execution for sensitive inputs unless you have an explicit business agreement and documented retention policy. Treat provider-run tools as non-private by default.
• Prompt injection and social engineering: follow latest provider guidance (OpenAI, Anthropic) to constrain risky actions, sanitize inputs used in shell/exec contexts, and implement allowed command whitelists inside containers.
• Infinite loops & safety: set iteration limits, track recent tool calls, and implement guardrails (timeouts, max steps, human review triggers).

Evaluation criteria

• Tool selection accuracy: % correct tool chosen per intent.
• Argument accuracy: % of tool calls with valid, complete arguments.
• Execution success rate: % of tool calls that succeed on first attempt.
• Loop efficiency: average tool calls per task.
• Error recovery rate: % of failed calls where the model adapts successfully.
• Latency per tool turn: time from model response to submitted tool result.

Research-backed changes (sources)

• OpenAI News (Apr 15, 2026): "The next evolution of the Agents SDK" — announcement describing model-native harness and native sandbox execution: https://openai.com/index/the-next-evolution-of-the-agents-sdk
• OpenAI (Mar 11, 2026): "From model to agent: Equipping the Responses API with a computer environment" — shell tool and hosted container workspace: https://openai.com/index/equip-responses-api-computer-environment
• OpenAI Developers Docs (Agents SDK): https://developers.openai.com/api/docs/guides/agents
• Anthropic: Programmatic tool calling docs — feature description, compatibility, and retention notes (code_execution_20260120; compatible models listed): https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
• Vercel AI SDK: AI SDK 6 Beta — agent abstraction, ToolLoopAgent, tool approval flows, and structured output guidance: https://ai-sdk.dev/v5/docs/announcing-ai-sdk-6-beta