Openai Agents

{
  "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 ",
  "version": "1.0.0",
  "author": {
    "name": "Jeremy Dawes",
    "email": "jeremy@jezweb.net"
  },
  "license": "MIT",
  "repository": "https://github.com/jezweb/claude-skills",
  "keywords": []
}

MIT License

Copyright (c) 2025 Jeremy Dawes (Jezweb)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

#!/bin/bash
# Check if @openai/agents and @openai/agents-realtime are at recommended versions

echo "Checking OpenAI Agents SDK package versions..."
echo ""

# Expected versions
EXPECTED_AGENTS="0.2.1"
EXPECTED_REALTIME="0.2.1"
EXPECTED_ZOD="3"

# Check @openai/agents
echo "Checking @openai/agents..."
AGENTS_VERSION=$(npm view @openai/agents version 2>/dev/null)
if [ -z "$AGENTS_VERSION" ]; then
  echo "❌ @openai/agents not found on npm registry"
else
  echo "✅ Latest @openai/agents: $AGENTS_VERSION"
  if [ "$AGENTS_VERSION" != "$EXPECTED_AGENTS" ]; then
    echo "⚠️  Expected version: $EXPECTED_AGENTS"
    echo "   Consider updating skill templates if breaking changes exist"
  fi
fi
echo ""

# Check @openai/agents-realtime
echo "Checking @openai/agents-realtime..."
REALTIME_VERSION=$(npm view @openai/agents-realtime version 2>/dev/null)
if [ -z "$REALTIME_VERSION" ]; then
  echo "❌ @openai/agents-realtime not found on npm registry"
else
  echo "✅ Latest @openai/agents-realtime: $REALTIME_VERSION"
  if [ "$REALTIME_VERSION" != "$EXPECTED_REALTIME" ]; then
    echo "⚠️  Expected version: $EXPECTED_REALTIME"
    echo "   Consider updating skill templates if breaking changes exist"
  fi
fi
echo ""

# Check zod (peer dependency)
echo "Checking zod (peer dependency)..."
ZOD_VERSION=$(npm view zod version 2>/dev/null)
if [ -z "$ZOD_VERSION" ]; then
  echo "❌ zod not found on npm registry"
else
  echo "✅ Latest zod: $ZOD_VERSION"
  ZOD_MAJOR=$(echo "$ZOD_VERSION" | cut -d. -f1)
  if [ "$ZOD_MAJOR" != "$EXPECTED_ZOD" ]; then
    echo "⚠️  Expected major version: $EXPECTED_ZOD.x"
    echo "   Skill requires zod@3.x for schema validation"
  fi
fi
echo ""

echo "Version check complete!"
echo ""
echo "To update skill documentation:"
echo "  1. Update metadata.packages in SKILL.md frontmatter"
echo "  2. Update shared/package.json dependencies"
echo "  3. Re-test all templates"
echo "  4. Update metadata.last_verified date"

/**
 * Cloudflare Workers + Hono + OpenAI Agents
 *
 * Demonstrates:
 * - Integrating agents with Hono framework
 * - Multiple agent endpoints
 * - Streaming with Hono
 * - Type-safe routing
 */

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { z } from 'zod';
import { Agent, run, tool } from '@openai/agents';

// ========================================
// Agents
// ========================================

const summarizerAgent = new Agent({
  name: 'Summarizer',
  instructions: 'Summarize text concisely in 2-3 sentences.',
  model: 'gpt-4o-mini',
});

const translatorAgent = new Agent({
  name: 'Translator',
  instructions: 'Translate text accurately while preserving meaning and tone.',
  model: 'gpt-4o-mini',
});

const analyzerTool = tool({
  name: 'analyze_sentiment',
  description: 'Analyze sentiment',
  parameters: z.object({
    text: z.string(),
  }),
  execute: async ({ text }) => {
    // Simplified sentiment analysis
    const positive = ['good', 'great', 'excellent', 'love', 'amazing'];
    const negative = ['bad', 'terrible', 'hate', 'awful', 'poor'];

    const lowerText = text.toLowerCase();
    const posCount = positive.filter(w => lowerText.includes(w)).length;
    const negCount = negative.filter(w => lowerText.includes(w)).length;

    if (posCount > negCount) return 'Positive sentiment detected';
    if (negCount > posCount) return 'Negative sentiment detected';
    return 'Neutral sentiment detected';
  },
});

const analyzerAgent = new Agent({
  name: 'Analyzer',
  instructions: 'Analyze text for sentiment, tone, and key themes.',
  tools: [analyzerTool],
  model: 'gpt-4o-mini',
});

// ========================================
// Hono App
// ========================================

type Bindings = {
  OPENAI_API_KEY: string;
};

const app = new Hono<{ Bindings: Bindings }>();

// Enable CORS
app.use('/*', cors());

// Health check
app.get('/', (c) => {
  return c.json({
    service: 'OpenAI Agents API',
    version: '1.0.0',
    agents: ['summarizer', 'translator', 'analyzer'],
  });
});

// ========================================
// Summarizer Endpoint
// ========================================

app.post('/api/summarize', async (c) => {
  try {
    const { text } = await c.req.json();

    if (!text) {
      return c.json({ error: 'Missing text parameter' }, 400);
    }

    // Set API key from environment
    process.env.OPENAI_API_KEY = c.env.OPENAI_API_KEY;

    const result = await run(summarizerAgent, text);

    return c.json({
      summary: result.finalOutput,
      tokens: result.usage.totalTokens,
    });

  } catch (error: any) {
    return c.json({ error: error.message }, 500);
  }
});

// ========================================
// Translator Endpoint
// ========================================

