OpenAI Agents SDK TypeScript: Practical Recipes & Code Examples
Worked TypeScript examples for the OpenAI Agents SDK: Q&A, translation, classification, routing, data validation, scheduling, webhooks and refinement loops.
Verified against
@openai/agents0.22.0 (checked 2026-11-19). Every block compiles undertsc --strictand was run withScriptedModelin place of a live model.
Short, self-contained examples. Tools return canned data so each recipe runs as written; replace them with calls to your own systems. For limits, retries, approvals and testing, see the production guide.
Table of Contents
Section titled “Table of Contents”- Basic Agent Recipes
- Multi-Agent Workflows
- Data Processing
- Customer Service
- Content Generation
- Research & Analysis
- Integration Patterns
- Advanced Orchestration
Basic Agent Recipes
Section titled “Basic Agent Recipes”Recipe 1: Simple Q&A Agent
Section titled “Recipe 1: Simple Q&A Agent”import { Agent, run } from '@openai/agents';
async function createQAAgent() { const qaAgent = new Agent({ name: 'Q&A Assistant', instructions: `You are a knowledgeable Q&A assistant. - Answer questions accurately and concisely - Provide relevant examples when helpful - Acknowledge when you're uncertain`, });
const question = 'What are the benefits of TypeScript?'; const result = await run(qaAgent, question);
console.log(`Q: ${question}`); console.log(`A: ${result.finalOutput}`);
return result.finalOutput;}
// Run: createQAAgent();Recipe 2: Translation Agent with Multiple Languages
Section titled “Recipe 2: Translation Agent with Multiple Languages”import { Agent, run } from '@openai/agents';
async function translateWithAgent(text: string, targetLanguage: string) { const translator = new Agent({ name: 'Translator', instructions: `You are an expert translator. Translate the provided text to ${targetLanguage} while: - Preserving tone and context - Maintaining technical accuracy - Handling idioms appropriately`, });
const result = await run(translator, `Translate to ${targetLanguage}: "${text}"`); return result.finalOutput;}
// Usageconst english = 'Hello, how can I help you today?';const spanish = await translateWithAgent(english, 'Spanish');const french = await translateWithAgent(english, 'French');const german = await translateWithAgent(english, 'German');
console.log(`Spanish: ${spanish}`);console.log(`French: ${french}`);console.log(`German: ${german}`);Recipe 3: Content Classification Agent
Section titled “Recipe 3: Content Classification Agent”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
async function classifyContentAgent() { const classificationTool = tool({ name: 'classify_content', description: 'Classify content into categories', parameters: z.object({ text: z.string(), }), execute: async ({ text }) => { // Return classifications return { category: 'technology', sentiment: 'positive', isSpam: false, }; }, });
const classifier = new Agent({ name: 'Content Classifier', instructions: 'Classify user-provided content into appropriate categories.', tools: [classificationTool], });
const content = 'This is an amazing new AI framework!'; const result = await run(classifier, `Classify: ${content}`);
return result.finalOutput;}Multi-Agent Workflows
Section titled “Multi-Agent Workflows”Recipe 4: Research & Summary Workflow
Section titled “Recipe 4: Research & Summary Workflow”import { Agent, run } from '@openai/agents';
async function researchAndSummariseWorkflow(topic: string) { // Researcher agent const researcher = new Agent({ name: 'Researcher', instructions: `Research and gather information about the given topic. - Find key facts and recent developments - Identify main concepts - Note authoritative sources`, });
// Summariser agent const summariser = new Agent({ name: 'Summariser', instructions: `Create a concise summary of research findings. - Extract key points - Keep it under 500 words - Organise logically`, });
// Step 1: Research console.log('Step 1: Researching...'); const researchResult = await run(researcher, `Research: ${topic}`); const findings = researchResult.finalOutput ?? ''; console.log('Research findings:', findings.substring(0, 200) + '...');
// Step 2: Summarise console.log('\nStep 2: Summarising...'); const summaryResult = await run( summariser, `Summarise these research findings about ${topic}:\n${findings}` ); console.log('Summary:', summaryResult.finalOutput);
return summaryResult.finalOutput;}
// Usageawait researchAndSummariseWorkflow('Quantum Computing');Recipe 5: Customer Support Routing
Section titled “Recipe 5: Customer Support Routing”import { Agent, run } from '@openai/agents';
async function customerSupportRouter(customerQuery: string) { // Department agents const billingAgent = new Agent({ name: 'Billing Support', instructions: 'Handle billing and payment inquiries professionally.', });
const technicalAgent = new Agent({ name: 'Technical Support', instructions: 'Resolve technical issues step-by-step.', });
const generalAgent = new Agent({ name: 'General Support', instructions: 'Provide general assistance and information.', });
// Routing agent const routerAgent = Agent.create({ name: 'Support Router', instructions: `Route customer inquiries to the appropriate department: - Billing issues → Billing Support - Technical problems → Technical Support - Everything else → General Support`, handoffs: [billingAgent, technicalAgent, generalAgent], });
const result = await run(routerAgent, customerQuery);
console.log(`Query: ${customerQuery}`); console.log(`Routed to: ${result.lastAgent?.name || 'General'}`); console.log(`Response: ${result.finalOutput}`);
return result;}
// Usage examplesawait customerSupportRouter('Why was I charged twice?');await customerSupportRouter('The app keeps crashing on startup');await customerSupportRouter('How do I reset my password?');Recipe 6: Parallel Processing Pipeline
Section titled “Recipe 6: Parallel Processing Pipeline”import { Agent, run } from '@openai/agents';
async function parallelProcessingPipeline(document: string) { // Create specialized agents const sentimentAnalyser = new Agent({ name: 'Sentiment Analyser', instructions: 'Analyse the sentiment of the provided text.', });
const keywordExtractor = new Agent({ name: 'Keyword Extractor', instructions: 'Extract key topics and keywords from the text.', });
const readabilityAnalyser = new Agent({ name: 'Readability Analyser', instructions: 'Analyse readability and suggest improvements.', });
// Execute in parallel const [sentiment, keywords, readability] = await Promise.all([ run(sentimentAnalyser, `Analyse sentiment: ${document}`), run(keywordExtractor, `Extract keywords: ${document}`), run(readabilityAnalyser, `Analyse readability: ${document}`), ]);
return { sentiment: sentiment.finalOutput, keywords: keywords.finalOutput, readability: readability.finalOutput, };}
// Usageconst analysis = await parallelProcessingPipeline('Your document text here...');console.log('Analysis Results:', analysis);Data Processing
Section titled “Data Processing”Recipe 7: Data Validation Agent
Section titled “Recipe 7: Data Validation Agent”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
async function dataValidationAgent(jsonData: string) { const validateTool = tool({ name: 'validate_data', description: 'Validate data structure and content', parameters: z.object({ data: z.string(), rules: z.string(), }), execute: async ({ data, rules }) => { try { const parsed = JSON.parse(data); return { valid: true, data: parsed }; } catch { return { valid: false, error: 'Invalid JSON' }; } }, });
const validator = new Agent({ name: 'Data Validator', instructions: `Validate provided data against requirements. - Check structure - Verify types - Ensure completeness`, tools: [validateTool], });
const result = await run(validator, `Validate this data: ${jsonData}`); return result.finalOutput;}
// Usageconst testData = JSON.stringify({ name: 'John Doe', email: 'john@example.com', age: 30,});
await dataValidationAgent(testData);Recipe 8: CSV to Structured Format
Section titled “Recipe 8: CSV to Structured Format”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
async function csvToStructuredAgent(csvData: string) { const parseTool = tool({ name: 'parse_csv', description: 'Parse CSV data', parameters: z.object({ csv: z.string(), }), execute: async ({ csv }) => { const lines = csv.trim().split('\n'); const headers = lines[0].split(','); const rows = lines.slice(1).map(line => Object.fromEntries( headers.map((header, idx) => [header.trim(), line.split(',')[idx]?.trim()]) ) ); return { headers, rows, count: rows.length }; }, });
const parser = new Agent({ name: 'CSV Parser', instructions: 'Convert CSV data to structured format.', tools: [parseTool], });
const result = await run(parser, `Parse this CSV:\n${csvData}`); return result.finalOutput;}
// Usageconst csv = `name,email,departmentAlice Johnson,alice@company.com,EngineeringBob Smith,bob@company.com,SalesCarol White,carol@company.com,HR`;
await csvToStructuredAgent(csv);Customer Service
Section titled “Customer Service”Recipe 9: FAQ System with Agent
Section titled “Recipe 9: FAQ System with Agent”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
const faqDatabase = { 'refund-policy': 'Refunds accepted within 30 days of purchase...', 'shipping-time': 'Standard shipping takes 5-7 business days...', 'warranty': 'All products come with a 1-year warranty...',};
async function faqAgent(userQuestion: string) { const lookupFAQTool = tool({ name: 'lookup_faq', description: 'Look up answers in FAQ database', parameters: z.object({ query: z.string(), }), execute: async ({ query }) => { const key = Object.keys(faqDatabase).find(k => query.toLowerCase().includes(k.replace('-', ' ')) ); return key ? { found: true, answer: faqDatabase[key as keyof typeof faqDatabase] } : { found: false }; }, });
const faqAssistant = new Agent({ name: 'FAQ Assistant', instructions: 'Answer customer questions using the FAQ database when available.', tools: [lookupFAQTool], });
const result = await run(faqAssistant, userQuestion); return result.finalOutput;}
// Usageawait faqAgent('What is your refund policy?');await faqAgent('How long does shipping take?');await faqAgent('Do you offer warranty?');Recipe 10: Appointment Scheduling Assistant
Section titled “Recipe 10: Appointment Scheduling Assistant”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
const appointments: Array<{ id: string; time: string; client: string }> = [];
async function appointmentSchedulingAgent(userRequest: string) { const scheduleTool = tool({ name: 'schedule_appointment', description: 'Schedule an appointment', parameters: z.object({ clientName: z.string(), time: z.string(), reason: z.string(), }), execute: async ({ clientName, time, reason }) => { const id = `apt-${Date.now()}`; appointments.push({ id, time, client: clientName }); return { success: true, appointmentId: id, confirmationTime: time }; }, });
const checkAvailabilityTool = tool({ name: 'check_availability', description: 'Check available time slots', parameters: z.object({ date: z.string(), }), execute: async ({ date }) => { // Mock availability return { available: ['09:00', '10:00', '14:00', '15:00', '16:00'], }; }, });
const scheduler = new Agent({ name: 'Appointment Scheduler', instructions: 'Help customers schedule appointments by finding available slots and confirming.', tools: [scheduleTool, checkAvailabilityTool], });
const result = await run(scheduler, userRequest); return result.finalOutput;}
// Usageawait appointmentSchedulingAgent('I need to schedule a consultation for next Tuesday morning');Content Generation
Section titled “Content Generation”Recipe 11: Blog Post Generator
Section titled “Recipe 11: Blog Post Generator”import { Agent, run } from '@openai/agents';
async function blogPostGenerator(topic: string, wordCount: number = 1000) { const outlineAgent = new Agent({ name: 'Outline Creator', instructions: 'Create detailed blog post outlines with clear sections.', });
const writerAgent = new Agent({ name: 'Blog Writer', instructions: 'Write engaging blog posts with SEO in mind.', });
// Step 1: Create outline const outlineResult = await run(outlineAgent, `Create an outline for a ${wordCount}-word blog post about: ${topic}`);
// Step 2: Write blog post const blogResult = await run( writerAgent, `Write a ${wordCount}-word blog post about ${topic} using this outline:\n${outlineResult.finalOutput}` );
return { topic, outline: outlineResult.finalOutput, content: blogResult.finalOutput, };}
// Usageconst blog = await blogPostGenerator('The Future of Artificial Intelligence', 1500);console.log('Blog Post:', blog.content);Recipe 12: Social Media Content Creator
Section titled “Recipe 12: Social Media Content Creator”import { Agent, run } from '@openai/agents';
async function socialMediaContentCreator(topic: string) { const tweetAgent = new Agent({ name: 'Tweet Creator', instructions: 'Create engaging tweets within 280 characters.', });
const linkedinAgent = new Agent({ name: 'LinkedIn Strategist', instructions: 'Create professional LinkedIn posts.', });
const instagramAgent = new Agent({ name: 'Instagram Specialist', instructions: 'Create creative Instagram captions.', });
const [tweet, linkedin, instagram] = await Promise.all([ run(tweetAgent, `Create a tweet about: ${topic}`), run(linkedinAgent, `Create a LinkedIn post about: ${topic}`), run(instagramAgent, `Create an Instagram caption about: ${topic}`), ]);
return { twitter: tweet.finalOutput, linkedin: linkedin.finalOutput, instagram: instagram.finalOutput, };}
// Usageconst content = await socialMediaContentCreator('Sustainable Technology');console.log('Social Media Content:', content);Research & Analysis
Section titled “Research & Analysis”Recipe 13: Market Analysis Agent
Section titled “Recipe 13: Market Analysis Agent”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
async function marketAnalysisAgent(industry: string) { const trendTool = tool({ name: 'research_trends', description: 'Research market trends', parameters: z.object({ industry: z.string(), period: z.string(), }), execute: async ({ industry }) => ({ trends: ['AI adoption', 'Cost optimisation', 'Sustainability'], }), });
const competitorTool = tool({ name: 'analyse_competitors', description: 'Analyse competitor landscape', parameters: z.object({ industry: z.string(), }), execute: async ({ industry }) => ({ topCompetitors: ['Company A', 'Company B', 'Company C'], }), });
const analyst = new Agent({ name: 'Market Analyst', instructions: 'Provide comprehensive market analysis.', tools: [trendTool, competitorTool], });
const result = await run(analyst, `Analyse the ${industry} market for investment opportunities`); return result.finalOutput;}
// Usageawait marketAnalysisAgent('Technology');Recipe 14: Code Review Agent
Section titled “Recipe 14: Code Review Agent”import { Agent, run, tool } from '@openai/agents';import { z } from 'zod';
async function codeReviewAgent(code: string) { const analyseCodeTool = tool({ name: 'analyse_code', description: 'Analyse code quality', parameters: z.object({ code: z.string(), }), execute: async ({ code }) => ({ issues: ['Missing error handling', 'Potential performance issue'], score: 7.5, }), });
const reviewer = new Agent({ name: 'Code Reviewer', instructions: `Review code for: - Best practices - Performance issues - Security vulnerabilities - Readability improvements`, tools: [analyseCodeTool], });
const result = await run(reviewer, `Review this code:\n\`\`\`typescript\n${code}\n\`\`\``); return result.finalOutput;}
// Usageconst sampleCode = `function calculateTotal(items) { let total = 0; for (let i = 0; i < items.length; i++) { total += items[i].price; } return total;}`;
await codeReviewAgent(sampleCode);Integration Patterns
Section titled “Integration Patterns”Recipe 15: Webhook Handler with Agent
Section titled “Recipe 15: Webhook Handler with Agent”Install express and @types/express alongside the SDK. A real webhook must verify the sender (a shared-secret header or a signature) before it passes any payload text to an agent, because the body becomes part of the prompt.
import { Agent, run } from '@openai/agents';import express from 'express';
const app = express();app.use(express.json());
const eventProcessor = new Agent({ name: 'Event Processor', instructions: 'Process and respond to incoming events.',});
app.post('/webhook', async (req, res) => { const { eventType, data } = req.body;
try { const result = await run( eventProcessor, `Process this event: ${eventType}\nData: ${JSON.stringify(data)}` );
res.json({ success: true, response: result.finalOutput, }); } catch (error) { res.status(500).json({ error: error instanceof Error ? error.message : String(error) }); }});
app.listen(3000, () => console.log('Webhook server ready'));Recipe 16: Scheduled Agent Tasks
Section titled “Recipe 16: Scheduled Agent Tasks”Install node-cron and @types/node-cron. The schedule lives in the process, so with several replicas every replica runs the job; use one scheduler instance or an external scheduler for production.
import { Agent, run } from '@openai/agents';import cron from 'node-cron';
const reportGenerator = new Agent({ name: 'Report Generator', instructions: 'Generate daily reports and summaries.',});
// Run every day at 8 AMcron.schedule('0 8 * * *', async () => { console.log('Generating daily report...'); const result = await run(reportGenerator, 'Generate today\'s summary report'); console.log('Report:', result.finalOutput);});
// Run every hourcron.schedule('0 * * * *', async () => { console.log('Running hourly task...'); const result = await run(reportGenerator, 'Check system health'); console.log('Health check:', result.finalOutput);});Advanced Orchestration
Section titled “Advanced Orchestration”Recipe 17: Complex Workflow with Conditions
Section titled “Recipe 17: Complex Workflow with Conditions”Route in code on a structured verdict rather than on keywords in free text:
import { Agent, run } from '@openai/agents';import { z } from 'zod';
const Triage = z.object({ urgency: z.enum(['urgent', 'routine']), reason: z.string(),});
const analyserAgent = new Agent({ name: 'Analyser', instructions: 'Classify the request as urgent (outage, data loss, security) or routine.', outputType: Triage,});
const escalationAgent = new Agent({ name: 'Escalator', instructions: 'Handle urgent matters.' });const routineAgent = new Agent({ name: 'Routine Handler', instructions: 'Handle routine tasks.' });
async function complexWorkflow(input: string): Promise<string> { const analysis = await run(analyserAgent, input); const verdict = analysis.finalOutput; const next = verdict?.urgency === 'urgent' ? escalationAgent : routineAgent; const result = await run(next, input); return result.finalOutput ?? '';}
console.log(await complexWorkflow('Server is down!'));console.log(await complexWorkflow('Update documentation'));Recipe 18: Feedback Loop with Refinement
Section titled “Recipe 18: Feedback Loop with Refinement”A writer and a critic in a loop, with the critic returning a typed verdict so the loop ends on a field, not on a phrase:
import { Agent, run } from '@openai/agents';import { z } from 'zod';
const Critique = z.object({ approved: z.boolean(), feedback: z.string(),});
const critic = new Agent({ name: 'Critic', instructions: 'Critique the draft. Approve it only if it is clear, accurate and under 150 words.', outputType: Critique,});
const writer = new Agent({ name: 'Writer', instructions: 'Write or revise the requested text.',});
async function refinementWorkflow(task: string, maxIterations = 3): Promise<string> { let prompt = task; let draft = '';
for (let iteration = 1; iteration <= maxIterations; iteration++) { const written = await run(writer, prompt); draft = written.finalOutput ?? ''; console.log(`Iteration ${iteration}:`, draft.substring(0, 100));
const review = await run(critic, draft); const critique = review.finalOutput; if (!critique || critique.approved) break;
prompt = `${task}\n\nPrevious draft:\n${draft}\n\nRevise it to address: ${critique.feedback}`; }
return draft;}
console.log(await refinementWorkflow('Write an introduction to machine learning'));More patterns: agents as tools, approvals and streaming over HTTP.