# Useful but Little-Known Features of OpenAI Agent SDK 🌍 Ever wanted to mix multiple LLM providers within a single agent system? `MultiProvider` automatically routes requests to the right provider based on model name prefixes. 📌 Title: Prefix Routing with MultiProvider 🔗 URL: 🧩 Overview `MultiProvider` routes requests to the appropriate provider based on model name prefixes (e.g., `openai/gpt-4.1`). Setting `openai_prefix_mode="model_id"` treats `openai/...` as a literal model ID, while `unknown_prefix_mode="model_id"` routes unknown prefixes as model IDs too. Enable `openai_use_responses_websocket=True` for WebSocket transport on supported providers. 🛠 How to use it ```python from agents import Agent, MultiProvider, RunConfig, Runner provider = MultiProvider( openai_base_url="", openai_api_key="...", openai_use_responses_websocket=True, openai_prefix_mode="model_id", unknown_prefix_mode="model_id", ) agent = Agent( name="Assistant", instructions="Be concise.", model="openai/gpt-4.1", ) result = await agent, "Hello", run_config=RunConfig(model_provider=provider), ) ``` 🏗 Building it into production ・Assign different provider models to each agent based on cost and latency requirements ・Combine with gateway services like OpenRouter using `openai_prefix_mode="model_id"` to pass prefixed model names through ・Switch providers at runtime via `RunConfig(model_provider=provider)` for A/B testing ・Enable WebSocket for improved streaming performance on supported providers 💡 Use cases 🔀 Routing GPT-4.1 vs GPT-5.5 based on task difficulty 🌐 Unified access to multiple providers through OpenRouter 💰 Hybrid operation mixing high-cost and low-cost models 🧪 Quality comparison testing across different models ⚠️ Watch out By default, `openai/...` aliases to the OpenAI provider, and unknown prefixes raise `UserError`. When using external gateways like OpenRouter, always set both `openai_prefix_mode` and `unknown_prefix_mode` to `"model_id"`. Note that feature support (tool calling, structured output, etc.) varies across providers. ✨ With MultiProvider, build agent systems that freely combine the best models from any provider. #OpenAIAgentSDK# #AIAgent#

# Useful but Little-Known Features of OpenAI Agent SDK 🌍 Ever wanted to pass provider-specific parameters that the SDK doesn't directly expose? With `extra_args`, you can add arbitrary provider-specific fields to `ModelSettings`. 📌 Title: Passing extra_args 🔗 URL: 🧩 Overview By passing a dictionary to the `extra_args` parameter of `ModelSettings`, you can send provider-specific request fields that aren't exposed as top-level SDK properties. For example, you can specify OpenAI Responses API fields like `service_tier` or `user`. This lets you use new API parameters without waiting for an SDK update. 🛠 How to use it ```python from agents import Agent, ModelSettings agent = Agent( name="English agent", instructions="You only speak English", model="gpt-4.1", model_settings=ModelSettings( temperature=0.1, extra_args={ "service_tier": "flex", "user": "user_12345", }, ), ) ``` 🏗 Building it into production ・Use `service_tier` for cost optimization (e.g., `"flex"` for cheaper low-priority batch processing) ・Set the `user` field to enable per-user tracking and abuse detection ・Adopt new API parameters immediately on release without waiting for SDK updates ・Build `extra_args` dynamically from environment variables or config files for per-environment tuning 💡 Use cases 💰 Cost reduction with `service_tier: "flex"` for batch workloads 👤 Per-user usage tracking via the `user` field 🔧 Early adoption of newly released provider features 🏢 Injecting tenant-specific parameters in multi-tenant environments ⚠️ Watch out Do not set the same request field through both a direct `ModelSettings` property and `extra_args`. Duplicate settings may cause unexpected behavior. Values passed via `extra_args` must conform to the provider's API specification, as the SDK does not validate them. ✨ With extra_args, unlock provider-specific optimizations beyond the SDK's built-in surface. #OpenAIAgentSDK# #AIAgent#