app.post('/api/translate', async (c) => {
  try {
    const { text, targetLanguage } = await c.req.json();

    if (!text || !targetLanguage) {
      return c.json({ error: 'Missing required parameters' }, 400);
    }

    process.env.OPENAI_API_KEY = c.env.OPENAI_API_KEY;

    const result = await run(
      translatorAgent,
      `Translate the following to ${targetLanguage}: ${text}`
    );

    return c.json({
      translation: result.finalOutput,
      sourceLanguage: 'auto-detected',
      targetLanguage,
      tokens: result.usage.totalTokens,
    });

  } catch (error: any) {
    return c.json({ error: error.message }, 500);
  }
});

// ========================================
// Analyzer Endpoint (with Streaming)
// ========================================

app.post('/api/analyze', async (c) => {
  try {
    const { text, stream = false } = await c.req.json();

    if (!text) {
      return c.json({ error: 'Missing text parameter' }, 400);
    }

    process.env.OPENAI_API_KEY = c.env.OPENAI_API_KEY;

    // Non-streaming
    if (!stream) {
      const result = await run(analyzerAgent, `Analyze this text: ${text}`);
      return c.json({
        analysis: result.finalOutput,
        tokens: result.usage.totalTokens,
      });
    }

    // Streaming
    const streamResult = await run(analyzerAgent, `Analyze: ${text}`, {
      stream: true,
    });

    const { readable, writable } = new TransformStream();
    const writer = writable.getWriter();
    const encoder = new TextEncoder();

    // Stream in background
    (async () => {
      try {
        for await (const event of streamResult) {
          if (event.type === 'raw_model_stream_event') {
            const chunk = event.data?.choices?.[0]?.delta?.content || '';
            if (chunk) {
              await writer.write(encoder.encode(`data: ${JSON.stringify({ chunk })}\n\n`));
            }
          }
        }

        await streamResult.completed;
        await writer.write(encoder.encode(`data: ${JSON.stringify({ done: true })}\n\n`));
      } catch (error: any) {
        await writer.write(encoder.encode(`data: ${JSON.stringify({ error: error.message })}\n\n`));
      } finally {
        await writer.close();
      }
    })();

    return new Response(readable, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });

  } catch (error: any) {
    return c.json({ error: error.message }, 500);
  }
});

// ========================================
// Export Worker
// ========================================

export default app;

/**
 * Cloudflare Workers with OpenAI Agents SDK
 *
 * Demonstrates:
 * - Running text agents in Cloudflare Workers
 * - Handling agent requests via fetch()
 * - Streaming responses to clients
 * - Error handling in Workers environment
 *
 * NOTE: OpenAI Agents SDK has experimental Cloudflare Workers support
 * Some features may not work due to runtime limitations
 */

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

// ========================================
// Agent Definition
// ========================================

const searchTool = tool({
  name: 'search_docs',
  description: 'Search documentation',
  parameters: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    // In production, query a vector database or search API
    return `Found documentation about: ${query}`;
  },
});

const docsAgent = new Agent({
  name: 'Documentation Assistant',
  instructions: 'Help users find information in our documentation. Use the search tool when needed.',
  tools: [searchTool],
  model: 'gpt-4o-mini', // Use smaller model for cost efficiency
});

// ========================================
// Cloudflare Worker
// ========================================

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Handle CORS preflight
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      });
    }

    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 });
    }

    try {
      // Parse request body
      const { message, stream = false } = await request.json() as {
        message: string;
        stream?: boolean;
      };

      if (!message || typeof message !== 'string') {
        return new Response(JSON.stringify({ error: 'Invalid message' }), {
          status: 400,
          headers: { 'Content-Type': 'application/json' },
        });
      }

      // Set OPENAI_API_KEY from environment
      process.env.OPENAI_API_KEY = env.OPENAI_API_KEY;

      // ========================================
      // Non-Streaming Response
      // ========================================

      if (!stream) {
        const result = await run(docsAgent, message, {
          maxTurns: 5,
        });

        return new Response(JSON.stringify({
          response: result.finalOutput,
          agent: result.currentAgent?.name,
          tokens: result.usage.totalTokens,
        }), {
          headers: {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin': '*',
          },
        });
      }

      // ========================================
      // Streaming Response
      // ========================================

      const streamResult = await run(docsAgent, message, {
        stream: true,
        maxTurns: 5,
      });

      // Create readable stream for response
      const { readable, writable } = new TransformStream();
      const writer = writable.getWriter();
      const encoder = new TextEncoder();

      // Stream events to client
      (async () => {
        try {
          for await (const event of streamResult) {
            if (event.type === 'raw_model_stream_event') {
              const chunk = event.data?.choices?.[0]?.delta?.content || '';
              if (chunk) {
                await writer.write(encoder.encode(`data: ${JSON.stringify({ type: 'chunk', content: chunk })}\n\n`));
              }
            } else if (event.type === 'agent_updated_stream_event') {
              await writer.write(encoder.encode(`data: ${JSON.stringify({ type: 'agent_change', agent: event.agent.name })}\n\n`));
            }
          }

          await streamResult.completed;

          // Send final message
          await writer.write(encoder.encode(`data: ${JSON.stringify({
            type: 'done',
            tokens: streamResult.result.usage.totalTokens
          })}\n\n`));

        } catch (error: any) {
          await writer.write(encoder.encode(`data: ${JSON.stringify({ type: 'error', message: error.message })}\n\n`));
        } finally {
          await writer.close();
        }
      })();

      return new Response(readable, {
        headers: {
          'Content-Type': 'text/event-stream',
          'Cache-Control': 'no-cache',
          'Connection': 'keep-alive',
          'Access-Control-Allow-Origin': '*',
        },
      });

    } catch (error: any) {
      console.error('Worker error:', error);

      return new Response(JSON.stringify({
        error: error.message || 'Internal server error',
      }), {
        status: 500,
        headers: {
          'Content-Type': 'application/json',
          'Access-Control-Allow-Origin': '*',
        },
      });
    }
  },
};

