OpenAI Agents SDK 2026：构建生产级AI智能体完全指南

**1. Agent（智能体）** 智能体是SDK的核心抽象，封装了LLM、工具和上下文。 ```typescript import { Agent, Tool, Context } from '@openai/agents-sdk'; // 创建智能体 const agent = new Agent({ name: 'customer-support', model: 'gpt-4-turbo', instructions: '你是一个专业的客户支持助手...', tools: [ new Tool({ name: 'search_knowledge_base', description: '搜索知识库', parameters: { query: { type: 'string', description: '搜索查询' }, }, execute: async ({ query }) => { return await searchKnowledgeBase(query); }, }), new Tool({ name: 'create_ticket', description: '创建工单', parameters: { title: { type: 'string' }, description: { type: 'string' }, priority: { type: 'string', enum: ['low', 'medium', 'high'] }, }, execute: async (params) => { return await createTicket(params); }, }), ], }); // 运行智能体 const response = await agent.run({ input: '我无法登录我的账户', context: { userId: 'user_123' }, }); console.log(response.output); console.log(response.toolCalls); ``` **2. Tool（工具）** 工具是智能体与外部世界交互的接口。 ```typescript import { Tool, Parameter } from '@openai/agents-sdk'; // 定义复杂工具 const weatherTool = new Tool({ name: 'get_weather', description: '获取指定城市的天气信息', parameters: { city: new Parameter({ type: 'string', description: '城市名称', required: true, }), units: new Parameter({ type: 'string', description: '温度单位', 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, }; }, }); // 工具验证 const validatedTool = weatherTool.validate({ city: '北京', units: 'celsius', }); if (validatedTool.isValid) { const result = await weatherTool.execute(validatedTool.params); } ``` **3. Context（上下文）** 上下文管理智能体的状态和记忆。 ```typescript import { Context, Memory } from '@openai/agents-sdk'; // 创建上下文 const context = new Context({ userId: 'user_123', sessionId: 'session_456', metadata: { plan: 'premium', language: 'zh-CN', }, }); // 添加记忆 context.memory.add({ role: 'user', content: '我喜欢使用TypeScript', timestamp: Date.now(), }); // 检索相关记忆 const relevantMemories = await context.memory.search('编程语言偏好', { topK: 5, threshold: 0.7, }); // 持久化上下文 await context.save(); // 恢复上下文 const restoredContext = await Context.load('session_456'); ``` 使用我们的[JSON格式化工具](/tools/json-formatter)来调试配置。

**模式一：分层智能体架构** ```typescript import { Agent, Router, Orchestrator } from '@openai/agents-sdk'; // 路由层：决定将请求发送给哪个专业智能体 const router = new Router({ name: 'request-router', model: 'gpt-3.5-turbo', instructions: '根据用户请求类型路由到合适的智能体', 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; }, }); // 编排层：协调多个智能体完成复杂任务 const orchestrator = new Orchestrator({ name: 'task-orchestrator', agents: [ researchAgent, analysisAgent, writingAgent, reviewAgent, ], workflow: async (task, agents) => { // 1. 研究阶段 const research = await agents.research.execute(task); // 2. 分析阶段 const analysis = await agents.analysis.execute(research.output); // 3. 写作阶段 const draft = await agents.writing.execute(analysis.output); // 4. 审查阶段 const review = await agents.review.execute(draft.output); return review.output; }, }); // 使用编排器 const result = await orchestrator.run({ task: '写一篇关于AI趋势的文章', }); ``` **模式二：状态机智能体** ```typescript import { StateMachineAgent, State, Transition } from '@openai/agents-sdk'; // 定义状态 const states = { idle: new State({ name: 'idle', onEnter: async (context) => { console.log('等待用户输入...'); }, }), collecting: new State({ name: 'collecting', onEnter: async (context) => { await context.agent.say('请提供更多信息'); }, }), 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(`处理结果：${result} 确认吗？`); }, }), completed: new State({ name: 'completed', onEnter: async (context) => { await context.agent.say('任务完成！'); }, }), }; // 定义转换 const transitions = [ new Transition({ from: 'idle', to: 'collecting', condition: (input) => input.includes('需要帮助'), }), 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('确认'), }), new Transition({ from: 'confirming', to: 'collecting', condition: (input) => input.toLowerCase().includes('修改'), }), ]; // 创建状态机智能体 const fsmAgent = new StateMachineAgent({ name: 'order-processor', states, transitions, initialState: 'idle', }); // 运行状态机 await fsmAgent.run({ input: '我需要帮助处理订单', }); ``` **模式三：多智能体协作** ```typescript import { MultiAgentSystem, Agent, Message } from '@openai/agents-sdk'; // 创建专业智能体 const researcher = new Agent({ name: 'researcher', role: '研究员', instructions: '负责收集和分析信息', tools: [searchTool, analyzeTool], }); const writer = new Agent({ name: 'writer', role: '作者', instructions: '负责撰写内容', tools: [writeTool, editTool], }); const reviewer = new Agent({ name: 'reviewer', role: '审查员', instructions: '负责审查和改进内容', tools: [reviewTool, feedbackTool], }); // 创建多智能体系统 const system = new MultiAgentSystem({ agents: [researcher, writer, reviewer], communication: 'broadcast', // 或 'point-to-point' protocol: async (messages, agents) => { // 定义协作协议 const lastMessage = messages[messages.length - 1]; if (lastMessage.from === 'researcher') { return 'writer'; // 研究完成后交给作者 } else if (lastMessage.from === 'writer') { return 'reviewer'; // 写作完成后交给审查员 } else if (lastMessage.from === 'reviewer' && lastMessage.needsRevision) { return 'writer'; // 需要修改则返回作者 } else { return null; // 完成 } }, }); // 运行多智能体系统 const result = await system.run({ task: '创建一份市场分析报告', maxIterations: 10, }); ``` 

