Generate production-ready multi-agent workflows using the OpenAI Agents SDK. Supports handoffs, tools, guardrails, streaming, structured outputs, and realtime voice agents. Works with OpenAI and other LLM providers.
Generate production-ready multi-agent workflows using the @openai/agents SDK. This skill helps you build sophisticated agent systems with handoffs, tools, guardrails, structured outputs, streaming, and realtime voice capabilities.
Creates complete multi-agent workflow implementations using the OpenAI Agents SDK, including:
When the user requests an agent workflow, multi-agent system, or OpenAI Agents SDK implementation:
First, understand what the user wants to build:
Select the appropriate pattern:
**A. Simple Agent (single agent, optional tools)**
```typescript
import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';
const agent = new Agent({
name: 'AgentName',
instructions: 'Clear instructions about agent behavior',
tools: [/* optional tools */],
});
```
**B. Multi-Agent with Handoffs (specialized agents)**
```typescript
const specialistAgent = new Agent({
name: 'Specialist',
instructions: 'Specialized instructions',
handoffDescription: 'When to hand off to this agent',
tools: [/* specialist tools */],
});
const coordinatorAgent = Agent.create({
name: 'Coordinator',
instructions: 'Orchestration instructions',
handoffs: [specialistAgent],
});
```
**C. Structured Output Agent (JSON responses)**
```typescript
const agent = new Agent({
name: 'DataAgent',
instructions: 'Extract and structure information',
outputType: z.object({
field1: z.string(),
field2: z.number(),
}),
});
```
**D. Realtime Voice Agent (audio in/out)**
```typescript
import { RealtimeAgent, RealtimeSession } from '@openai/agents-realtime';
const voiceAgent = new RealtimeAgent({
name: 'VoiceAssistant',
instructions: 'Voice interaction instructions',
tools: [/* optional tools */],
voice: 'alloy', // or 'echo', 'shimmer', etc.
});
```
For each tool the agent needs:
```typescript
import { tool } from '@openai/agents';
import { z } from 'zod';
const toolName = tool({
name: 'tool_name',
description: 'Clear description of what this tool does',
parameters: z.object({
param1: z.string().describe('Parameter description'),
param2: z.number().optional(),
}),
execute: async (input) => {
// Tool implementation
// Return string or structured data
return result;
},
});
```
**Tool Best Practices:**
Set appropriate agent properties:
```typescript
const agent = new Agent({
name: 'AgentName', // Short, descriptive name
instructions: 'Detailed system instructions...', // Be specific about behavior, tone, constraints
model: 'gpt-4o', // Default; can use gpt-4o-mini, o1, etc.
tools: [/* tools array */],
handoffs: [/* other agents */],
handoffDescription: 'When this agent should receive control', // Only for agents that can be handed off to
outputType: /* Zod schema for structured output */,
parallelToolCalls: true, // Allow multiple tools to execute concurrently
temperature: 0.7, // Adjust for creativity vs consistency
});
```
**Basic execution:**
```typescript
const result = await run(agent, 'User input message');
console.log(result.finalOutput);
```
**With configuration:**
```typescript
const result = await run(agent, 'User input', {
maxTurns: 20, // Max iterations before timeout
context: { /* additional context */ },
modelParameters: { temperature: 0.5 },
});
```
**Streaming (for real-time output):**
```typescript
const stream = await run(agent, 'User input', { stream: true });
for await (const event of stream) {
if (event.type === 'agent:message') {
console.log(event.content);
} else if (event.type === 'tool:call') {
console.log(`Calling tool: ${event.toolName}`);
}
}
```
```typescript
import { Guardrail } from '@openai/agents';
const inputGuardrail = new Guardrail({
name: 'input_filter',
type: 'input',
check: async (input) => {
// Return true to allow, false to block
if (containsProhibitedContent(input)) {
throw new Error('Input rejected: prohibited content');
}
return true;
},
});
const agent = new Agent({
// ... other config
guardrails: [inputGuardrail],
});
```
Generate the necessary setup code:
**Installation:**
```bash
npm install @openai/agents zod
npm install @openai/agents-realtime
```
**Environment variables (.env):**
```
OPENAI_API_KEY=sk-...
OPENAI_TRACING_ENABLED=true
```
**TypeScript configuration (tsconfig.json):**
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true
}
}
```
```typescript
import { MaxTurnsExceededError, GuardrailTripwireTriggered } from '@openai/agents';
try {
const result = await run(agent, input, { maxTurns: 15 });
console.log(result.finalOutput);
} catch (error) {
if (error instanceof MaxTurnsExceededError) {
console.error('Agent exceeded maximum turns');
} else if (error instanceof GuardrailTripwireTriggered) {
console.error('Guardrail blocked:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
```
For browser-based voice agents:
```typescript
import { RealtimeAgent, RealtimeSession } from '@openai/agents-realtime';
// Server-side: generate ephemeral API key
// app.get('/api/session', async (req, res) => {
// const ephemeralKey = await generateEphemeralKey();
// res.json({ apiKey: ephemeralKey });
// });
// Client-side:
const voiceAgent = new RealtimeAgent({
name: 'VoiceAssistant',
instructions: 'You are a helpful voice assistant',
tools: [/* tools */],
voice: 'alloy',
modalities: ['audio', 'text'],
});
const session = new RealtimeSession(voiceAgent);
// Connect and start voice interaction
const { apiKey } = await fetch('/api/session').then(r => r.json());
await session.connect({ apiKey });
// Listen for events
session.on('message', (msg) => console.log('Agent said:', msg));
session.on('tool_call', (call) => console.log('Tool called:', call));
// Send text or audio
session.send({ type: 'message', text: 'Hello!' });
```
Create a README with:
```typescript
import { z } from 'zod';
import { Agent, run, tool } from '@openai/agents';
const weatherTool = tool({
name: 'get_weather',
description: 'Get current weather for a city',
parameters: z.object({ city: z.string() }),
execute: async (input) => {
// Call weather API
return `Weather in ${input.city}: 72°F, sunny`;
},
});
const weatherAgent = new Agent({
name: 'WeatherAgent',
instructions: 'You provide weather information',
handoffDescription: 'Transfer here for weather queries',
tools: [weatherTool],
});
const mainAgent = Agent.create({
name: 'MainAgent',
instructions: 'You are a helpful assistant. Hand off weather questions.',
handoffs: [weatherAgent],
});
const result = await run(mainAgent, 'What is the weather in Paris?');
console.log(result.finalOutput);
```
```typescript
const extractionAgent = new Agent({
name: 'DataExtractor',
instructions: 'Extract structured information from text',
outputType: z.object({
name: z.string(),
email: z.string().email(),
age: z.number().optional(),
}),
});
const result = await run(
extractionAgent,
'My name is Alice, email [email protected], and I am 30 years old'
);
console.log(result.finalOutput); // { name: 'Alice', email: '[email protected]', age: 30 }
```
```typescript
const searchTool = tool({
name: 'web_search',
description: 'Search the web',
parameters: z.object({ query: z.string() }),
execute: async (input) => { /* search implementation */ },
});
const analyzeTool = tool({
name: 'analyze_data',
description: 'Analyze data and generate insights',
parameters: z.object({ data: z.string() }),
execute: async (input) => { /* analysis implementation */ },
});
const researchAgent = new Agent({
name: 'Researcher',
instructions: 'Research topics and provide detailed analysis',
tools: [searchTool, analyzeTool],
parallelToolCalls: true, // Enable parallel execution
});
```
1. **Always install both @openai/agents and zod** - Zod is required for parameter schemas
2. **Set OPENAI_API_KEY** - Required unless using a custom model adapter
3. **Use Agent.create()** for multi-agent systems - Ensures proper type inference with handoffs
4. **Keep instructions clear and specific** - Agent behavior depends heavily on instruction quality
5. **Validate tool parameters with Zod** - Prevents runtime errors from malformed inputs
6. **Handle MaxTurnsExceededError** - Agent loops can timeout; always implement error handling
7. **Use @openai/agents-realtime for voice** - Separate package optimized for browser usage
8. **Test handoffs thoroughly** - Ensure handoffDescription clearly defines when to transfer control
9. **Enable tracing during development** - Essential for debugging multi-agent workflows
10. **Keep tool execution fast** - Long-running tools can cause timeouts; use async patterns
Provide the user with:
1. **Complete agent implementation** - Fully functional code with all agents, tools, and configuration
2. **package.json** - With correct dependencies (@openai/agents, zod, and any tool-specific packages)
3. **.env.example** - Template showing required environment variables
4. **README.md** - Setup instructions, usage examples, and architecture documentation
5. **Type definitions** (TypeScript) - Ensure all schemas and agent outputs are properly typed
6. **Error handling** - Comprehensive try-catch blocks for all error scenarios
7. **Example usage** - Working code snippets showing how to run the agents
8. **(Optional) Tests** - If requested, provide unit tests for tools and integration tests for agent flows
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/openai-agents-sdk-multi-agent-workflow-builder/raw