OpenAI Agents SDK Architecture for Tool-Using Systems

Example workflow

• Define tool contracts before prompts: input schema, output schema, side effects, policy, and allowed runtime.
• Route model outputs through structured schemas so the UI and downstream tools never parse prose as state.
• Add approval boundaries for external writes, purchases, transactions, email sends, or irreversible actions.
• Log tool calls, retrieved evidence, policy checks, and final responses as separate observability events.
• Run evaluator gates on high-risk responses and block action when required evidence is missing.

Stack recommendations

• OpenAI Agents SDK or Responses API for model/tool orchestration.
• MCP or typed service adapters for integration boundaries.
• Zod or JSON Schema for structured inputs and outputs.
• Postgres or durable object storage for state, receipts, and audit logs.
• Langfuse or similar tracing for prompt, tool, and evaluator visibility.

Failure modes

• The prompt describes a safety policy that tools do not enforce.
• The model receives raw credentials or unrestricted side-effect tools.
• The UI trusts natural-language output as a machine state.
• Retrieval evidence is not linked to the final answer.
• No evaluator or approval gate exists for sensitive operations.

Verification checklist

• Every tool has a typed schema and documented side effects.
• High-risk actions require explicit approval or dry-run receipts.
• Traces separate prompt, retrieval, tool call, policy, and output events.
• Evaluator tests cover missing evidence, unsafe action requests, and malformed tool inputs.
• Production logs can reconstruct what the agent saw, decided, and executed.

Use when

• The application needs model planning plus deterministic tools.
• The team needs auditable tool calls and structured outputs.
• Users need approvals, receipts, or traceable execution.

Avoid when

• The app only needs a simple completion or summarization endpoint.
• The product cannot define allowed side effects yet.
• The team has not decided who approves sensitive actions.

Alternatives

• Use a plain Responses API route for simple chat and extraction tasks.
• Use LangGraph when you need explicit graph state and custom transitions.
• Use MCP servers to standardize tool access across multiple clients.

Tradeoffs

• The architecture is more explicit, but debugging becomes easier.
• Approval gates add friction, but they make governed execution viable.
• Structured outputs reduce flexibility, but they protect UI and tool contracts.