# Practical and Useful Patterns for OpenAI Agent SDK 🌍 Deliver your agent's responses in real time! By leveraging different streaming event types, you can build everything from typewriter UIs to tool-progress notifications, dramatically improving user experience. 📌 Title: Streaming 🔗 URL: 🧩 Overview The OpenAI Agent SDK provides three streaming event types. RawResponsesStreamEvent delivers raw LLM tokens in real time. RunItemStreamEvent fires for coarser events like message creation and tool calls. AgentUpdatedStreamEvent detects agent handoffs. You can also cancel immediately or after the current turn completes. 🛠 Usage Define `Agent(name="assistant", instructions="Answer helpfully")` and start streaming with ` "What are the latest AI trends?")`. Iterate with `async for event in for `isinstance(event, RawResponsesStreamEvent)`, display tokens in real time via ` For `isinstance(event, RunItemStreamEvent)`, check `event.item.type` -- `"tool_called"` shows tool invocation with ` `"tool_output"` signals completion, and `"message_output_created"` indicates message generation start. For `isinstance(event, AgentUpdatedStreamEvent)`, display agent switches via ` Finally, `await retrieves the complete result. For cancellation, after starting with ` "Run a long analysis")`, call `result.cancel()` inside the stream event loop for immediate abort, or `result.cancel(mode="after_turn")` to stop after the current turn completes. After canceling, consume the iterator with `async for _ in pass` to clean up resources. 🏗 Practical Patterns For chat UIs, the foundation is typewriter display using `output_text.delta` from `RawResponsesStreamEvent`. But since no tokens flow during tool calls, best practice is to show progress indicators like "Searching..." via `RunItemStreamEvent`'s `tool_called` event. In multi-agent setups, `AgentUpdatedStreamEvent` lets you display transitions like "Switched from Researcher to Writer agent," helping users understand the processing flow. Cancellation comes in two modes. `cancel()` aborts immediately, while `cancel(mode="after_turn")` waits for the current LLM turn to finish cleanly. In both cases, you must consume the stream iterator to completion after canceling to properly clean up resources. 💡 Use Cases ⌨️ Typewriter-style real-time display in chat applications 🔧 "Searching..." / "Calculating..." progress indicators during tool execution 🔄 Real-time agent-switch notifications in multi-agent UIs 🛑 Safe cancellation via user "Stop" button ⚠️ Caveats - Failing to consume the iterator after `cancel()` may cause resource leaks - `RawResponsesStreamEvent` fires per-token at high frequency — watch your UI re-render rate - Errors during streaming arrive as events, so handle them appropriately ✨ Using the right streaming events for the right purpose lets you communicate "thinking," "searching," and "writing" to users — building highly responsive agent UIs! #OpenAIAgentSDK# #AIAgent#

# Useful but Little-Known Features of OpenAI Agent SDK 🌍 Has a transient LLM API error ever crashed your entire agent pipeline? `ModelRetrySettings` lets the Runner automatically manage retry strategies, building agents resilient to temporary failures. 📌 Title: Runner-Managed Retries 🔗 URL: 🧩 Overview By passing `ModelRetrySettings` to the `retry` parameter of `ModelSettings`, you gain fine-grained control over retry count, backoff strategy, and retry policy. `max_retries` sets the maximum attempts, `backoff` configures delay strategy (`initial_delay`, `max_delay`, `multiplier`, `jitter`), and `policy` defines which error types qualify for retry. Importantly, abort errors, unsafe replays, streams after output begins, and stateful requests are never retried. 🛠 How to use it ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies agent = Agent( name="Assistant", model="gpt-5.5", model_settings=ModelSettings( retry=ModelRetrySettings( max_retries=4, backoff={ "initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True, }, policy=retry_policies.any( retry_policies.provider_suggested(), retry_policies.retry_after(), retry_policies.network_error(), retry_policies.http_status([408, 429, 500, 502, 503, 504]), ), ) ), ) ``` Available policy helpers: - `retry_policies.never()` - always opt out - `retry_policies.provider_suggested()` - follow provider guidance - `retry_policies.network_error()` - transient network failures - `retry_policies.http_status([...])` - specific HTTP status codes - `retry_policies.retry_after()` - honor Retry-After headers - `retry_policies.any(...)` / `retry_policies.all(...)` - combine policies 🏗 Building it into production ・Define default retry settings at the Runner level, override only `max_retries` per Agent ・Use `jitter: True` to avoid thundering herd when multiple agents retry simultaneously ・Always include 429 (rate limit) and 5xx (server errors) in your retry targets ・Agent-level settings deep-merge with Runner-level settings 💡 Use cases 🔄 Automatic backoff on rate limits (429) 🌐 Self-healing through transient network failures 🏢 Agent stability in multi-tenant environments 📊 Absorbing temporary errors in batch processing ⚠️ Watch out Abort errors, requests marked replay-unsafe by the provider, streams after output has started, and stateful requests using `previous_response_id` or `conversation_id` are never retried for safety. The `policy` field is not serialized, so it only takes effect at runtime. ✨ With ModelRetrySettings, build agents that stay resilient through transient failures. #OpenAIAgentSDK# #AIAgent#

