OpenAI Agents SDK

The OpenAI Agents SDK is OpenAI's official primitive for building multi-agent systems on top of the Responses API. Trefur ships a dedicated patchOpenAIAgents adapter in both TypeScript + Python that wraps Agent definitions, Runner invocations, function tools, and handoffs.

Install

npm install @trefur/observe @openai/agents

Setup — TypeScript

import * as agents from '@openai/agents';
import { Agent, Runner, tool } from '@openai/agents';
import { TrefurObserve, patchOpenAIAgents } from '@trefur/observe';
import { z } from 'zod';

// Initialise observe once at startup.
TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: 'support-triage', framework: 'openai-agents' },
});
// patchOpenAIAgents takes the imported '@openai/agents' module namespace
// and the observe instance. Call it before constructing your agents.
patchOpenAIAgents(agents, TrefurObserve.getInstance());

const lookupOrder = tool({
  name: 'lookup_order',
  description: 'Look up an order by id',
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => {
    return { status: 'shipped', tracking: 'UPS-1Z999AA1' };
  },
});

const triage = new Agent({
  name: 'Triage agent',
  instructions: 'Route customer support requests.',
  tools: [lookupOrder],
});

const refunds = new Agent({
  name: 'Refunds agent',
  instructions: 'Process refund requests.',
});

triage.handoffs = [refunds];

const result = await Runner.run(triage, 'My order #12345 never arrived');
console.log(result.finalOutput);

What gets traced

  • Each Agent definition registers as an observed agent on first use.
  • Runner.run creates a root run with the user input and final output.
  • Tool calls (any tool({}) or function_tool) — args + return values + duration.
  • Handoffs show as parent-child run links (one trace per agent that handled the request).
  • Guardrail violations — input + output guardrails fire as steps with status blocked.
  • Token usage rolled up across all turns.

Common use case — triage + handoff networks

The standard pattern is one triage agent that hands off to specialised agents (refunds, support, sales). Trefur renders the handoff graph: which agent answered, which it handed off to, how many round-trips happened, and where guardrails fired.

Common pitfalls

  • Patch before constructing agents. patchOpenAIAgents hooks the SDK's internal tracer. Call it before new Agent(...) or the first agent you construct will not emit.
  • Streaming output. Runner.run(...).stream() works but you must let the stream finish (or call result.abort()) before flush. Prematureprocess.exit drops the trailing steps.
  • Python users. The Python equivalent is from trefur_observe import patch_openai_agents; the rest of the surface is symmetric.

See the JavaScript SDK or Python SDK reference for the full adapter surface.