// ========================================
// Environment Types
// ========================================

interface Env {
  OPENAI_API_KEY: string;
}

/**
 * Next.js App Router API Route with OpenAI Agents
 *
 * File: app/api/agent/route.ts
 *
 * Demonstrates:
 * - Creating API routes with agents
 * - Handling POST requests
 * - Streaming responses
 * - Error handling
 */

import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { Agent, run, tool } from '@openai/agents';

// ========================================
// Agent Definition
// ========================================

const searchTool = tool({
  name: 'search',
  description: 'Search for information',
  parameters: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    // Implement your search logic
    return `Search results for: ${query}`;
  },
});

const assistantAgent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant. Use the search tool when you need to find information.',
  tools: [searchTool],
  model: 'gpt-4o-mini',
});

// ========================================
// POST /api/agent
// ========================================

export async function POST(request: NextRequest) {
  try {
    // Parse request body
    const body = await request.json();
    const { message, stream = false } = body;

    if (!message || typeof message !== 'string') {
      return NextResponse.json(
        { error: 'Invalid message' },
        { status: 400 }
      );
    }

    // ========================================
    // Non-Streaming Response
    // ========================================

    if (!stream) {
      const result = await run(assistantAgent, message, {
        maxTurns: 5,
      });

      return NextResponse.json({
        response: result.finalOutput,
        agent: result.currentAgent?.name,
        tokens: result.usage.totalTokens,
        history: result.history.length,
      });
    }

    // ========================================
    // Streaming Response
    // ========================================

    const streamResult = await run(assistantAgent, message, {
      stream: true,
      maxTurns: 5,
    });

    // Create readable stream
    const encoder = new TextEncoder();

    const stream = new ReadableStream({
      async start(controller) {
        try {
          for await (const event of streamResult) {
            if (event.type === 'raw_model_stream_event') {
              const chunk = event.data?.choices?.[0]?.delta?.content || '';
              if (chunk) {
                controller.enqueue(
                  encoder.encode(`data: ${JSON.stringify({ type: 'chunk', content: chunk })}\n\n`)
                );
              }

            } else if (event.type === 'agent_updated_stream_event') {
              controller.enqueue(
                encoder.encode(`data: ${JSON.stringify({
                  type: 'agent_change',
                  agent: event.agent.name
                })}\n\n`)
              );

            } else if (event.type === 'run_item_stream_event') {
              if (event.name === 'tool_call') {
                controller.enqueue(
                  encoder.encode(`data: ${JSON.stringify({
                    type: 'tool_call',
                    name: (event.item as any).name,
                    arguments: (event.item as any).arguments,
                  })}\n\n`)
                );
              }
            }
          }

          await streamResult.completed;

          // Send completion event
          controller.enqueue(
            encoder.encode(`data: ${JSON.stringify({
              type: 'done',
              tokens: streamResult.result.usage.totalTokens
            })}\n\n`)
          );

          controller.close();

        } catch (error: any) {
          controller.enqueue(
            encoder.encode(`data: ${JSON.stringify({
              type: 'error',
              message: error.message
            })}\n\n`)
          );
          controller.close();
        }
      },
    });

    return new Response(stream, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });

  } catch (error: any) {
    console.error('API route error:', error);

    return NextResponse.json(
      { error: error.message || 'Internal server error' },
      { status: 500 }
    );
  }
}

// ========================================
// GET /api/agent (Info)
// ========================================

export async function GET() {
  return NextResponse.json({
    agent: assistantAgent.name,
    tools: assistantAgent.tools?.map((t: any) => t.name) || [],
    model: assistantAgent.model,
  });
}

/**
 * Next.js API Route for Realtime Voice Agent
 *
 * File: app/api/voice/session/route.ts
 *
 * Demonstrates:
 * - Generating ephemeral API keys for voice sessions
 * - Securing realtime agent access
 * - NEVER exposing main API key to clients
 *
 * CRITICAL: Never send your main OPENAI_API_KEY to the browser!
 * Use ephemeral session keys with short expiration.
 */

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

// ========================================
// POST /api/voice/session
// Generate ephemeral API key for voice session
// ========================================

export async function POST(request: NextRequest) {
  try {
    // Optional: Authenticate user first
    // const session = await getServerSession(authOptions);
    // if (!session) {
    //   return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    // }

    // Create OpenAI client with main API key (server-side only)
    const openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });

    // Generate ephemeral key
    // NOTE: As of 2025-10-26, OpenAI doesn't have a dedicated ephemeral key endpoint
    // You may need to use session tokens or implement your own proxy
    //
    // Recommended approach: Create a proxy that validates requests and
    // forwards to OpenAI API with your key server-side

    // For demonstration, we'll show the pattern:
    // In production, implement a secure proxy or use OpenAI's ephemeral keys when available

    // Option 1: Return a session token (your own implementation)
    const sessionToken = generateSecureSessionToken();

    // Store session token mapping to your API key in Redis/KV
    // await redis.set(`session:${sessionToken}`, process.env.OPENAI_API_KEY, {
    //   ex: 3600, // 1 hour expiration
    // });

    return NextResponse.json({
      sessionToken,
      expiresIn: 3600, // seconds
    });

    // Option 2: If OpenAI provides ephemeral keys API (future)
    // const ephemeralKey = await openai.ephemeralKeys.create({
    //   expiresIn: 3600,
    // });
    // return NextResponse.json({
    //   apiKey: ephemeralKey.key,
    //   expiresIn: ephemeralKey.expiresIn,
    // });

  } catch (error: any) {
    console.error('Session creation error:', error);

    return NextResponse.json(
      { error: 'Failed to create session' },
      { status: 500 }
    );
  }
}