# Useful but Little-Known Features of OpenAI Agent SDK 🌍 Did you know you can stop a streaming agent run mid-generation with a single method call? `RunResultStreaming.cancel()` lets you safely cancel a streaming run on demand. 📌 Title: RunResultStreaming.cancel() 🔗 URL: 🧩 Overview The `cancel()` method on `RunResultStreaming` stops a streaming agent run either immediately or after the current turn completes. After calling `cancel()`, you must continue consuming the `stream_events()` async iterator so that cancellation and cleanup finish correctly. The `is_complete` property indicates whether the run reached its terminal state, and summary properties like `final_output` and `interruptions` finalize after the last token. 🛠 How to use it ```python from agents import Agent, Runner agent = Agent(name="Assistant", instructions="You are helpful.") result = "Write a long essay...") async for event in # User pressed the cancel button if user_cancelled(): result.cancel() # Keep consuming for cleanup continue # Normal event processing handle_event(event) # Check state after cleanup completes print(f"Complete: {") ``` 🏗 Building it into production ・Wire a "Stop" button in your chat UI to trigger user-initiated cancellation ・Always consume `stream_events()` to completion after cancel to prevent resource leaks ・Check `is_complete` to distinguish cancelled runs from normal completions in your logs ・Use cancellation for cost management by cutting off unnecessary token generation early 💡 Use cases 🛑 Implementing a "Stop generating" button in chatbots 💰 Reducing token costs on overly long responses ⏱ Timeout-based automatic cancellation 🔄 Aborting a previous run when the user changes their question ⚠️ Watch out Skipping `stream_events()` consumption after `cancel()` prevents proper resource cleanup. Always exhaust the iterator. Depending on timing, the current turn may complete before the cancellation takes effect. ✨ With cancel(), give users full control over responsive streaming experiences. #OpenAIAgentSDK# #AIAgent#