**1. 工具设计原则** ```typescript // 好的工具设计 const goodTool = new Tool({ name: 'calculate_shipping', description: '计算订单的运费', // 清晰的描述 parameters: { weight: new Parameter({ type: 'number', description: '包裹重量（千克）', // 明确的单位 required: true, }), destination: new Parameter({ type: 'string', description: '目的地国家代码（ISO 3166-1 alpha-2）', // 明确的格式 required: true, }), service: new Parameter({ type: 'string', description: '配送服务类型', enum: ['standard', 'express', 'overnight'], // 明确的选项 default: 'standard', }), }, execute: async ({ weight, destination, service }) => { // 输入验证 if (weight <= 0) { throw new Error('Weight must be positive'); } // 业务逻辑 const rate = await getShippingRate(destination, service); const cost = weight * rate; // 返回结构化结果 return { cost: cost.toFixed(2), currency: 'USD', estimated_days: getEstimatedDays(destination, service), tracking_available: service !== 'standard', }; }, }); ``` **2. 错误处理** ```typescript import { Tool, ToolError, RetryStrategy } from '@openai/agents-sdk'; const resilientTool = new Tool({ name: 'api_call', description: '调用外部API', parameters: { /* ... */ }, execute: async (params) => { // 重试策略 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. 工具组合** ```typescript import { ToolChain, Tool } from '@openai/agents-sdk'; // 创建工具链 const dataPipeline = new ToolChain({ name: 'data-processing-pipeline', tools: [ fetchTool, // 获取数据 validateTool, // 验证数据 transformTool, // 转换数据 enrichTool, // 丰富数据 storeTool, // 存储数据 ], execution: 'sequential', // 或 'parallel' onError: 'stop', // 或 'continue' }); // 使用工具链 const result = await dataPipeline.execute({ input: rawData, context: { userId: 'user_123' }, }); // 条件工具链 const smartPipeline = new ToolChain({ name: 'smart-pipeline', tools: [ { tool: fetchTool, condition: (input) => input.needsFetch, }, { tool: cacheTool, condition: (input) => !input.needsFetch, }, validateTool, // 总是执行 transformTool, // 总是执行 ], }); ``` 使用我们的[代码格式化工具](/tools/code-formatter)来优化代码。

**1. 部署配置** ```typescript import { Agent, DeploymentConfig } from '@openai/agents-sdk'; const deploymentConfig: DeploymentConfig = { // 模型配置 model: { name: 'gpt-4-turbo', temperature: 0.7, maxTokens: 2000, topP: 0.9, }, // 性能配置 performance: { timeout: 30000, // 30秒超时 retries: 3, rateLimit: { requests: 100, window: '1m', }, }, // 安全配置 security: { inputValidation: true, outputSanitization: true, piiDetection: true, contentFiltering: true, }, // 监控配置 monitoring: { enableTracing: true, enableMetrics: true, logLevel: 'info', sampleRate: 0.1, // 10%的请求进行详细追踪 }, // 缓存配置 caching: { enabled: true, ttl: 3600, // 1小时 maxSize: 1000, // 最多1000个缓存项 }, }; const agent = new Agent({ name: 'production-agent', config: deploymentConfig, // ... 其他配置 }); ``` **2. 监控指标** ```typescript import { Metrics, Tracer } from '@openai/agents-sdk'; // 自定义指标 const metrics = new Metrics({ prefix: 'agent_', labels: { agent: 'customer-support', environment: 'production', }, }); // 记录指标 metrics.increment('requests_total'); metrics.histogram('response_time', responseTime); metrics.gauge('active_sessions', activeSessions); // 追踪 const tracer = new Tracer({ serviceName: 'customer-support-agent', endpoint: 'http://jaeger:14268/api/traces', }); // 创建追踪 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. 日志记录** ```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' }, ], }); // 结构化日志 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. 提示缓存** ```typescript import { PromptCache } from '@openai/agents-sdk'; const cache = new PromptCache({ maxSize: 1000, ttl: 3600, strategy: 'lru', }); // 使用缓存 const cachedResponse = await cache.get(prompt); if (cachedResponse) { return cachedResponse; } const response = await agent.run({ input }); await cache.set(prompt, response); return response; ``` **2. 流式响应** ```typescript // 流式处理长响应 const stream = await agent.runStream({ input: '写一篇长文章', }); for await (const chunk of stream) { process.stdout.write(chunk.content); // 实时处理工具调用 if (chunk.toolCalls) { for (const toolCall of chunk.toolCalls) { console.log(`Calling tool: ${toolCall.name}`); } } } ``` **3. 批处理** ```typescript import { BatchProcessor } from '@openai/agents-sdk'; const batchProcessor = new BatchProcessor({ batchSize: 10, timeout: 5000, // 5秒 }); // 添加请求到批处理队列 batchProcessor.add({ input: '请求1', context: { userId: 'user_1' }, }); batchProcessor.add({ input: '请求2', context: { userId: 'user_2' }, }); // 自动批处理 batchProcessor.on('batch', async (batch) => { const results = await Promise.all( batch.map(item => agent.run(item)) ); return results; }); ``` 使用我们的[Markdown编辑器](/tools/markdown-editor)来编写文档。 **结论** OpenAI Agents SDK为构建生产级AI智能体提供了完整的工具链。通过合理的架构设计、工具集成、状态管理和部署策略，你可以构建可靠、可扩展的智能体系统。记住，生产级智能体不仅仅是功能实现，更重要的是可靠性、可观测性和可维护性。