scaffolding-openai-agents

Create specialist agents with handoff_description fields, then attach them to a triage agent via the handoffs parameter. The triage agent analyzes each request and routes it to the appropriate specialist automatically when you call Runner.run.

Decorate a Python function with @function_tool and pass it in the agent's tools list. The SDK derives the tool schema from the function signature and docstring, and both sync and async functions are supported.

Yes, use Runner.run_streamed instead of Runner.run, then iterate over result.stream_events() in an async loop. Each event with a delta attribute yields incremental output tokens suitable for SSE or FastAPI StreamingResponse.

Call result.to_input_list() after a run to get the full message history, append the new user message, and pass the combined list to the next Runner.run call. This preserves context across turns.

Use handoffs when a triage agent should fully transfer control to a specialist, which is the recommended routing pattern. Use agents as tools when a manager agent must coordinate multiple specialists and combine their outputs within one run.

Avoid it when you need raw OpenAI API calls without SDK abstractions or when your stack is built on another framework like LangChain. The SDK patterns here assume the openai-agents package and its Agent and Runner model.