The Responses API connects your application with models and tools. The Agents SDK organizes agent work at your own code. To understand the difference prevents attributing to the model tasks of execution and control that belong to the run time.
Key concepts
Think about three levels: models production of responses and proposals for actions Responses API as an interface for invoking them with context and tools; and Agents SDK to define agents and coordinate your loop. The module studies this course base, and not the whole product catalogue that can be published later.
Using SDK doesn't mean that OpenAI automatically hosts your Python application. Your application remains owner from your deployment, integrations, data and authorisation decisions. A hosted tool and a feature of your backend can appear in the same flow, though they run in different environments.
For a simple request you can call Responses directly. If you need several steps, you can also implement the loop into your application. The SDK will be useful if you are interested in re-using co-ordination, tools, handoffs and guarrails. The choice depends on how much control you need and how logical you want to maintain, and not how an option's always better.
Module Objectives
- To choose from a call directly to Responses and an SDK-run loop.
- Differentiate hosted tools, function tools and agents as tools.
- To explain who retains control after a handoff.
- To place validation, approval and observability where they really protect the flow.
Responses and context
A request to Responses specifies model, input and, as appropriate, instructions and tools. The output can contain text and other elements, including requests execution. output_text easier to read the final text but an integrer should examine the relevant elements while applying the loop.
To conduct discussions there are options as a history administered by the application, previous_response_id To channel answers and Conversations to preserve elements in a conversation. Having a continuity identifier does not remove context boundaries, costs or retention decisions. Choose a strategy and preserve the data that that strategy requires. The state's official conversation guide explain his differences.
Agents, Runner and Tools
A Agent brings together a responsibility, instructions, model and capabilities. The Runner conduct the cycle: invokes the model, attends tools or delegations and returns a result after its end. At Python, Runner.run is asynchronous and Runner.run_sync serves in an appropriate synchronous context. final_output contains the final result output. The type depends how the agent has been set up.
One function tool Expand code your application. The decorator @function_tool seizes signature, types and description to represent the capacity. The model requests an operation with arguments. The runtime runs the implementation. One hosted toolas a search compatible with the model chosen, operates from service. Agents as tools allows a leading agent to consult a specialist as a closed capacity and then prepare the response.
The schemes improve the form of arguments, but a refund function should still check owner, amount, state and duplicates. A API key is saved on the server or in a protected environment, never at public JavaScript from a study page.
Handup and liability
with a handoffControl of that branch goes to specialist. with a manager using agents as tools, the main retains responsibility for the response. Several actors are not required just because there are several tools: they divide when responsibilities, policies or capabilities change. The official orchestration pattern He describes that distinction.
Step-by-step example
It mentally builds a support system with triage, orders and returns.
- The user asks "Where's my order P-204?" Input validation checks range and format.
- Triage identifies intention and performs a handoff to the order specialist.
- That agent's applying
consultar_pedido. The backend checks access and returns "in preparation." - The specialist writes the answer using that result, without claiming that it was already delivered.
- If the user after applying for a refund, the refund policy and the authorization of the concrete action are applied before issuing a refund.
The demonstration uses fictitious data and a function that only simulates the operation. Test order nonexistent, denied access and request out of topic. In each case there should be a controlled response and no real financial operation.
Wagons and traces
Input, output and tools have different ranges. In the SDK, the inlet are applied to the first agent of the chain and the end agent to whom the final response results. Don't assume they're repeated at every specialist. The validation of an action sensitive is placed next to the tool and an approval can pause the flow. Parallel checks reduce latency but can allow speculative work: using execution blocking as necessary. Query and human monitoring.
In the support example, a voucher can produce a structured output as is_support_question: bool, as defined with a Pydantic model. If the result does not meet the rule, the guarrail can activate a tripwire: The Runner intersects execution with an exception that the application should manage. Do not uncover operations already undertaken. That's why it matters when it's valid. The official implementation of SDK guarrails shows structured result and execution modes.
A trace shows stages, calls and available results. helps to distinguish time from model, from a API and from validation. It protects the registered data and checks the layout configuration. Do not interpret a trace as complete internal reasoning or feel that the most visible function is necessarily the bottle neck.
Common errors
- To merge SDK client API with Agents SDK: they have different responsibilities.
- To hope that defining a tool will immediately run your code.
- To believe that a handoff guarantees his return to the triage agent.
- Trust the entrance guard to approve all subsequent repayments.
Design exercise
A staff member should consult two specialists and put his or her results together in a single report. What best indicates that responsibility?
Solution
A manager with specialists exposed as tools keeps track and synthesizes the report. The handoff is suitable when another specialist has to take care of the conversation. None of them by itself authorized sensitive actions: each tool retains its validations and permissions.
Sources and review
The official introduction to Agents SDK links definitions, execution and tools. Review the support case by indicating what configuration belongs to the agent and how logical it should stay in the application. The exact syntax and capabilities should be checked with the SDK version and the chosen model.