Skip to main content Startseite Ersteller ovachiever droid-tings openai-agents
openai-agents Build AI applications with OpenAI Agents SDK - text agents, voice agents (realtime), multi-agent workflows with handoffs, tools with Zod schemas, input/output guardrails, structured outputs, and streaming. Deploy to Cloudflare Workers, Next.js, or React with human-in-the-loop patterns.
Use when: building text-based agents with tools and Zod schemas, creating realtime voice agents with WebRTC/WebSocket, implementing multi-agent workflows with handoffs between specialists, setting up input/output guardrails for safety, requiring human approval for critical actions, streaming agent responses, deploying agents to Cloudflare Workers or Next.js, or troubleshooting Zod schema type errors, MCP tracing failures, infinite loops (MaxTurnsExceededError), tool call failures, schema mismatches, or voice agent handoff constraints.
Zur Installation springen Skills Marktplatz Entdecken und erkunden Sie KI-Skills, die von der Community erstellt wurden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Prompt-Details anzeigen Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
npx skills add https://github.com/ovachiever/droid-tings --skill openai-agentsDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
ZIP herunterladen Herunterladen... Mehr aus diesem Repository
Build backend AI with Vercel AI SDK v5/v6. Covers v6 beta (Agent abstraction, tool approval, reranking),
v4→v5 migration (breaking changes), latest models (GPT-5/5.1, Claude 4.x, Gemini 2.5), Workers startup
fix, and 12 error solutions (AI_APICallError, AI_NoObjectGeneratedError, streamText silent errors).
Use when: implementing AI SDK v5/v6, migrating v4→v5, troubleshooting errors, fixing Workers startup
issues, or updating to latest models.
Build React chat interfaces with Vercel AI SDK v5/v6. Covers v6 beta (agent integration, tool approval,
auto-submit), v4→v5 migration (breaking changes), useChat/useCompletion/useObject/useAssistant hooks,
and 12 UI error solutions (stream parsing, stale body values, React update depth).
Use when: implementing AI SDK v5/v6 chat UIs, migrating v4→v5, troubleshooting "useChat failed to parse
stream", "useChat no response", or "stale body values" errors, or integrating OpenAI assistants.
Verwandte Berufe SOC
Basierend auf der SOC-Berufsklassifikation
name openai-agents description Build AI applications with OpenAI Agents SDK - text agents, voice agents (realtime), multi-agent workflows with handoffs, tools with Zod schemas, input/output guardrails, structured outputs, and streaming. Deploy to Cloudflare Workers, Next.js, or React with human-in-the-loop patterns.
Use when: building text-based agents with tools and Zod schemas, creating realtime voice agents with WebRTC/WebSocket, implementing multi-agent workflows with handoffs between specialists, setting up input/output guardrails for safety, requiring human approval for critical actions, streaming agent responses, deploying agents to Cloudflare Workers or Next.js, or troubleshooting Zod schema type errors, MCP tracing failures, infinite loops (MaxTurnsExceededError), tool call failures, schema mismatches, or voice agent handoff constraints.
license MIT metadata {"packages":["@openai/agents@0.2.1","@openai/agents-realtime@0.2.1","zod@^3.24.1"],"frameworks":["Cloudflare Workers","Next.js","React","Node.js","Hono"],"last_verified":"2025-10-26","production_tested":true,"token_savings":"~60%","errors_prevented":9}
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.
Installation & Setup
Install required packages:
npm install @openai/agents zod@3
npm install @openai/agents-realtime
Set environment variable:
export OPENAI_API_KEY="your-api-key"
Node.js 22+
Deno
Bun
Cloudflare Workers (experimental)
Core Concepts
1. Agents LLMs equipped with instructions and tools:
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:
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 const specialist = new Agent ({ });
const triageAgent = Agent .create ({
name : 'Triage' ,
instructions : 'Route to specialists' ,
handoffs : [specialist],
});
4. Guardrails Input/output validation for safety:
const agent = new Agent ({
inputGuardrails : [homeworkDetector],
outputGuardrails : [piiFilter],
});
5. Structured Outputs Type-safe responses with Zod:
const agent = new Agent ({
outputType : z.object ({
sentiment : z.enum (['positive' , 'negative' , 'neutral' ]),
confidence : z.number (),
}),
});
Text Agents
Basic Usage import { run } from '@openai/agents' ;
const result = await run (agent, 'What is 2+2?' );
console .log (result.finalOutput );
console .log (result.usage .totalTokens );
Streaming 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/text-agents/agent-basic.tstemplates/text-agents/agent-streaming.ts
Multi-Agent Handoffs Create specialized agents and route between them:
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/text-agents/agent-handoffs.ts
references/agent-patterns.md - LLM vs code orchestration
Guardrails
Input Guardrails Validate input before processing:
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 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/text-agents/agent-guardrails-input.tstemplates/text-agents/agent-guardrails-output.ts
Human-in-the-Loop Require approval for specific actions:
const refundTool = tool ({
name : 'process_refund' ,
requiresApproval : true ,
execute : async ({ amount }) => {
return `Refunded $${amount} ` ;
},
});
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/text-agents/agent-human-approval.ts
Realtime Voice Agents
Creating Voice Agents import { RealtimeAgent , tool } from '@openai/agents-realtime' ;
const voiceAgent = new RealtimeAgent ({
name : 'Voice Assistant' ,
instructions : 'Keep responses concise for voice' ,
tools : [weatherTool],
voice : 'alloy' ,
model : 'gpt-4o-realtime-preview' ,
});
Browser Session (React) import { RealtimeSession } from '@openai/agents-realtime' ;
const session = new RealtimeSession (voiceAgent, {
apiKey : sessionApiKey,
transport : 'webrtc' ,
});
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 handoffCannot change model during handoffConversation history automatically passed
const specialist = new RealtimeAgent ({
voice : 'nova' ,
});
const triageAgent = new RealtimeAgent ({
voice : 'nova' ,
handoffs : [specialist],
});
templates/realtime-agents/realtime-agent-basic.tstemplates/realtime-agents/realtime-session-browser.tsxtemplates/realtime-agents/realtime-handoffs.ts
references/realtime-transports.md - WebRTC vs WebSocket
Framework Integration
Cloudflare Workers (Experimental) 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' },
});
},
};
No realtime voice agents
CPU time limits (30s max)
Memory constraints (128MB)
templates/cloudflare-workers/worker-text-agent.tstemplates/cloudflare-workers/worker-agent-hono.ts
references/cloudflare-integration.md
Next.js App Router
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/nextjs/api-agent-route.tstemplates/nextjs/api-realtime-route.ts
Error Handling (9+ Errors Prevented)
1. Zod Schema Type Errors Error : Type errors with tool parameters.
Workaround : Define schemas inline.
parameters : mySchema
parameters : z.object ({ field : z.string () })
2. MCP Tracing Errors Error : "No existing trace found" with MCP servers.
import { initializeTracing } from '@openai/agents/tracing' ;
await initializeTracing ();
3. MaxTurnsExceededError Error : Agent loops infinitely.
Solution : Increase maxTurns or improve instructions:
const result = await run (agent, input, {
maxTurns : 20 ,
});
instructions : `After using tools, provide a final answer.
Do not loop endlessly.`
4. ToolCallError Error : Tool execution fails.
Solution : Retry with exponential backoff:
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:
const agent = new Agent ({
model : 'gpt-4o' ,
instructions : 'CRITICAL: Return JSON matching schema exactly' ,
outputType : mySchema,
});
All Errors : See references/common-errors.md
Template : templates/shared/error-handling.ts
Orchestration Patterns
LLM-Based Agent decides routing autonomously:
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 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:
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
Debugging & Tracing process.env .DEBUG = '@openai/agents:*' ;
Access execution details:
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
When to Use This Skill
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
Simple OpenAI API calls (use openai-api skill instead)
Non-OpenAI models exclusively
Production voice at massive scale (consider LiveKit Agents)
Production Checklist
Token Efficiency 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
Templates Index
agent-basic.ts - Simple agent with toolsagent-handoffs.ts - Multi-agent triageagent-structured-output.ts - Zod schemasagent-streaming.ts - Real-time eventsagent-guardrails-input.ts - Input validationagent-guardrails-output.ts - Output filteringagent-human-approval.ts - HITL patternagent-parallel.ts - Concurrent execution Realtime Agents (3):
9. realtime-agent-basic.ts - Voice setup
10. realtime-session-browser.tsx - React client
11. realtime-handoffs.ts - Voice delegation
Framework Integration (4):
12. worker-text-agent.ts - Cloudflare Workers
13. worker-agent-hono.ts - Hono framework
14. api-agent-route.ts - Next.js API
15. api-realtime-route.ts - Next.js voice
Utilities (2):
16. error-handling.ts - Comprehensive errors
17. tracing-setup.ts - Debugging
References
agent-patterns.md - Orchestration strategiescommon-errors.md - 9 errors with workaroundsrealtime-transports.md - WebRTC vs WebSocketcloudflare-integration.md - Workers limitationsofficial-links.md - Documentation links
Official Resources
Version : SDK v0.2.1
Last Verified : 2025-10-26
Skill Author : Jeremy Dawes (Jezweb)
Production Tested : Yes
