openai-agents

Install required packages:

```bash

npm install @openai/agents zod@3

npm install @openai/agents-realtime # For voice agents

```

Set environment variable:

```bash

export OPENAI_API_KEY="your-api-key"

```

Supported runtimes:

• Node.js 22+
• Deno
• Bun
• Cloudflare Workers (experimental)

---

1. Agents

LLMs equipped with instructions and tools:

```typescript

import { Agent } from '@openai/agents';

const agent = new Agent({

name: 'Assistant',

instructions: 'You are helpful.',

tools: [myTool],

model: 'gpt-4o-mini',

});

```

2. Tools

Functions agents can call, with automatic schema generation:

```typescript

import { tool } from '@openai/agents';

import { z } from 'zod';

const weatherTool = tool({

name: 'get_weather',

description: 'Get weather for a city',

parameters: z.object({

city: z.string(),

}),

execute: async ({ city }) => {

return Weather in ${city}: sunny;

},

});

```

3. Handoffs

Multi-agent delegation:

```typescript

const specialist = new Agent({ / ... / });

const triageAgent = Agent.create({

name: 'Triage',

instructions: 'Route to specialists',

handoffs: [specialist],

});

```

4. Guardrails

Input/output validation for safety:

```typescript

const agent = new Agent({

inputGuardrails: [homeworkDetector],

outputGuardrails: [piiFilter],

});

```

5. Structured Outputs

Type-safe responses with Zod:

```typescript

const agent = new Agent({

outputType: z.object({

sentiment: z.enum(['positive', 'negative', 'neutral']),

confidence: z.number(),

}),

});

```

---

Basic Usage

```typescript

import { run } from '@openai/agents';

const result = await run(agent, 'What is 2+2?');

console.log(result.finalOutput);

console.log(result.usage.totalTokens);

```

Streaming

```typescript

const stream = await run(agent, 'Tell me a story', {

stream: true,

});

for await (const event of stream) {

if (event.type === 'raw_model_stream_event') {

const chunk = event.data?.choices?.[0]?.delta?.content || '';

process.stdout.write(chunk);

}

}

```

Templates:

• templates/text-agents/agent-basic.ts
• templates/text-agents/agent-streaming.ts

---

Create specialized agents and route between them:

```typescript

const billingAgent = new Agent({

name: 'Billing',

handoffDescription: 'For billing and payment questions',

tools: [processRefundTool],

});

const techAgent = new Agent({

name: 'Technical',

handoffDescription: 'For technical issues',

tools: [createTicketTool],

});

const triageAgent = Agent.create({

name: 'Triage',

instructions: 'Route customers to the right specialist',

handoffs: [billingAgent, techAgent],

});

```

Templates:

• templates/text-agents/agent-handoffs.ts

References:

• references/agent-patterns.md - LLM vs code orchestration

---

Input Guardrails

Validate input before processing:

```typescript

const homeworkGuardrail: InputGuardrail = {

name: 'Homework Detection',

execute: async ({ input, context }) => {

const result = await run(guardrailAgent, input);

return {

tripwireTriggered: result.finalOutput.isHomework,

outputInfo: result.finalOutput,

};

},

};

const agent = new Agent({

inputGuardrails: [homeworkGuardrail],

});

```

Output Guardrails

Filter responses:

```typescript

const piiGuardrail: OutputGuardrail = {

name: 'PII Detection',

execute: async ({ agentOutput }) => {

const phoneRegex = /\b\d{3}[-. ]?\d{3}[-. ]?\d{4}\b/;

return {

tripwireTriggered: phoneRegex.test(agentOutput as string),

outputInfo: { detected: 'phone_number' },

};

},

};

```

Templates:

• templates/text-agents/agent-guardrails-input.ts
• templates/text-agents/agent-guardrails-output.ts

---

Require approval for specific actions:

```typescript

const refundTool = tool({

name: 'process_refund',

requiresApproval: true, // ← Requires human approval

execute: async ({ amount }) => {

return Refunded $${amount};

},

});

// Handle approval requests

let result = await runner.run(input);

while (result.interruption) {

if (result.interruption.type === 'tool_approval') {

const approved = await promptUser(result.interruption);

result = approved

? await result.state.approve(result.interruption)

: await result.state.reject(result.interruption);

}

}

```

Templates:

• templates/text-agents/agent-human-approval.ts

---

Creating Voice Agents