// ========================================
// Helper: Generate Secure Session Token
// ========================================

function generateSecureSessionToken(): string {
  // Generate cryptographically secure random token
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
}

// ========================================
// Proxy Endpoint (Recommended Pattern)
// File: app/api/voice/proxy/route.ts
// ========================================

/**
 * This proxy validates session tokens and forwards requests to OpenAI API
 * This is the RECOMMENDED approach to avoid exposing your API key
 */

export async function POST_PROXY(request: NextRequest) {
  try {
    // Get session token from request
    const authHeader = request.headers.get('authorization');
    const sessionToken = authHeader?.replace('Bearer ', '');

    if (!sessionToken) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    }

    // Validate session token
    // const apiKey = await redis.get(`session:${sessionToken}`);
    // if (!apiKey) {
    //   return NextResponse.json({ error: 'Invalid session' }, { status: 401 });
    // }

    // Get the actual OpenAI API request from client
    const body = await request.json();

    // Forward to OpenAI API with server-side key
    const openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });

    // Forward request to OpenAI Realtime API
    // Implementation depends on the exact endpoint being called
    // This is a simplified example

    return NextResponse.json({
      message: 'Proxy implementation needed',
    });

  } catch (error: any) {
    return NextResponse.json(
      { error: 'Proxy error' },
      { status: 500 }
    );
  }
}

// ========================================
// Important Security Notes
// ========================================

/**
 * SECURITY CHECKLIST:
 *
 * 1. ✅ NEVER send OPENAI_API_KEY to browser
 * 2. ✅ Use ephemeral/session tokens with expiration
 * 3. ✅ Implement rate limiting per user/session
 * 4. ✅ Authenticate users before generating tokens
 * 5. ✅ Store session tokens in secure storage (Redis/KV)
 * 6. ✅ Log all voice session creation for monitoring
 * 7. ✅ Set maximum session duration (e.g., 1 hour)
 * 8. ✅ Implement cost controls and usage tracking
 *
 * RECOMMENDED ARCHITECTURE:
 *
 * Browser Client → Next.js Proxy → OpenAI API
 *     ↓
 * Session Token (never sees main API key)
 *
 * Alternative: Use OpenAI's official ephemeral key endpoint when available
 */

/**
 * Basic Realtime Voice Agent
 *
 * Demonstrates:
 * - Creating a realtime voice agent
 * - Defining tools for voice agents
 * - Configuring voice and instructions
 * - Understanding WebRTC vs WebSocket transports
 *
 * NOTE: This runs in the browser or in a Node.js environment with WebRTC support
 */

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

// ========================================
// Tools for Voice Agent
// ========================================

// Note: Tools for realtime agents execute in the client environment
// For sensitive operations, make HTTP requests to your backend

const checkWeatherTool = tool({
  name: 'check_weather',
  description: 'Check current weather for a city',
  parameters: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).optional().default('celsius'),
  }),
  execute: async ({ city, units }) => {
    // In production, call a real weather API
    const temp = Math.floor(Math.random() * 30) + 10;
    return `The weather in ${city} is sunny and ${temp}°${units === 'celsius' ? 'C' : 'F'}`;
  },
});

const setReminderTool = tool({
  name: 'set_reminder',
  description: 'Set a reminder for the user',
  parameters: z.object({
    message: z.string(),
    timeMinutes: z.number().describe('Minutes from now'),
  }),
  execute: async ({ message, timeMinutes }) => {
    // In production, save to database via API call
    console.log(`Reminder set: "${message}" in ${timeMinutes} minutes`);
    return `I'll remind you about "${message}" in ${timeMinutes} minutes`;
  },
});

const searchDocsTool = tool({
  name: 'search_docs',
  description: 'Search documentation',
  parameters: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    // In production, call your search API
    return `Found documentation about: ${query}`;
  },
});

// ========================================
// Create Realtime Voice Agent
// ========================================

const voiceAssistant = new RealtimeAgent({
  name: 'Voice Assistant',

  // Instructions for the agent's behavior
  instructions: `You are a friendly and helpful voice assistant.
  - Keep responses concise and conversational
  - Use natural speech patterns
  - When using tools, explain what you're doing
  - Be proactive in offering help`,

  // Tools available to the agent
  tools: [checkWeatherTool, setReminderTool, searchDocsTool],

  // Voice configuration (OpenAI voice options)
  voice: 'alloy', // Options: alloy, echo, fable, onyx, nova, shimmer

  // Model (realtime API uses specific models)
  model: 'gpt-4o-realtime-preview', // Default for realtime

  // Turn detection (when to consider user done speaking)
  turnDetection: {
    type: 'server_vad', // Voice Activity Detection on server
    threshold: 0.5, // Sensitivity (0-1)
    prefix_padding_ms: 300, // Audio before speech starts
    silence_duration_ms: 500, // Silence to end turn
  },

  // Additional configuration
  temperature: 0.7, // Response creativity (0-1)
  maxOutputTokens: 4096, // Maximum response length
});

// ========================================
// Example: Create Session (Node.js)
// ========================================

/**
 * For Node.js environments, you need to manually manage the session.
 * See realtime-session-browser.tsx for browser usage.
 */
async function createNodeSession() {
  // Note: WebRTC transport requires browser environment
  // For Node.js, use WebSocket transport

  const { OpenAIRealtimeWebSocket } = await import('@openai/agents-realtime');

  const transport = new OpenAIRealtimeWebSocket({
    apiKey: process.env.OPENAI_API_KEY,
  });

  // Create session
  const session = await voiceAssistant.createSession({
    transport,
  });

  // Handle events
  session.on('connected', () => {
    console.log('✅ Voice session connected');
  });

  session.on('disconnected', () => {
    console.log('🔌 Voice session disconnected');
  });

  session.on('error', (error) => {
    console.error('❌ Session error:', error);
  });

  // Audio transcription events
  session.on('audio.transcription.completed', (event) => {
    console.log('User said:', event.transcript);
  });

  session.on('agent.audio.done', (event) => {
    console.log('Agent said:', event.transcript);
  });

  // Tool call events
  session.on('tool.call', (event) => {
    console.log('Tool called:', event.name, event.arguments);
  });

  session.on('tool.result', (event) => {
    console.log('Tool result:', event.result);
  });

  // Connect to start session
  await session.connect();

  // To disconnect later
  // await session.disconnect();

  return session;
}