# Practical and Useful Patterns for OpenAI Agent SDK 🌍 How you orchestrate multiple agents determines the quality and reliability of your entire system. Master LLM-driven and code-driven patterns to build the right architecture for each use case. 📌 Title: Agent orchestration 🔗 URL: 🧩 Overview Multi-agent orchestration comes in two flavors: LLM-driven (the model dynamically decides routing via handoffs) and code-driven (Python code explicitly controls the flow). Combined with the Manager pattern (`as_tool`) and handoff-based delegation, these patterns let you build anything from open-ended research assistants to deterministic content pipelines. 🛠 Usage For LLM-driven orchestration, define `Agent(name="researcher", handoffs=[web_search_agent, code_exec_agent])` and let the model dynamically choose. For code-driven pipelines, define `researcher`, `outliner`, `writer`, and `critic` agents, then in `blog_pipeline(topic)` call `await input=...)` followed by `await input= + [...])` and `await input=...)` sequentially. The generate-evaluate loop uses `for i in range(3)` to have the `critic` review, breaking if `"no issues"` is found, otherwise sending feedback back to `writer`. For parallel execution, use `asyncio.gather(*[ input=data) for a in agents])` to run sentiment, topic, and summary analyses concurrently. The Manager pattern uses `Agent(name="manager", tools=[ to call child agents as tools while retaining control. 🏗 Practical Patterns **LLM-Driven — Open-Ended Tasks** Equip a research agent with web search, file search, code execution, and specialist handoffs. The LLM dynamically selects the best approach based on context. Ideal for "investigate this technology" type queries where you can't predetermine the flow. **Code-Driven — Deterministic Pipelines** When steps are known upfront (research, outline, write, critique, improve), define the pipeline explicitly in Python. Each step's output can be programmatically validated and branched, giving you much tighter quality control. **Generate-Evaluate Loop** Use a `while`/`for` loop to repeatedly generate and evaluate until quality criteria are met. A critic agent reviews output until it passes — achieving quality that single-shot generation can't match. Always set a maximum iteration count. **Parallel Execution with asyncio.gather** Run independent tasks (sentiment analysis, topic extraction, summarization) concurrently with `asyncio.gather`. Dramatically reduces latency compared to sequential execution. **Manager Pattern (as_tool) vs Handoff** `as_tool` keeps the Manager in control — it calls child agents as tools and gets results back to synthesize. Use this when you need to combine outputs from multiple specialists. Handoffs transfer control entirely — use this when the specialist should handle the rest of the conversation independently. 💡 Use Cases 🔬 Research investigation (LLM-driven with dynamic web/paper/code analysis selection) 📝 Content creation pipeline (code-driven: research, write, review, improve) ⚡ Parallel data analysis (asyncio.gather for sentiment/topic/summary) 👔 Manager pattern (synthesize analysis team results into a unified report) ⚠️ Caveats - LLM-driven patterns are flexible but may produce unnecessary handoffs or tool calls due to model judgment errors. Use code-driven control for critical flows. - Always set a maximum iteration count on generate-evaluate loops. Unbounded loops cause runaway token costs. - When using `asyncio.gather` for parallel execution, consider `return_exceptions=True` so one task's failure doesn't cancel others. - Child agents called via `as_tool` return results as text to the Manager. Specify `output_type` if you need structured data. ✨ Combine LLM-driven and code-driven orchestration to build the optimal multi-agent architecture for each use case! #OpenAIAgentSDK# #AIAgent#

# Practical and Useful Patterns for OpenAI Agent SDK 🌍 When handing off between agents, wouldn't it be great to pass structured reasons and metadata along? Handoff inputs and on_handoff let you transfer context-rich data for seamless agent transitions. 📌 Title: Handoffs – Handoff inputs 🔗 URL: 🧩 Overview Handoff inputs allow the model to generate structured data (via a Pydantic model) that gets passed to the target agent during a handoff. Combined with the `on_handoff` callback, you can log escalation reasons, prefetch data the target agent needs, and inject additional context — all before the target agent starts processing. 🛠 Usage Define a Pydantic model `EscalationData(BaseModel)` with `reason: str`, `priority: str = "normal"`, and `customer_tier: str = "standard"` as structured handoff data. The `on_escalation(ctx: RunContext, input_data: EscalationData)` callback logs `input_data.reason` and `input_data.priority`, prefetches customer data using `ctx.context["customer_id"]`, and stores it in `ctx.context["customer_data"]`. Define `Agent(name="escalation", instructions="...")` as the escalation target and `Agent(name="triage", handoffs=[Handoff(agent=escalation_agent, input_type=EscalationData, on_handoff=on_escalation, handoff_description="Complex inquiries or urgent cases requiring escalation")])` as the triage agent. Execute with `await input="I was double-charged. I need this resolved immediately.", context={"customer_id": "C-12345"})`. 🏗 Practical Patterns **Structured Escalation Reasons** Define handoff reasons as typed Pydantic models like `EscalationData(reason, priority)`. Instead of free-text reasoning buried in conversation history, you get structured data that's easy to log, analyze, and act on programmatically. **Data Prefetching in on_handoff** Use the `on_handoff` callback to fetch data from databases or APIs that the target agent will need. This eliminates an extra tool-call round-trip after handoff, reducing latency. The target agent starts with all the context it needs. **Metadata Transfer** Pass `{"reason": "duplicate_charge", "priority": "high"}` to a refund agent so it can make policy decisions based on structured metadata rather than inferring from conversation history. More accurate, more reliable. **Audit Logging** Record handoff reasons, timing, and priority in `on_handoff` for audit trails. This data powers SLA dashboards and escalation trend analysis in customer support operations. 💡 Use Cases 🔄 Customer support escalation with structured reason and priority 💳 Refund processing handoffs with explicit cause (duplicate charge / defective item / cancellation) 📊 Escalation analytics via on_handoff logging to dashboards ⚡ Reduced target agent latency through on_handoff data prefetching ⚠️ Caveats - Too many required fields in `input_type` makes it harder for the model to generate accurate data. Keep required fields minimal and use defaults for optional ones. - Exceptions in `on_handoff` will fail the entire handoff. Wrap external API calls in try-except with fallback logic. - `on_handoff` runs synchronously. Heavy processing increases handoff latency — keep it lightweight. - Without `input_type`, the `on_handoff` callback does not receive an `input_data` argument. ✨ Use handoff inputs to pass structured context between agents and make your multi-agent transitions seamless! #OpenAIAgentSDK# #AIAgent#