```typescript

import { RealtimeAgent, tool } from '@openai/agents-realtime';

const voiceAgent = new RealtimeAgent({

name: 'Voice Assistant',

instructions: 'Keep responses concise for voice',

tools: [weatherTool],

voice: 'alloy', // alloy, echo, fable, onyx, nova, shimmer

model: 'gpt-4o-realtime-preview',

});

```

Browser Session (React)

```typescript

import { RealtimeSession } from '@openai/agents-realtime';

const session = new RealtimeSession(voiceAgent, {

apiKey: sessionApiKey, // From your backend!

transport: 'webrtc', // or 'websocket'

});

session.on('connected', () => console.log('Connected'));

session.on('audio.transcription.completed', (e) => console.log('User:', e.transcript));

session.on('agent.audio.done', (e) => console.log('Agent:', e.transcript));

await session.connect();

```

CRITICAL: Never send your main OPENAI_API_KEY to the browser! Generate ephemeral session tokens server-side.

Voice Agent Handoffs

Voice agents support handoffs with constraints:

• Cannot change voice during handoff
• Cannot change model during handoff
• Conversation history automatically passed

```typescript

const specialist = new RealtimeAgent({

voice: 'nova', // Must match parent

/ ... /

});

const triageAgent = new RealtimeAgent({

voice: 'nova',

handoffs: [specialist],

});

```

Templates:

• templates/realtime-agents/realtime-agent-basic.ts
• templates/realtime-agents/realtime-session-browser.tsx
• templates/realtime-agents/realtime-handoffs.ts

References:

• references/realtime-transports.md - WebRTC vs WebSocket

---

Cloudflare Workers (Experimental)

```typescript

import { Agent, run } from '@openai/agents';

export default {

async fetch(request: Request, env: Env) {

const { message } = await request.json();

process.env.OPENAI_API_KEY = env.OPENAI_API_KEY;

const agent = new Agent({

name: 'Assistant',

instructions: 'Be helpful and concise',

model: 'gpt-4o-mini',

});

const result = await run(agent, message, {

maxTurns: 5,

});

return new Response(JSON.stringify({

response: result.finalOutput,

tokens: result.usage.totalTokens,

}), {

headers: { 'Content-Type': 'application/json' },

});

},

};

```

Limitations:

• No realtime voice agents
• CPU time limits (30s max)
• Memory constraints (128MB)

Templates:

• templates/cloudflare-workers/worker-text-agent.ts
• templates/cloudflare-workers/worker-agent-hono.ts

References:

• references/cloudflare-integration.md

Next.js App Router

```typescript

// app/api/agent/route.ts

import { NextRequest, NextResponse } from 'next/server';

import { Agent, run } from '@openai/agents';

export async function POST(request: NextRequest) {

const { message } = await request.json();

const agent = new Agent({

name: 'Assistant',

instructions: 'Be helpful',

});

const result = await run(agent, message);

return NextResponse.json({

response: result.finalOutput,

});

}

```

Templates:

• templates/nextjs/api-agent-route.ts
• templates/nextjs/api-realtime-route.ts

---

1. Zod Schema Type Errors

Error: Type errors with tool parameters.

Workaround: Define schemas inline.

```typescript

// ❌ Can cause type errors

parameters: mySchema

// ✅ Works reliably

parameters: z.object({ field: z.string() })

```

