OpenAI Agents SDK 2026: Building Production-Ready AI Agents

**1. Agent** The Agent is the core abstraction of the SDK, encapsulating the LLM, tools, and context. ```typescript import { Agent, Tool, Context } from '@openai/agents-sdk'; // Create an agent const agent = new Agent({ name: 'customer-support', model: 'gpt-4-turbo', instructions: 'You are a professional customer support assistant...', tools: [ new Tool({ name: 'search_knowledge_base', description: 'Search the knowledge base', parameters: { query: { type: 'string', description: 'Search query' }, }, execute: async ({ query }) => { return await searchKnowledgeBase(query); }, }), new Tool({ name: 'create_ticket', description: 'Create a support ticket', parameters: { title: { type: 'string' }, description: { type: 'string' }, priority: { type: 'string', enum: ['low', 'medium', 'high'] }, }, execute: async (params) => { return await createTicket(params); }, }), ], }); // Run the agent const response = await agent.run({ input: 'I cannot log into my account', context: { userId: 'user_123' }, }); console.log(response.output); console.log(response.toolCalls); ``` **2. Tool** Tools are the interface for agents to interact with the external world. ```typescript import { Tool, Parameter } from '@openai/agents-sdk'; // Define a complex tool const weatherTool = new Tool({ name: 'get_weather', description: 'Get weather information for a specified city', parameters: { city: new Parameter({ type: 'string', description: 'City name', required: true, }), units: new Parameter({ type: 'string', description: 'Temperature unit', enum: ['celsius', 'fahrenheit'], default: 'celsius', }), }, execute: async ({ city, units }) => { const response = await fetch( `https://api.weather.com/v1/current/${city}?units=${units}` ); const data = await response.json(); return { temperature: data.temperature, condition: data.condition, humidity: data.humidity, wind_speed: data.wind_speed, }; }, }); // Tool validation const validatedTool = weatherTool.validate({ city: 'Beijing', units: 'celsius', }); if (validatedTool.isValid) { const result = await weatherTool.execute(validatedTool.params); } ``` **3. Context** Context manages the agent's state and memory. ```typescript import { Context, Memory } from '@openai/agents-sdk'; // Create context const context = new Context({ userId: 'user_123', sessionId: 'session_456', metadata: { plan: 'premium', language: 'en-US', }, }); // Add memory context.memory.add({ role: 'user', content: 'I prefer using TypeScript', timestamp: Date.now(), }); // Retrieve relevant memories const relevantMemories = await context.memory.search('programming language preference', { topK: 5, threshold: 0.7, }); // Persist context await context.save(); // Restore context const restoredContext = await Context.load('session_456'); ``` Try our [JSON Formatter](/tools/json-formatter) to debug configurations.