// ========================================
// Transport Options
// ========================================

/**
 * WebRTC Transport (recommended for browser)
 * - Lower latency
 * - Better for real-time voice
 * - Requires browser environment
 *
 * WebSocket Transport
 * - Works in Node.js
 * - Slightly higher latency
 * - Simpler setup
 */

// Uncomment to run in Node.js
// createNodeSession().catch(console.error);

export {
  voiceAssistant,
  checkWeatherTool,
  setReminderTool,
  searchDocsTool,
  createNodeSession,
};

/**
 * Realtime Agent Handoffs (Voice)
 *
 * Demonstrates:
 * - Multi-agent voice workflows
 * - Handoffs between voice agents
 * - Automatic conversation history passing
 * - Voice/model constraints during handoffs
 *
 * IMPORTANT: Unlike text agents, realtime agent handoffs have constraints:
 * - Cannot change voice during handoff
 * - Cannot change model during handoff
 * - Conversation history automatically passed
 */

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

// ========================================
// Specialized Agent Tools
// ========================================

const checkAccountTool = tool({
  name: 'check_account',
  description: 'Look up account information',
  parameters: z.object({
    accountId: z.string(),
  }),
  execute: async ({ accountId }) => {
    return `Account ${accountId}: Premium tier, billing current, last login: 2025-10-20`;
  },
});

const processPaymentTool = tool({
  name: 'process_payment',
  description: 'Process a payment',
  parameters: z.object({
    accountId: z.string(),
    amount: z.number(),
  }),
  execute: async ({ accountId, amount }) => {
    return `Payment of $${amount} processed for account ${accountId}`;
  },
});

const checkSystemTool = tool({
  name: 'check_system',
  description: 'Check system status',
  parameters: z.object({}),
  execute: async () => {
    return 'All systems operational: API ✅, Database ✅, CDN ✅';
  },
});

const createTicketTool = tool({
  name: 'create_ticket',
  description: 'Create support ticket',
  parameters: z.object({
    title: z.string(),
    priority: z.enum(['low', 'medium', 'high']),
  }),
  execute: async ({ title, priority }) => {
    const id = `TICKET-${Math.floor(Math.random() * 10000)}`;
    return `Created ${priority} priority ticket ${id}: ${title}`;
  },
});

// ========================================
// Specialized Voice Agents
// ========================================

const billingAgent = new RealtimeAgent({
  name: 'Billing Specialist',
  instructions: `You handle billing and payment questions.
  - Be professional and empathetic
  - Explain charges clearly
  - Process payments when requested
  - Keep responses concise for voice`,
  handoffDescription: 'Transfer for billing, payments, or account questions',
  tools: [checkAccountTool, processPaymentTool],
  voice: 'nova', // All agents must use same voice as parent
});

const technicalAgent = new RealtimeAgent({
  name: 'Technical Support',
  instructions: `You handle technical issues and system problems.
  - Diagnose issues systematically
  - Provide clear troubleshooting steps
  - Create tickets for complex issues
  - Use simple language for voice`,
  handoffDescription: 'Transfer for technical problems, bugs, or system issues',
  tools: [checkSystemTool, createTicketTool],
  voice: 'nova', // Must match triage agent voice
});

// ========================================
// Triage Agent (Entry Point)
// ========================================

const triageVoiceAgent = new RealtimeAgent({
  name: 'Customer Service',
  instructions: `You are the first point of contact.
  - Greet customers warmly
  - Understand their issue
  - Route to the right specialist
  - Explain the transfer before handing off`,
  handoffs: [billingAgent, technicalAgent],
  voice: 'nova', // This voice will be used by all agents
  model: 'gpt-4o-realtime-preview', // This model will be used by all agents
});

// ========================================
// Important Notes about Voice Handoffs
// ========================================

/**
 * KEY DIFFERENCES from text agent handoffs:
 *
 * 1. VOICE CONSTRAINT
 *    - All agents in a handoff chain must use the same voice
 *    - Voice is set by the initial agent
 *    - Cannot change voice during handoff
 *
 * 2. MODEL CONSTRAINT
 *    - All agents must use the same model
 *    - Model is set by the initial agent
 *    - Cannot change model during handoff
 *
 * 3. AUTOMATIC HISTORY
 *    - Conversation history automatically passed to delegated agent
 *    - No need to manually manage context
 *    - Specialist agents can see full conversation
 *
 * 4. SEAMLESS AUDIO
 *    - Audio stream continues during handoff
 *    - User doesn't need to reconnect
 *    - Tools execute in same session
 */

// ========================================
// Example: Create Session with Handoffs
// ========================================