Source: [GitHub #188](https://github.com/openai/openai-agents-js/issues/188)

2. MCP Tracing Errors

Error: "No existing trace found" with MCP servers.

Workaround:

```typescript

import { initializeTracing } from '@openai/agents/tracing';

await initializeTracing();

```

Source: [GitHub #580](https://github.com/openai/openai-agents-js/issues/580)

3. MaxTurnsExceededError

Error: Agent loops infinitely.

Solution: Increase maxTurns or improve instructions:

```typescript

const result = await run(agent, input, {

maxTurns: 20, // Increase limit

});

// Or improve instructions

instructions: `After using tools, provide a final answer.

Do not loop endlessly.`

```

4. ToolCallError

Error: Tool execution fails.

Solution: Retry with exponential backoff:

```typescript

for (let attempt = 1; attempt <= 3; attempt++) {

try {

return await run(agent, input);

} catch (error) {

if (error instanceof ToolCallError && attempt < 3) {

await sleep(1000 * Math.pow(2, attempt - 1));

continue;

}

throw error;

}

}

```

5. Schema Mismatch

Error: Output doesn't match outputType.

Solution: Use stronger model or add validation instructions:

```typescript

const agent = new Agent({

model: 'gpt-4o', // More reliable than gpt-4o-mini

instructions: 'CRITICAL: Return JSON matching schema exactly',

outputType: mySchema,

});

```

All Errors: See references/common-errors.md

Template: templates/shared/error-handling.ts

---

LLM-Based

Agent decides routing autonomously:

```typescript

const manager = Agent.create({

instructions: 'Analyze request and route to appropriate agent',

handoffs: [agent1, agent2, agent3],

});

```

Pros: Adaptive, handles complexity

Cons: Less predictable, higher tokens

Code-Based

Explicit control flow:

```typescript

const summary = await run(summarizerAgent, text);

const sentiment = await run(sentimentAgent, summary.finalOutput);

if (sentiment.finalOutput.score < 0.3) {

await run(escalationAgent, text);

}

```

Pros: Predictable, lower cost

Cons: Less flexible

Parallel

Run multiple agents concurrently:

```typescript

const [summary, keywords, entities] = await Promise.all([

run(summarizerAgent, text),

run(keywordAgent, text),

run(entityAgent, text),

]);

```

Template: templates/text-agents/agent-parallel.ts

References: references/agent-patterns.md

---

Enable verbose logging:

```typescript

process.env.DEBUG = '@openai/agents:*';

```

Access execution details:

```typescript

const result = await run(agent, input);

console.log('Tokens:', result.usage.totalTokens);

console.log('Turns:', result.history.length);

console.log('Current Agent:', result.currentAgent?.name);

```

Template: templates/shared/tracing-setup.ts

---

✅ Use when:

• Building multi-agent workflows
• Creating voice AI applications
• Implementing tool-calling patterns
• Requiring input/output validation (guardrails)
• Needing human approval gates
• Orchestrating complex AI tasks
• Deploying to Cloudflare Workers or Next.js

❌ Don't use when:

• Simple OpenAI API calls (use openai-api skill instead)
• Non-OpenAI models exclusively
• Production voice at massive scale (consider LiveKit Agents)

---

• [ ] Set OPENAI_API_KEY as environment secret
• [ ] Implement error handling for all agent calls
• [ ] Add guardrails for safety-critical applications
• [ ] Enable tracing for debugging
• [ ] Set reasonable maxTurns to prevent runaway costs
• [ ] Use gpt-4o-mini where possible for cost efficiency
• [ ] Implement rate limiting
• [ ] Log token usage for cost monitoring
• [ ] Test handoff flows thoroughly
• [ ] Never expose API keys to browsers (use session tokens)

---

Estimated Savings: ~60%

| Task | Without Skill | With Skill | Savings |

|------|---------------|------------|---------|

| Multi-agent setup | ~12k tokens | ~5k tokens | 58% |

| Voice agent | ~10k tokens | ~4k tokens | 60% |

| Error debugging | ~8k tokens | ~3k tokens | 63% |

| Average | ~10k | ~4k | ~60% |

Errors Prevented: 9 documented issues = 100% error prevention

---

Text Agents (8):

1. agent-basic.ts - Simple agent with tools
2. agent-handoffs.ts - Multi-agent triage
3. agent-structured-output.ts - Zod schemas
4. agent-streaming.ts - Real-time events
5. agent-guardrails-input.ts - Input validation
6. agent-guardrails-output.ts - Output filtering
7. agent-human-approval.ts - HITL pattern
8. agent-parallel.ts - Concurrent execution

Realtime Agents (3):

1. realtime-agent-basic.ts - Voice setup
2. realtime-session-browser.tsx - React client
3. realtime-handoffs.ts - Voice delegation

Framework Integration (4):

1. worker-text-agent.ts - Cloudflare Workers
2. worker-agent-hono.ts - Hono framework
3. api-agent-route.ts - Next.js API
4. api-realtime-route.ts - Next.js voice

Utilities (2):

1. error-handling.ts - Comprehensive errors
2. tracing-setup.ts - Debugging

---

1. agent-patterns.md - Orchestration strategies
2. common-errors.md - 9 errors with workarounds
3. realtime-transports.md - WebRTC vs WebSocket
4. cloudflare-integration.md - Workers limitations
5. official-links.md - Documentation links

---

• Docs: https://openai.github.io/openai-agents-js/
• GitHub: https://github.com/openai/openai-agents-js
• npm: https://www.npmjs.com/package/@openai/agents
• Issues: https://github.com/openai/openai-agents-js/issues

---

Version: SDK v0.2.1

Last Verified: 2025-10-26

Skill Author: Jeremy Dawes (Jezweb)

Production Tested: Yes