**Pattern 1: Layered Agent Architecture** ```typescript import { Agent, Router, Orchestrator } from '@openai/agents-sdk'; // Router layer: decides which specialized agent to send the request to const router = new Router({ name: 'request-router', model: 'gpt-3.5-turbo', instructions: 'Route user requests to the appropriate agent based on type', agents: { 'technical-support': techSupportAgent, 'billing': billingAgent, 'sales': salesAgent, 'general': generalAgent, }, classify: async (input) => { const response = await router.llm.classify(input, { categories: Object.keys(router.agents), }); return response.category; }, }); // Orchestrator layer: coordinates multiple agents to complete complex tasks const orchestrator = new Orchestrator({ name: 'task-orchestrator', agents: [ researchAgent, analysisAgent, writingAgent, reviewAgent, ], workflow: async (task, agents) => { // 1. Research phase const research = await agents.research.execute(task); // 2. Analysis phase const analysis = await agents.analysis.execute(research.output); // 3. Writing phase const draft = await agents.writing.execute(analysis.output); // 4. Review phase const review = await agents.review.execute(draft.output); return review.output; }, }); // Use the orchestrator const result = await orchestrator.run({ task: 'Write an article about AI trends', }); ``` **Pattern 2: State Machine Agent** ```typescript import { StateMachineAgent, State, Transition } from '@openai/agents-sdk'; // Define states const states = { idle: new State({ name: 'idle', onEnter: async (context) => { console.log('Waiting for user input...'); }, }), collecting: new State({ name: 'collecting', onEnter: async (context) => { await context.agent.say('Please provide more information'); }, }), processing: new State({ name: 'processing', onEnter: async (context) => { const result = await processRequest(context.data); context.set('result', result); }, }), confirming: new State({ name: 'confirming', onEnter: async (context) => { const result = context.get('result'); await context.agent.say(`Processing result: ${result}\nConfirm?`); }, }), completed: new State({ name: 'completed', onEnter: async (context) => { await context.agent.say('Task completed!'); }, }), }; // Define transitions const transitions = [ new Transition({ from: 'idle', to: 'collecting', condition: (input) => input.includes('need help'), }), new Transition({ from: 'collecting', to: 'processing', condition: (input, context) => context.hasRequiredData(), }), new Transition({ from: 'processing', to: 'confirming', condition: () => true, }), new Transition({ from: 'confirming', to: 'completed', condition: (input) => input.toLowerCase().includes('confirm'), }), new Transition({ from: 'confirming', to: 'collecting', condition: (input) => input.toLowerCase().includes('modify'), }), ]; // Create state machine agent const fsmAgent = new StateMachineAgent({ name: 'order-processor', states, transitions, initialState: 'idle', }); // Run state machine await fsmAgent.run({ input: 'I need help processing my order', }); ``` **Pattern 3: Multi-Agent Collaboration** ```typescript import { MultiAgentSystem, Agent, Message } from '@openai/agents-sdk'; // Create specialized agents const researcher = new Agent({ name: 'researcher', role: 'Researcher', instructions: 'Responsible for collecting and analyzing information', tools: [searchTool, analyzeTool], }); const writer = new Agent({ name: 'writer', role: 'Writer', instructions: 'Responsible for writing content', tools: [writeTool, editTool], }); const reviewer = new Agent({ name: 'reviewer', role: 'Reviewer', instructions: 'Responsible for reviewing and improving content', tools: [reviewTool, feedbackTool], }); // Create multi-agent system const system = new MultiAgentSystem({ agents: [researcher, writer, reviewer], communication: 'broadcast', // or 'point-to-point' protocol: async (messages, agents) => { // Define collaboration protocol const lastMessage = messages[messages.length - 1]; if (lastMessage.from === 'researcher') { return 'writer'; // After research, hand to writer } else if (lastMessage.from === 'writer') { return 'reviewer'; // After writing, hand to reviewer } else if (lastMessage.from === 'reviewer' && lastMessage.needsRevision) { return 'writer'; // If revision needed, return to writer } else { return null; // Complete } }, }); // Run multi-agent system const result = await system.run({ task: 'Create a market analysis report', maxIterations: 10, }); ``` 

**1. Tool Design Principles** ```typescript // Good tool design const goodTool = new Tool({ name: 'calculate_shipping', description: 'Calculate shipping cost for an order', // Clear description parameters: { weight: new Parameter({ type: 'number', description: 'Package weight (kilograms)', // Explicit units required: true, }), destination: new Parameter({ type: 'string', description: 'Destination country code (ISO 3166-1 alpha-2)', // Explicit format required: true, }), service: new Parameter({ type: 'string', description: 'Shipping service type', enum: ['standard', 'express', 'overnight'], // Explicit options default: 'standard', }), }, execute: async ({ weight, destination, service }) => { // Input validation if (weight <= 0) { throw new Error('Weight must be positive'); } // Business logic const rate = await getShippingRate(destination, service); const cost = weight * rate; // Return structured result return { cost: cost.toFixed(2), currency: 'USD', estimated_days: getEstimatedDays(destination, service), tracking_available: service !== 'standard', }; }, }); ``` **2. Error Handling** ```typescript import { Tool, ToolError, RetryStrategy } from '@openai/agents-sdk'; const resilientTool = new Tool({ name: 'api_call', description: 'Call external API', parameters: { /* ... */ }, execute: async (params) => { // Retry strategy const retryStrategy = new RetryStrategy({ maxAttempts: 3, backoff: 'exponential', initialDelay: 1000, }); return await retryStrategy.execute(async () => { try { const response = await fetch('https://api.example.com/data', { method: 'POST', body: JSON.stringify(params), }); if (!response.ok) { throw new ToolError({ code: 'API_ERROR', message: `API returned ${response.status}`, recoverable: response.status >= 500, }); } return await response.json(); } catch (error) { if (error instanceof ToolError) { throw error; } throw new ToolError({ code: 'NETWORK_ERROR', message: error.message, recoverable: true, }); } }); }, }); ``` **3. Tool Composition** ```typescript import { ToolChain, Tool } from '@openai/agents-sdk'; // Create tool chain const dataPipeline = new ToolChain({ name: 'data-processing-pipeline', tools: [ fetchTool, // Fetch data validateTool, // Validate data transformTool, // Transform data enrichTool, // Enrich data storeTool, // Store data ], execution: 'sequential', // or 'parallel' onError: 'stop', // or 'continue' }); // Use tool chain const result = await dataPipeline.execute({ input: rawData, context: { userId: 'user_123' }, }); // Conditional tool chain const smartPipeline = new ToolChain({ name: 'smart-pipeline', tools: [ { tool: fetchTool, condition: (input) => input.needsFetch, }, { tool: cacheTool, condition: (input) => !input.needsFetch, }, validateTool, // Always execute transformTool, // Always execute ], }); ``` Try our [Code Formatter](/tools/code-formatter) to optimize code.

