Core Concepts

Agents are LLMs with structure: An agent combines an LLM with instructions (system prompt), tools (functions it can call), handoffs (delegation targets), and optional guardrails (validators).

Minimal abstractions: The SDK provides primitives (Agent, tool, run) rather than heavyweight frameworks. You compose behavior through code, not configuration.

Context injection: Tools and instructions receive RunContext, enabling dependency injection of user data, database connections, or other runtime context without global state.

Handoffs transfer ownership: When one agent hands off to another, the target agent becomes the active conversational participant. This differs from tools (manager pattern) where the calling agent maintains control.

Guardrails run in parallel: Input guardrails can validate user input concurrently with the LLM call, reducing latency. Output guardrails check responses before returning them.

Structured output is typed: Using Zod schemas for outputType gives you compile-time type safety and runtime validation of agent responses.

Human-in-the-loop is first-class: Tools with needsApproval create interruptions that your code handles explicitly, enabling approval workflows without special infrastructure.

Design Principles

Start simple, add complexity as needed: Begin with a single agent and basic tools. Add handoffs, guardrails, and orchestration only when requirements justify them.

Test with real LLM calls: Mocking LLMs hides emergent behavior. Use small models (gpt-4.1-mini) or cached prompts for fast iteration, but always test end-to-end.

Make instructions specific: Vague prompts ("be helpful") produce vague behavior. Specify the agent's role, available information, decision criteria, and output format.

Tools are for actions, not data: Don't create tools just to return static information. Put reference data in instructions or context. Tools should execute side effects or retrieve dynamic data.

Fail explicitly: Return error strings from tools rather than throwing exceptions. This lets the LLM see what went wrong and potentially retry with different parameters.

Trace everything: Enable tracing in development to understand agent decision-making. The SDK's built-in tracing shows tool calls, handoffs, and model reasoning.