openai-agents

# OpenAI Agents SDK Skill

Complete skill for building AI applications with OpenAI Agents SDK (JavaScript/TypeScript), covering text agents, realtime voice agents, multi-agent workflows, and production deployment patterns.

---

## Quick Start

### Installation

```bash
bun add @openai/agents zod@3
bun add @openai/agents-realtime  # For voice agents
```

Set environment variable:

```bash
export OPENAI_API_KEY="your-api-key"
```

### Basic Text Agent

```typescript
import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are helpful.',
  tools: [tool({
    name: 'get_weather',
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => `Weather in ${city}: sunny`,
  })],
  model: 'gpt-4o-mini',
});

const result = await run(agent, 'What is the weather in SF?');
```

### Voice Agent & Multi-Agent

```typescript
// Voice agent
const voiceAgent = new RealtimeAgent({
  voice: 'alloy',
  model: 'gpt-4o-realtime-preview',
});

// Browser session
const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey, // From backend!
  transport: 'webrtc',
});

// Multi-agent handoffs
const triageAgent = Agent.create({
  handoffs: [billingAgent, techAgent],
});
```

**17 Templates**: `templates/` directory has production-ready examples for all patterns.

---

## Top 3 Critical Errors

### 1. Zod Schema Type Errors

**Error**: Type errors with tool parameters even when structurally compatible.

**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