async function createVoiceSessionWithHandoffs() {
  const { OpenAIRealtimeWebSocket } = await import('@openai/agents-realtime');

  const transport = new OpenAIRealtimeWebSocket({
    apiKey: process.env.OPENAI_API_KEY,
  });

  const session = await triageVoiceAgent.createSession({
    transport,
  });

  // Track which agent is currently active
  let currentAgent = 'Customer Service';

  session.on('connected', () => {
    console.log('✅ Voice session connected');
    console.log('🎙️  Current agent:', currentAgent);
  });

  // Listen for agent changes (handoffs)
  session.on('agent.changed', (event: any) => {
    currentAgent = event.agent.name;
    console.log('\n🔄 HANDOFF to:', currentAgent);
  });

  session.on('audio.transcription.completed', (event) => {
    console.log(`👤 User: ${event.transcript}`);
  });

  session.on('agent.audio.done', (event) => {
    console.log(`🤖 ${currentAgent}: ${event.transcript}`);
  });

  session.on('tool.call', (event) => {
    console.log(`\n🛠️  Tool: ${event.name}`);
    console.log(`   Arguments:`, event.arguments);
  });

  session.on('tool.result', (event) => {
    console.log(`✅ Result:`, event.result, '\n');
  });

  await session.connect();

  console.log('\n💡 Try saying:');
  console.log('  - "I have a question about my bill"');
  console.log('  - "The API is returning errors"');
  console.log('  - "I need to update my payment method"');
  console.log('\n');

  return session;
}

// ========================================
// Example: Manual Handoff Triggering
// ========================================

/**
 * While handoffs usually happen automatically via LLM routing,
 * you can also programmatically trigger them if needed via
 * backend delegation patterns (see agent-patterns.md reference).
 */

// Uncomment to run
// createVoiceSessionWithHandoffs().catch(console.error);

export {
  triageVoiceAgent,
  billingAgent,
  technicalAgent,
  createVoiceSessionWithHandoffs,
};

/**
 * Realtime Voice Session - React Browser Client
 *
 * Demonstrates:
 * - Creating a voice session in the browser
 * - Using WebRTC transport for low latency
 * - Handling audio I/O automatically
 * - Managing session lifecycle
 * - Displaying transcripts and tool calls
 *
 * IMPORTANT: Generate ephemeral API keys server-side, never expose your main API key
 */

import React, { useState, useEffect, useRef } from 'react';
import { RealtimeSession, RealtimeAgent } from '@openai/agents-realtime';
import { z } from 'zod';

// ========================================
// Voice Agent Definition
// ========================================

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

const weatherTool = tool({
  name: 'get_weather',
  description: 'Get weather for a city',
  parameters: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => {
    // Call your backend API
    const response = await fetch(`/api/weather?city=${city}`);
    const data = await response.json();
    return data.weather;
  },
});

const voiceAgent = new RealtimeAgent({
  name: 'Voice Assistant',
  instructions: 'You are a helpful voice assistant. Keep responses concise and friendly.',
  tools: [weatherTool],
  voice: 'alloy',
});

// ========================================
// React Component
// ========================================

interface Message {
  role: 'user' | 'assistant';
  content: string;
  timestamp: Date;
}

interface ToolCall {
  name: string;
  arguments: Record<string, any>;
  result?: any;
}