**1. Deployment Configuration** ```typescript import { Agent, DeploymentConfig } from '@openai/agents-sdk'; const deploymentConfig: DeploymentConfig = { // Model configuration model: { name: 'gpt-4-turbo', temperature: 0.7, maxTokens: 2000, topP: 0.9, }, // Performance configuration performance: { timeout: 30000, // 30 second timeout retries: 3, rateLimit: { requests: 100, window: '1m', }, }, // Security configuration security: { inputValidation: true, outputSanitization: true, piiDetection: true, contentFiltering: true, }, // Monitoring configuration monitoring: { enableTracing: true, enableMetrics: true, logLevel: 'info', sampleRate: 0.1, // 10% of requests for detailed tracing }, // Caching configuration caching: { enabled: true, ttl: 3600, // 1 hour maxSize: 1000, // Max 1000 cached items }, }; const agent = new Agent({ name: 'production-agent', config: deploymentConfig, // ... other configuration }); ``` **2. Monitoring Metrics** ```typescript import { Metrics, Tracer } from '@openai/agents-sdk'; // Custom metrics const metrics = new Metrics({ prefix: 'agent_', labels: { agent: 'customer-support', environment: 'production', }, }); // Record metrics metrics.increment('requests_total'); metrics.histogram('response_time', responseTime); metrics.gauge('active_sessions', activeSessions); // Tracing const tracer = new Tracer({ serviceName: 'customer-support-agent', endpoint: 'http://jaeger:14268/api/traces', }); // Create trace const span = tracer.startSpan('agent.run'); span.setTag('user_id', userId); span.setTag('session_id', sessionId); try { const result = await agent.run({ input, context }); span.setTag('status', 'success'); span.setTag('tool_calls', result.toolCalls.length); return result; } catch (error) { span.setTag('status', 'error'); span.setTag('error', error.message); throw error; } finally { span.finish(); } ``` **3. Logging** ```typescript import { Logger } from '@openai/agents-sdk'; const logger = new Logger({ level: 'info', format: 'json', outputs: [ { type: 'console' }, { type: 'file', path: '/var/log/agent.log' }, { type: 'elasticsearch', endpoint: 'http://es:9200' }, ], }); // Structured logging logger.info('Agent started', { agent: 'customer-support', version: '1.2.3', environment: 'production', }); logger.info('Processing request', { userId: 'user_123', sessionId: 'session_456', inputLength: input.length, }); logger.error('Tool execution failed', { tool: 'search_knowledge_base', error: error.message, stack: error.stack, }); ``` 

**1. Prompt Caching** ```typescript import { PromptCache } from '@openai/agents-sdk'; const cache = new PromptCache({ maxSize: 1000, ttl: 3600, strategy: 'lru', }); // Use cache const cachedResponse = await cache.get(prompt); if (cachedResponse) { return cachedResponse; } const response = await agent.run({ input }); await cache.set(prompt, response); return response; ``` **2. Streaming Responses** ```typescript // Stream processing for long responses const stream = await agent.runStream({ input: 'Write a long article', }); for await (const chunk of stream) { process.stdout.write(chunk.content); // Real-time tool call handling if (chunk.toolCalls) { for (const toolCall of chunk.toolCalls) { console.log(`Calling tool: ${toolCall.name}`); } } } ``` **3. Batch Processing** ```typescript import { BatchProcessor } from '@openai/agents-sdk'; const batchProcessor = new BatchProcessor({ batchSize: 10, timeout: 5000, // 5 seconds }); // Add requests to batch processing queue batchProcessor.add({ input: 'Request 1', context: { userId: 'user_1' }, }); batchProcessor.add({ input: 'Request 2', context: { userId: 'user_2' }, }); // Automatic batch processing batchProcessor.on('batch', async (batch) => { const results = await Promise.all( batch.map(item => agent.run(item)) ); return results; }); ``` Try our [Markdown Editor](/tools/markdown-editor) to write documentation. **Conclusion** OpenAI Agents SDK provides a complete toolchain for building production-grade AI agents. Through proper architecture design, tool integration, state management, and deployment strategies, you can build reliable, scalable agent systems. Remember, production-grade agents are not just about functionality implementation — more importantly, they're about reliability, observability, and maintainability.