Agentuity Documentation

The OpenAI Agents SDK provides a small typed Agent class plus a run() function that drives the tool-calling loop. Drop it into a Hono route when you want an OpenAI-flavored agent without writing the loop yourself.

npm install hono @openai/agents zod

Define the Agent and Tools

Tools use Zod schemas for parameters. Each tool has a name, description, parameters schema, and an execute function.

typescriptsrc/lib/research-agent.ts

import { Agent, tool, setTracingDisabled } from '@openai/agents';
import { z } from 'zod';
 
setTracingDisabled(true);
const model = process.env.OPENAI_MODEL;
 
if (!model) {
  throw new Error('Set OPENAI_MODEL to the model this agent should use.');
}
 
const search = tool({
  name: 'search',
  description: 'Search for information on any topic',
  parameters: z.object({
    query: z.string().describe('The search query'),
  }),
  execute: async ({ query }) => `Results for: ${query}`,
});
 
export const researchAgent = new Agent({
  name: 'Research Assistant',
  instructions: 'You are a helpful assistant. Be concise.',
  model,
  tools: [search],
});

setTracingDisabled(true) skips the SDK's local tracing exporter. Remove that line if you want the SDK's traces.

Wire the Route

run(agent, message) runs the full ReAct loop. The route validates, runs, returns.

typescriptsrc/index.ts

import { Hono } from 'hono';
import { run } from '@openai/agents';
import { researchAgent } from './lib/research-agent';
import { z } from 'zod';
 
const requestSchema = z.object({
  message: z.string(),
});
 
const app = new Hono();
 
app.post('/api/research', async (c) => {
  const body: unknown = await c.req.json();
  const { message } = requestSchema.parse(body);
 
  const result = await run(researchAgent, message);
 
  return c.json({
    response: typeof result.finalOutput === 'string'
      ? result.finalOutput
      : JSON.stringify(result.finalOutput),
  });
});
 
export default app;

Handoffs

Multiple agents compose with the SDK's handoff pattern. Each child agent has its own instructions and tools; the parent decides when to delegate.

import { Agent, run } from '@openai/agents';
 
const model = process.env.OPENAI_MODEL;
 
if (!model) {
  throw new Error('Set OPENAI_MODEL to the model this workflow should use.');
}
 
const refundAgent = new Agent({
  name: 'Refund Agent',
  instructions: 'Process refund requests. Confirm the order ID first.',
  model,
});
 
const triageAgent = new Agent({
  name: 'Triage',
  instructions: 'Route the user to the right specialist.',
  model,
  handoffs: [refundAgent],
});
 
const result = await run(triageAgent, 'I want a refund on order ord_123.');

The SDK manages the handoff turn for you. The route still sees one round trip.

When to reach for the OpenAI Agents SDK

Pick this SDK when you want OpenAI's first-party agent loop, especially for handoffs and hosted tools. Pick the Anthropic SDK loop when Anthropic's tool_use blocks are central. Pick raw AI SDK when you want one provider-agnostic surface.

Run locally with agentuity dev to use AI Gateway env wiring for the OpenAI SDK. For deployed apps, set provider keys directly unless you have verified the project receives the gateway env your SDK path needs.

Next Steps

Agents: the plain-function pattern this page wraps
Tool Calling: the AI SDK path with provider-agnostic tool calls
Autonomous Research: a hand-rolled tool loop using the Anthropic SDK