export function VoiceAssistant() {
  const [isConnected, setIsConnected] = useState(false);
  const [isListening, setIsListening] = useState(false);
  const [messages, setMessages] = useState<Message[]>([]);
  const [toolCalls, setToolCalls] = useState<ToolCall[]>([]);
  const [error, setError] = useState<string | null>(null);

  const sessionRef = useRef<RealtimeSession | null>(null);

  // ========================================
  // Initialize Session
  // ========================================

  useEffect(() => {
    let session: RealtimeSession;

    async function initSession() {
      try {
        // Get ephemeral API key from your backend
        const response = await fetch('/api/generate-session-key');
        const { apiKey } = await response.json();

        // Create session with WebRTC transport (low latency)
        session = new RealtimeSession(voiceAgent, {
          apiKey,
          transport: 'webrtc', // or 'websocket'
        });

        sessionRef.current = session;

        // ========================================
        // Session Event Handlers
        // ========================================

        session.on('connected', () => {
          console.log('✅ Connected to voice session');
          setIsConnected(true);
          setError(null);
        });

        session.on('disconnected', () => {
          console.log('🔌 Disconnected from voice session');
          setIsConnected(false);
          setIsListening(false);
        });

        session.on('error', (err) => {
          console.error('❌ Session error:', err);
          setError(err.message);
        });

        // ========================================
        // Transcription Events
        // ========================================

        session.on('audio.transcription.completed', (event) => {
          // User finished speaking
          setMessages(prev => [...prev, {
            role: 'user',
            content: event.transcript,
            timestamp: new Date(),
          }]);
          setIsListening(false);
        });

        session.on('audio.transcription.started', () => {
          // User started speaking
          setIsListening(true);
        });

        session.on('agent.audio.done', (event) => {
          // Agent finished speaking
          setMessages(prev => [...prev, {
            role: 'assistant',
            content: event.transcript,
            timestamp: new Date(),
          }]);
        });

        // ========================================
        // Tool Call Events
        // ========================================

        session.on('tool.call', (event) => {
          console.log('🛠️  Tool call:', event.name, event.arguments);
          setToolCalls(prev => [...prev, {
            name: event.name,
            arguments: event.arguments,
          }]);
        });

        session.on('tool.result', (event) => {
          console.log('✅ Tool result:', event.result);
          setToolCalls(prev => prev.map(tc =>
            tc.name === event.name
              ? { ...tc, result: event.result }
              : tc
          ));
        });

        // Connect to start session
        await session.connect();

      } catch (err: any) {
        console.error('Failed to initialize session:', err);
        setError(err.message);
      }
    }

    initSession();

    // Cleanup on unmount
    return () => {
      if (session) {
        session.disconnect();
      }
    };
  }, []);

  // ========================================
  // Manual Control Functions
  // ========================================

  const handleInterrupt = () => {
    if (sessionRef.current) {
      sessionRef.current.interrupt();
    }
  };

  const handleDisconnect = () => {
    if (sessionRef.current) {
      sessionRef.current.disconnect();
    }
  };

  // ========================================
  // Render UI
  // ========================================

  return (
    <div className="voice-assistant">
      <div className="status-bar">
        <div className={`status ${isConnected ? 'connected' : 'disconnected'}`}>
          {isConnected ? '🟢 Connected' : '🔴 Disconnected'}
        </div>
        {isListening && <div className="listening">🎤 Listening...</div>}
      </div>

      {error && (
        <div className="error">
          ❌ Error: {error}
        </div>
      )}

      <div className="messages">
        {messages.map((msg, i) => (
          <div key={i} className={`message ${msg.role}`}>
            <div className="role">{msg.role === 'user' ? '👤' : '🤖'}</div>
            <div className="content">
              <p>{msg.content}</p>
              <span className="timestamp">
                {msg.timestamp.toLocaleTimeString()}
              </span>
            </div>
          </div>
        ))}
      </div>

      {toolCalls.length > 0 && (
        <div className="tool-calls">
          <h3>🛠️ Tool Calls</h3>
          {toolCalls.map((tc, i) => (
            <div key={i} className="tool-call">
              <strong>{tc.name}</strong>
              <pre>{JSON.stringify(tc.arguments, null, 2)}</pre>
              {tc.result && (
                <div className="result">
                  Result: {JSON.stringify(tc.result)}
                </div>
              )}
            </div>
          ))}
        </div>
      )}

      <div className="controls">
        <button
          onClick={handleInterrupt}
          disabled={!isConnected}
        >
          ⏸️ Interrupt
        </button>
        <button
          onClick={handleDisconnect}
          disabled={!isConnected}
        >
          🔌 Disconnect
        </button>
      </div>

      <style jsx>{`
        .voice-assistant {
          max-width: 600px;
          margin: 0 auto;
          padding: 20px;
        }
        .status-bar {
          display: flex;
          gap: 20px;
          margin-bottom: 20px;
        }
        .status {
          padding: 8px 16px;
          border-radius: 20px;
          font-size: 14px;
        }
        .status.connected {
          background: #d4edda;
          color: #155724;
        }
        .status.disconnected {
          background: #f8d7da;
          color: #721c24;
        }
        .listening {
          padding: 8px 16px;
          background: #fff3cd;
          color: #856404;
          border-radius: 20px;
          font-size: 14px;
        }
        .error {
          padding: 12px;
          background: #f8d7da;
          color: #721c24;
          border-radius: 8px;
          margin-bottom: 20px;
        }
        .messages {
          height: 400px;
          overflow-y: auto;
          border: 1px solid #ddd;
          border-radius: 8px;
          padding: 16px;
          margin-bottom: 20px;
        }
        .message {
          display: flex;
          gap: 12px;
          margin-bottom: 16px;
        }
        .message.user {
          justify-content: flex-end;
        }
        .content {
          max-width: 70%;
          padding: 12px;
          border-radius: 12px;
        }
        .message.user .content {
          background: #007bff;
          color: white;
        }
        .message.assistant .content {
          background: #f1f3f4;
          color: #000;
        }
        .timestamp {
          font-size: 11px;
          opacity: 0.6;
        }
        .tool-calls {
          margin-bottom: 20px;
          padding: 12px;
          background: #f8f9fa;
          border-radius: 8px;
        }
        .tool-call {
          margin: 8px 0;
          padding: 8px;
          background: white;
          border-radius: 4px;
        }
        .controls {
          display: flex;
          gap: 12px;
        }
        button {
          flex: 1;
          padding: 12px;
          border: none;
          border-radius: 8px;
          background: #007bff;
          color: white;
          cursor: pointer;
        }
        button:disabled {
          background: #ccc;
          cursor: not-allowed;
        }
        button:hover:not(:disabled) {
          background: #0056b3;
        }
      `}</style>
    </div>
  );
}

export default VoiceAssistant;

/**
 * Comprehensive error handling patterns for OpenAI Agents SDK
 *
 * Covers all major error types:
 * - MaxTurnsExceededError: Agent hit maximum turns limit
 * - InputGuardrailTripwireTriggered: Input blocked by guardrail
 * - OutputGuardrailTripwireTriggered: Output blocked by guardrail
 * - ToolCallError: Tool execution failed
 * - ModelBehaviorError: Unexpected model behavior
 * - GuardrailExecutionError: Guardrail itself failed
 */

import {
  Agent,
  run,
  MaxTurnsExceededError,
  InputGuardrailTripwireTriggered,
  OutputGuardrailTripwireTriggered,
  ModelBehaviorError,
  ToolCallError,
  GuardrailExecutionError,
} from '@openai/agents';

/**
 * Run agent with comprehensive error handling and retry logic
 */