# Useful but Little-Known Features of OpenAI Agent SDK 🌍 Did you know you can save an agent's state when it pauses for human approval and resume it later? With `to_state()` and interruptions, you can pause and resume agent runs that require approval workflows. 📌 Title: Pause/Resume with to_state() and Interruptions 🔗 URL: 🧩 Overview When a tool requires human approval, `result.interruptions` holds the pending approval requests. Call ` to capture the current execution as a resumable `RunState` snapshot, then use `state.approve()` or `state.reject()` for each interruption. Finally, pass the modified state back with ` state)` to resume. This works with direct tools, nested handoffs, and ` runs alike. 🛠 How to use it ```python from agents import Agent, Runner agent = Agent(name="Assistant", instructions="Use tools when needed.") result = await "Delete temp files...") # Check for pending interruptions if result.interruptions: # Capture a resumable state snapshot state = # Approve or reject each interruption for interruption in result.interruptions: state.approve(interruption) # state.reject(interruption) # to deny # Resume with the approved state result = await state) ``` 🏗 Building it into production ・Serialize `RunState` to a database for asynchronous approval workflows ・Integrate with Slack buttons or admin dashboards: approve, then ` to resume ・For streaming runs, fully consume `stream_events()` before accessing interruptions ・Approve or reject interruptions individually for fine-grained access control 💡 Use cases 🔐 Pre-approval for destructive operations like file deletion or data modification 💳 Human double-check before processing payments 📋 Multi-stage approval workflows with escalation 🔄 Checkpointing long-running processes for later resumption ⚠️ Watch out For streaming runs, accessing interruptions before fully consuming `stream_events()` yields incomplete results. Also, `RunState` is tied to the agent configuration at capture time. Resuming with a modified agent definition may cause unexpected behavior. ✨ Use to_state() to build safe agent workflows with human judgment in the loop. #OpenAIAgentSDK# #AIAgent#

# Useful but Little-Known Features of OpenAI Agent SDK 🌍 When your agent crashes mid-task, do you have to start over from scratch? Durable execution integrations preserve agent progress across failures, letting you resume right where you left off. 📌 Title: Durable Execution Integrations 🔗 URL: 🧩 Overview The OpenAI Agent SDK supports integration with multiple durable execution orchestrators. **Temporal** enables durable, long-running workflows. **Dapr** is a vendor-neutral CNCF orchestrator with automatic failure recovery. **Restate** provides a lightweight durable agent framework supporting processes, containers, and serverless. **DBOS** preserves agent progress using SQLite or Postgres. All four integrate with the standard `Runner` interface and support human-in-the-loop patterns (pause, approve, resume). 🛠 How to use it ```python # Temporal integration # pip install temporalio from temporalio.contrib.openai_agents import openai_workflow # Dapr integration # Set up Dapr CLI and runtime, then: # dapr run -- python agent_workflow.py # Restate integration # pip install restate-sdk # Deploy agents following Restate docs # DBOS integration # pip install dbos from dbos import DBOS # See official documentation for each orchestrator: # Temporal: # Dapr: # Restate: # DBOS: ``` 🏗 Building it into production ・Ensure failure resilience for long-running agents (research, data processing) ・Use human-in-the-loop patterns to pause agents awaiting approval and resume after sign-off ・If you already have orchestration infrastructure (Temporal/Dapr), run agents on top of it ・In serverless environments, use Restate or DBOS for lightweight agent durability 💡 Use cases 🔄 Long-running research agents that auto-resume after failures ✅ Workflow automation with human approval steps 🏗 Agent orchestration in microservices architectures 💾 Checkpointing agent progress for recovery ⚠️ Watch out Each orchestrator has its own infrastructure requirements (Temporal server, Dapr runtime, Restate service, DBOS database), so factor in operational cost and complexity when choosing. For vendor neutrality, consider Dapr (CNCF) or Restate. If you have existing workflow infrastructure, Temporal is a natural fit. For minimal setup, DBOS works well. Integration maturity varies, so thoroughly validate before production deployment. ✨ With durable execution, build agents that survive crashes and never lose progress. #OpenAIAgentSDK# #AIAgent#

