Hatchet and MCP: Using the OpenAI Agents SDK in a Trusted Environment
This cookbook builds on the Hatchet Agent Tools guide by connecting the OpenAI Agents SDK directly to Hatchet-backed support tools. When the agent decides to use a tool, the tool handler submits a run to the Hatchet engine. A worker executes the task, and the result flows back to the agent.
What this example builds
The example uses a support scenario similar to How to Create a Support Agent Using Hatchet, but with a different architecture. That cookbook models support as a durable Hatchet workflow. This cookbook shows the agent choosing among separate Hatchet-backed tools:
- lookup-customer: retrieve a customer profile by ID.
- check-order-status: check shipping status and known issues for an order.
- create-ticket: open a support ticket for the customer.
The same Hatchet-backed tool pattern also works for workflows, as shown in Hatchet Agent Tools. Use a workflow when a tool should trigger a multi-step process rather than a single operation. Later guides in this series will explore larger production agent patterns.
Architecture
The agent may call independent tools in a different order depending on the model’s decisions.
Unlike the Claude Agent SDK example, there is no in-process MCP server here. Hatchet’s MCP tool helper converts each task into an OpenAI-compatible tool, which is passed directly to the OpenAI Agent.
Trusted environment pattern. This cookbook uses a trusted-harness architecture. The agent process runs in your own infrastructure with direct access to Hatchet credentials. If you need to run agent turns inside untrusted sandboxes with credentials kept outside, that is a different architecture pattern covered in a later guide.
Setup
Prepare your environment
You need:
- A working local Hatchet environment or access to Hatchet Cloud
- A Hatchet SDK example environment (see the Quickstart)
- An
OPENAI_API_KEYenvironment variable set with a valid OpenAI API key
Install the OpenAI Agents SDK integration for your language:
Install the Hatchet SDK extra for OpenAI:
pip install "hatchet-sdk[openai]"Define the models
Define input and output types for each tool. The agent uses the input schema to understand what arguments a tool accepts.
Set up the Hatchet client
Initialize the Hatchet client. It reads credentials from environment variables or a .env file.
Add deterministic support data
The following fixture data keeps the example runnable without any third-party APIs.
Define the Hatchet-backed tools
Each tool is a standalone Hatchet task with a description and an input validator, as covered in the Hatchet Agent Tools guide.
Lookup customer
First, define a tool that retrieves customer profile data.
Check order status
Next, define another tool that returns shipping status, carrier, and any known issues for an order.
Create ticket
Finally, define a tool that creates a support ticket. Validate inputs before creating records, and consider attaching agent or user context with additional metadata to improve traceability.
Expose the tasks as OpenAI agent tools
Convert each task into an OpenAI FunctionTool using Hatchet’s tool helper. Although the helper has mcp in its name, this example passes FunctionTool objects directly to the OpenAI Agents SDK. A later guide in this series will cover using the OpenAI Agents SDK with an MCP server.
The worker does not discover agent tools. It registers Hatchet tasks normally. When the tool handler submits a run, Hatchet dispatches it to a worker that registered the corresponding task.
Register and start the worker
Register the Hatchet tasks with a worker. Tool calls submit runs to the Hatchet engine, which dispatches them to a running worker.
Wire the OpenAI Agents SDK
Now we have everything we need to create the support agent. Pass each tool directly to the OpenAI Agent through the tools array. Unlike the Claude version of this cookbook, this example does not create an in-process MCP server or declare a list of pre-approved MCP tool names.
The example runs the agent once, waits for the tool calls to complete, and prints the final result.
Test it
Start the worker in one terminal and run the agent in another. The worker must be running before the agent calls any tools.
Start the worker:
cd sdks/python
poetry run python -m examples.support_agent_tools.workerIn a second terminal, run the agent:
cd sdks/python
poetry run python -m examples.support_agent_tools.agent_openaiWhen successful, you should see tool calls for all three agent tools. Given the fixture data used in this example, the agent looks up customer C-100, checks order ORD-9987, creates a high priority ticket for the delayed delivery, and prints a final summary to the terminal.
Each tool call appears as a task run in the Hatchet dashboard with full status, timing, and input/output visibility.
Security considerations
The agent process has direct access to Hatchet client credentials and runs in your own infrastructure. Every tool passed to the agent adds to the model’s available capability set. Once a tool is available to the model, you should assume the model may attempt to call it. Do not rely on the agent prompt alone to enforce security rules.
Hatchet does not provide native code sandboxing. If you need to run each agent turn inside an untrusted sandbox, use a different architecture with external sandbox providers and credential proxying. Later guides in this series will explore sandboxed and custom-harness patterns.
Next steps
- Hatchet Agent Tools: the prerequisite guide for exposing tasks and workflows as MCP tools.
- Claude Agent SDK: the same support scenario using the Claude Agent SDK.
- How to Create a Support Agent Using Hatchet: a workflow-first support-agent pattern with durable waits and escalation.
- Python SDK reference and TypeScript SDK reference: full SDK references.