export async function runAgentWithErrorHandling(
  agent: Agent,
  input: string,
  options: {
    maxRetries?: number;
    maxTurns?: number;
    onError?: (error: Error, attempt: number) => void;
  } = {}
) {
  const { maxRetries = 3, maxTurns = 10, onError } = options;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await run(agent, input, { maxTurns });
      return result;

    } catch (error) {
      // Notify error callback
      if (onError) {
        onError(error as Error, attempt);
      }

      // Handle specific error types
      if (error instanceof MaxTurnsExceededError) {
        console.error('❌ Agent exceeded maximum turns');
        console.error(`   Agent entered an infinite loop after ${maxTurns} turns`);
        throw error; // Don't retry - this is a logic issue

      } else if (error instanceof InputGuardrailTripwireTriggered) {
        console.error('❌ Input blocked by guardrail');
        console.error('   Reason:', error.outputInfo);
        throw error; // Don't retry - input is invalid

      } else if (error instanceof OutputGuardrailTripwireTriggered) {
        console.error('❌ Output blocked by guardrail');
        console.error('   Reason:', error.outputInfo);
        throw error; // Don't retry - output violates policy

      } else if (error instanceof ToolCallError) {
        console.error(`⚠️  Tool call failed (attempt ${attempt}/${maxRetries})`);
        console.error('   Tool:', error.toolName);
        console.error('   Error:', error.message);

        if (attempt === maxRetries) {
          throw error; // Give up after max retries
        }

        // Exponential backoff
        const delay = 1000 * Math.pow(2, attempt - 1);
        console.log(`   Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));

      } else if (error instanceof ModelBehaviorError) {
        console.error('❌ Unexpected model behavior');
        console.error('   Details:', error.message);
        throw error; // Don't retry - model is behaving incorrectly

      } else if (error instanceof GuardrailExecutionError) {
        console.error('❌ Guardrail execution failed');
        console.error('   Guardrail:', error.guardrailName);
        console.error('   Error:', error.message);

        // Option to retry with fallback guardrail
        // See common-errors.md for fallback pattern
        throw error;

      } else {
        // Unknown error - retry with exponential backoff
        console.error(`⚠️  Unknown error (attempt ${attempt}/${maxRetries})`);
        console.error('   Error:', error);

        if (attempt === maxRetries) {
          throw error;
        }

        const delay = 1000 * Math.pow(2, attempt - 1);
        console.log(`   Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw new Error('Max retries exceeded');
}

/**
 * Example usage
 */
export async function exampleUsage() {
  const agent = new Agent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
  });

  try {
    const result = await runAgentWithErrorHandling(
      agent,
      'What is 2+2?',
      {
        maxRetries: 3,
        maxTurns: 10,
        onError: (error, attempt) => {
          console.log(`Error on attempt ${attempt}:`, error.message);
        },
      }
    );

    console.log('✅ Success:', result.finalOutput);
    console.log('Tokens used:', result.usage.totalTokens);

  } catch (error) {
    console.error('❌ Final error:', error);
    process.exit(1);
  }
}

// Uncomment to run example
// exampleUsage();

{
  "name": "openai-agents-templates",
  "version": "1.0.0",
  "description": "OpenAI Agents SDK templates for Claude Code skill",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@openai/agents": "^0.2.1",
    "@openai/agents-realtime": "^0.2.1",
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "@types/node": "^22.10.2",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  },
  "engines": {
    "node": ">=22.0.0"
  }
}

/**
 * Tracing and debugging configuration for OpenAI Agents SDK
 *
 * Built-in tracing helps visualize agent execution:
 * - Agent transitions (handoffs)
 * - Tool calls
 * - LLM requests
 * - Guardrail executions
 * - Token usage
 *
 * Tracing is automatically enabled when you import from '@openai/agents'
 */

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

/**
 * Enable detailed logging for debugging
 */
export function enableVerboseLogging() {
  // Set environment variable for debug mode
  process.env.DEBUG = '@openai/agents:*';
}

/**
 * Run agent with detailed trace logging
 */
export async function runWithTracing(agent: Agent, input: string) {
  console.log('🔍 Starting traced agent execution...\n');

  const result = await run(agent, input);

  // Log execution summary
  console.log('\n📊 Execution Summary:');
  console.log('─────────────────────────────────────');
  console.log('Final Output:', result.finalOutput);
  console.log('Current Agent:', result.currentAgent?.name || 'N/A');
  console.log('Total Tokens:', result.usage.totalTokens);
  console.log('Input Tokens:', result.usage.inputTokens);
  console.log('Output Tokens:', result.usage.outputTokens);
  console.log('Conversation Turns:', result.history.length);
  console.log('─────────────────────────────────────\n');

  // Log conversation history
  console.log('💬 Conversation History:');
  result.history.forEach((message, index) => {
    console.log(`\n[${index + 1}] ${message.role}:`);
    if (message.role === 'user' || message.role === 'assistant') {
      console.log(message.content);
    } else if (message.role === 'tool') {
      console.log(`  Tool: ${message.name}`);
      console.log(`  Result:`, message.result);
    }
  });

  return result;
}

/**
 * Stream agent execution with event logging
 */
export async function runWithStreamTracing(agent: Agent, input: string) {
  console.log('🔍 Starting streamed agent execution...\n');

  const stream = await run(agent, input, { stream: true });

  for await (const event of stream) {
    if (event.type === 'raw_model_stream_event') {
      // Raw model response chunk
      const chunk = event.data?.choices?.[0]?.delta?.content || '';
      if (chunk) {
        process.stdout.write(chunk);
      }

    } else if (event.type === 'agent_updated_stream_event') {
      // Agent handoff occurred
      console.log(`\n🔄 Handoff to: ${event.agent.name}`);

    } else if (event.type === 'run_item_stream_event') {
      // Tool call, output, or other run item
      if (event.name === 'tool_call') {
        console.log(`\n🛠️  Tool call: ${event.item.name}`);
        console.log(`   Arguments:`, event.item.arguments);
      } else if (event.name === 'tool_result') {
        console.log(`✅ Tool result:`, event.item.result);
      }
    }
  }

  // Wait for completion
  await stream.completed;
  const result = stream.result;

  console.log('\n\n📊 Stream Summary:');
  console.log('─────────────────────────────────────');
  console.log('Total Tokens:', result.usage.totalTokens);
  console.log('─────────────────────────────────────\n');

  return result;
}

/**
 * Example: Debug a complex multi-agent workflow
 */
export async function exampleTracedWorkflow() {
  // Enable verbose logging
  enableVerboseLogging();

  const agent = new Agent({
    name: 'Debug Agent',
    instructions: 'You are a debugging assistant.',
  });

  // Run with tracing
  await runWithTracing(
    agent,
    'Explain how to debug a TypeScript application'
  );

  // Run with stream tracing
  await runWithStreamTracing(
    agent,
    'What are the best debugging tools for Node.js?'
  );
}

// Uncomment to run example
// exampleTracedWorkflow();