# Practical and Useful Patterns for OpenAI Agent SDK 🌍 Is your handoff target drowning in irrelevant tool call history from previous agents? Input filters and recommended prompts ensure each agent receives exactly the context it needs. 📌 Title: Handoffs – Input filters / Recommended prompts 🔗 URL: 🧩 Overview Handoff input filters transform the conversation history passed to the target agent. `remove_all_tools` strips all tool call history, `nest_handoff_history` (beta) compresses multi-handoff history into a single summary message. Additionally, `RECOMMENDED_PROMPT_PREFIX` helps the LLM correctly understand the handoff mechanism and make better routing decisions. 🛠 Usage Define `Agent(name="faq", instructions="Answer frequently asked questions. Keep responses simple.")` and `Agent(name="specialist", instructions="Answer advanced technical questions.")`. The triage agent is `Agent(name="triage", instructions=RECOMMENDED_PROMPT_PREFIX + "\nClassify customer inquiries and route to the appropriate specialist.", handoffs=[...])`, where the FAQ handoff uses `Handoff(agent=faq_agent, input_filter=handoff_filters.remove_all_tools, handoff_description="General FAQ questions")` to strip tool history, and the specialist handoff uses `Handoff(agent=specialist_agent, input_filter=handoff_filters.nest_handoff_history, handoff_description="Advanced technical questions")` to compress history. Import `RECOMMENDED_PROMPT_PREFIX` from `agents.extensions.handoff_prompt`. 🏗 Practical Patterns **Clean Handoffs with remove_all_tools** When a triage agent uses multiple tools (DB queries, API calls) before handing off to an FAQ agent, that tool history is noise for the FAQ agent. `remove_all_tools` strips all tool-related messages, giving the target agent a clean conversation history. This also reduces token consumption. **History Compression with nest_handoff_history (beta)** In multi-hop handoffs (A to B to C), history accumulates rapidly. `nest_handoff_history` compresses prior handoff history into a single summary message, using the context window much more efficiently for the final agent. **RECOMMENDED_PROMPT_PREFIX for Accurate Routing** Including `prompt_with_handoff_instructions()` or `RECOMMENDED_PROMPT_PREFIX` in an agent's `instructions` helps the LLM understand available handoff targets and when to use them. Without this, the model may try to answer questions itself instead of delegating to the right specialist. **Custom Filters** When built-in filters aren't enough, create custom ones: keep only the last 5 messages, remove messages containing sensitive data, or preserve only specific tool call results. Tailor the handoff input to exactly what the target agent needs. 💡 Use Cases 🧹 Strip tool history before handing off to a simple FAQ agent 📦 Compress multi-hop handoff history to optimize token usage 🤖 Improve handoff routing accuracy with RECOMMENDED_PROMPT_PREFIX 🔒 Filter out messages containing sensitive information before handoff ⚠️ Caveats - `remove_all_tools` removes ALL tool-related messages. Don't use it if the target agent needs to reference tool results. - `nest_handoff_history` is a beta feature. Compression behavior may change in future releases. - When using `RECOMMENDED_PROMPT_PREFIX`, prepend it to existing `instructions`. Appending at the end may reduce its effectiveness. - Custom filters should only add or remove messages — not reorder them or change roles, which can cause unpredictable model behavior. ✨ Optimize handoff inputs with filters so each agent receives exactly the context it needs to perform at its best! #OpenAIAgentSDK# #AIAgent#