XNews

OpenAI Building Agents Guide & Best Practices

OpenAI Building Agents Guide & Best Practices

OpenAI published a guide on building AI agents, defining an agent as a system with instructions, guardrails, and tools that can act on behalf of users. It distinguishes reasoning models (slower, more reliable) from non-reasoning models (faster, cheaper), recommending starting with flagship models and adjusting reasoning_effort. The guide compares Responses API (stateful, flexible) and Agents SDK (built on top, handles agent loop, guardrails, tracing, supports external models). Tools include custom function calling and built-in tools: Web Search, File Search (managed RAG), Code Interpreter, Computer Use (visual feedback loop), Image Generation, and MCP. Orchestration uses Agents SDK primitives: Agent, Handoff, Guardrail, Session. Multi-agent setups are advised only when tasks are non-overlapping, using a routing agent pattern and agent-as-tool with shared conversation_id. Three example use cases: support agent (human-in-the-loop), customer service agent (multi-agent network), front-end testing agent (computer use). Best practices include input guardrails to prevent jailbreaking and irrelevant inputs, structured outputs with JSON Schema for programmatic consumption, and output guardrails to prevent harmful content. The guide emphasizes managing unpredictability inherent in LLMs.

Key insights

OpenAI Defines Agents with Three Essential Components

OpenAI's guide states that an AI system qualifies as an agent only when it has instructions (what to do), guardrails (what not to do), and tools (what it can do), and can take actions on behalf of users by connecting to external systems. This definition sets a clear boundary between simple chatbots and true agents.

Reasoning Models Trade Latency and Cost for Reliability

The guide distinguishes reasoning models, which use chain-of-thought before responding, from non-reasoning models that are faster and cheaper. It recommends starting with flagship reasoning models and downgrading for simple tasks, or increasing reasoning_effort for complex ones, framing the choice as a tradeoff between latency/cost and reliability.

Built-in Tools Simplify Agent Development

OpenAI provides a suite of built-in tools—Web Search, File Search (managed RAG), Code Interpreter, Computer Use, Image Generation, and MCP—that run on OpenAI infrastructure without user-side execution. The guide advises using built-in tools first and resorting to custom function calling only when specific logic is needed, reducing development complexity.

Multi-Agent Systems Should Be Used Sparingly

OpenAI advises against making multi-agent the default. It recommends multi-agent only when tasks are non-overlapping and instructions are too complex or tool sets too large for a single agent, to avoid tool confusion. The preferred pattern is a routing agent that hands off to specialized agents, with agent-as-tool implementation and shared conversation_id.

Structured Outputs Are Critical for Engineering Reliability

The guide emphasizes that whenever agent output is consumed programmatically, it must be constrained with JSON Schema via Structured Outputs. This ensures predictable, machine-readable responses and is described as the cornerstone of engineering reliability in agent systems.

Source posts