OpenAI Agents SDK – A Guide for Financial Institutions
Introduction
Agentic AI promises to perform complex tasks completely autonomously. Since 2025, the OpenAI Agents SDK has provided a standardised framework for developing such agents. It significantly reduces the integration effort by combining instructions, tools, storage and security in a single library. In this article, we summarise the most important components of the SDK and explain new developments up to the beginning of 2026.
Core building block: “Agent”
An agent is a system based on a large language transformer that uses it together with instructions, tools and logic. Only two properties are required for a functional agent: a unique name and instructions that define its behaviour. The instructions serve as a system prompt and determine whether the agent responds as a “helpful assistant” or a “financial researcher,” for example. Extensions such as tools, handoffs, guardrails, context or metadata can be added depending on the use case.
Synchronous vs. asynchronous
Agents can be executed either synchronously or asynchronously. run_sync() executes the agent in a blocking manner, which means that the programme pauses at this point and does not execute any further instructions until the result has been fully calculated. In environments with an existing asyncio loop (e.g. Jupyter), run() can be used as an asynchronous, i.e. non-blocking, call. Non-blocking means that the agent runs in the background while the programme can continue to process other tasks in parallel instead of having to wait for the result.
Tools
Tools allow agents to generate more than just text. They can execute Python functions, delegate to other agents, or access hosted services. The SDK distinguishes between three classes of tools:
| Tool class | Description |
| Function Tools | Python functions that are provided as tools. They must be marked with the `@function_tool` decorator. The agent uses the function name and docstring as metadata to decide when to call the function. |
| Agent Tools | Instead of a function, another agent can be used as a tool. This allows complex tasks to be delegated to specialised sub-agents. |
| Hosted tools | Tools provided by OpenAI such as WebSearchTool, FileSearchTool, ComputerTool, and CodeInterpreter. These services run in the cloud and do not need to be implemented yourself. |
The description of the tools is key: the agent only reads the metadata and decides whether a tool is required based on the docstring. Clear, detailed descriptions therefore increase the likelihood that the right tool will be called up.
Control tool usage
In some situations, you need to enforce or restrict tool usage. The `ModelSettings.tool_choice` option allows you to specify whether the agent must use a particular tool, avoid it, or leave the decision to the model. In addition, `tool_use_behavior` can be used to define whether the result of a tool should be returned directly or processed again by the model.
Example: Function as a tool
A common scenario is that an agent can access Python functions. The following example defines a function `get_weather()`, marks it with `@function_tool`, and passes it to an agent as a tool:
The code in Figure1 demonstrates how the agent recognises the weather function via its description and calls it when needed.
Example: Enforcing tool usage
Sometimes it makes sense to force the model to use a tool. In the following example, `ModelSettings` is used to specify that the `get_weather` tool must be used:
Setting the `tool_choice` option to the name of the tool (see Figure2 ) causes the model to always call the function.
Handoffs – Delegation to other agents
Handoffs enable an agent to transfer tasks to specialised sub-agents. An agent can either provide a final response or generate a handoff instruction. The Runner class acts as the central execution and control instance: it starts the agent, monitors its output, and detects whether a normal response or a handoff instruction has been generated. If a handoff occurs, the Runner class takes over coordination and automatically transfers control and the current context to the specified subagent so that the process continues without manual intervention.
The handoff function can be finely tuned. It offers parameters such as `tool_name_override` for renaming the subagent, `tool_description_override` for an alternative description, `on_handoff` for callback logic, and `input_type` and `input_filter` for defining the input data. Such options are important when agents switch between different areas of expertise – for example, from handling mathematical questions to travel expense advice.
Example: Delegation via handoffs
In the following example, a triage agent acts as a router: it decides whether to transfer the user request to a Spanish-speaking or English-speaking subagent based on the language of the user request. The handoff mechanism is processed automatically by the SDK; the developer only needs to specify the subagents in the `handoffs` list:
This example (in Figure3 ) shows how handoffs can be used to orchestrate complex multi-agent workflows. The triage agent automatically recognises that the request is in Spanish and transfers control to the appropriate sub-agent.
Context and dynamic instructions
The context is an object that is passed to the agent for each execution. It serves as a “dependency injection” and provides state-dependent information that is not contained in the user prompt. This can be, for example, the name and age of a user or functions for querying internal databases. The context is packaged in a `RunContextWrapper`, which is passed as the first argument to all tool functions and hooks.
The context is not automatically sent to the language model. If you want this information to be part of the prompt, you use dynamic instructions. Instead of a static string, you pass the agent a function that reads the context from the wrapper and generates a prompt from it. For example, allows you to create a personalised greeting by inserting the user name into the instructions at runtime.
Example: Using the context wrapper
The following example defines a Pydantic data class `UserInfo`, passes it as context, and implements a tool that reads the user’s name from the `RunContextWrapper`. The SDK ensures that the context is automatically passed to the tool function:
This code snippet (see Figure4 ) illustrates how context data is passed to tools via `RunContextWrapper`.
Example: Dynamic instructions
Instead of using static instructions, these can be generated at runtime based on the context. In the following example, `dynamic_instructions` is a function that reads the user’s name from the context and embeds it in the system prompt:
In Figure5 , the agent uses the `dynamic_instructions` function to generate the system prompt at runtime from the context.
Sessions – memory for conversations
A session object acts as persistent storage and remembers past dialogues. Without a session, the agent is stateless and forgets previous messages. Sessions are particularly relevant for chat applications, as they can establish connections between multiple requests. The SDK supports various storage locations:
- SQLite session: Stores conversation histories locally in an SQLite file and loads them automatically each time it is run.
- In-memory session: Keeps the history only in memory, useful for temporary chats.
- OpenAI Conversations API session: Stores the history in the OpenAI cloud, so no separate database is required.
Example: Using a session
The following sequence shows how to use an `SQLiteSession` to store the conversation history across multiple calls. The agent remembers the answers from previous questions:
The SDK handles memory management (see Figure6 ). The agent automatically receives the history with each run and can derive coherent responses from it.
Guardrails – security and compliance
Guardrails are security mechanisms that check an agent’s inputs and outputs. The SDK distinguishes between input and output guardrails:
Input guardrails: Check the user request before the agent processes it. The example in Figure 7 uses an input guardrail to prevent the agent from solving maths homework problems.
Output guardrails: Evaluate the agent’s response, for example to block violent content.
Guardrail functions deliver structured results and trigger exceptions in the event of violations. Such security mechanisms are essential for banks in order to comply with regulatory requirements and protect sensitive data.
Example: Input guardrail for blocking maths queries
To prevent a support agent from being overwhelmed with maths homework, an input guardrail can be defined. The guardrail is executed before the agent executes and aborts if unwanted content is detected:
In this example (see Figure7 ), `math_guardrail` checks the user request and throws an `InputGuardrailTripwireTriggered` exception when it detects numbers. This corresponds to the use of an input guardrail in the SDK.
Hooks – Insight into the agent lifecycle
Hooks are event listeners that allow logic to be included before, during, or after an agent execution. There are AgentHooks, which are bound to a specific agent, and RunHooks, which apply to an entire execution run. Methods such as `on_start` and `on_tool_end` can be used to write logs or perform additional validations, for example.
New developments until 2026
Since its initial release in March 2025, the Agents SDK has been continuously expanded. According to the OpenAI blog, the focus is on four areas: easily configurable agents, intelligent handoffs, configurable guardrails, and integrated tracing/observability features. These features facilitate debugging and quality control in complex workflows.
In the summer of 2025, OpenAI announced further improvements. The SDK now supports TypeScript, bringing familiar features such as guardrails, handoffs and the Model Context Protocol to the JavaScript world. In addition, human-in-the-loop approvals have been introduced, allowing developers to pause tool calls and manually approve or reject them. For voice agents, there is an improved speech-to-speech model with better instruction following and the ability to control speech rate.
Conclusion
The OpenAI Agents SDK marks an important step towards practical, agentic AI. It reduces the complexity of building agents through tools, handoffs and guardrails – while still allowing for fine-tuned control. This opens up a wide range of opportunities for financial institutions to improve customer service, automate processes and comply with regulatory requirements.
With an academic background in mathematics (MSc, University of Zurich) and professional experience as an IT consultant in Zurich, he combines analytical strength with practical implementation. In various projects at major Swiss banks, he was responsible for the development and implementation of solutions in the areas of data migration, reconciliation, and automation. He used Python and SQL to optimize complex processes and make data usable as a measurable value for the business.
Through a combination of research, teaching, and consulting, he is working to design scalable, data-driven solutions for the banking of the future.