> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-add-third-party-integration-issues-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAI Agent Builder (Python)
> Add Portkey to visual agent workflows exported from OpenAI Agent Builder.
OpenAI Agent Builder is a visual canvas for creating multi-step agent workflows. Export production-ready Python code and add Portkey for:
* Complete observability of agent workflows
* Cost tracking and optimization
* Reliability features (fallbacks, retries)
* Access to 1600+ LLMs
* Guardrails for safe agent behavior
## Quick Start
Open [OpenAI Agent Builder](https://platform.openai.com/playground/agent-builder) and create your workflow using the visual canvas.
Click **Code** → **Agents SDK** to get the Python implementation.
```bash theme={null}
pip install -U openai-agents portkey-ai
```
Replace the OpenAI client with Portkey:
```python theme={null}
from agents import Agent, Runner, set_default_openai_client, set_default_openai_api
from openai import AsyncOpenAI
from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders
client = AsyncOpenAI(
base_url=PORTKEY_GATEWAY_URL,
api_key="YOUR_PORTKEY_API_KEY",
default_headers=createHeaders(provider="@openai-prod")
)
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
# Your Agent Builder workflow code continues as exported...
```
Update the `model` field to use Portkey's format: `@openai-prod/gpt-4o`
## Setup
Go to [Model Catalog → Add Provider](https://app.portkey.ai/model-catalog). Select your provider (OpenAI, Anthropic, etc.), enter API keys, and name it (e.g., `openai-prod`).
Your provider slug is `@openai-prod`.
Create an API key at [app.portkey.ai/api-keys](https://app.portkey.ai/api-keys).
**Pro tip:** Attach a [config](https://app.portkey.ai/configs) for fallbacks, caching, and guardrails—applies automatically.
## Production Features
### Observability
All workflow executions are logged:
Add trace IDs and metadata for filtering:
```python theme={null}
default_headers=createHeaders(
provider="@openai-prod",
trace_id="workflow-session-123",
metadata={
"workflow_type": "research",
"_user": "user_123",
"environment": "production"
}
)
```
### Reliability
Enable fallbacks via [Configs](https://app.portkey.ai/configs):
```python theme={null}
client = AsyncOpenAI(
base_url=PORTKEY_GATEWAY_URL,
api_key="YOUR_PORTKEY_API_KEY",
default_headers=createHeaders(
config={
"strategy": { "mode": "fallback" },
"targets": [
{ "override_params": { "model": "@openai-prod/gpt-4o" } },
{ "override_params": { "model": "@anthropic-prod/claude-sonnet-4" } }
]
}
)
)
```
Handles temporary failures automatically
Distribute across multiple keys
Route based on request attributes
Switch to backup providers automatically
### Guardrails
Add input/output validation:
```python theme={null}
default_headers=createHeaders(
provider="@openai-prod",
config={
"input_guardrails": ["guardrail-id-xxx"],
"output_guardrails": ["guardrail-id-yyy"]
}
)
```
Guardrails can:
* Detect and redact PII
* Filter harmful content
* Validate response formats
* Apply custom business rules
PII detection, content filtering, and custom rules
### Caching
Reduce costs with response caching:
```python theme={null}
default_headers=createHeaders(
provider="@openai-prod",
config={ "cache": { "mode": "semantic" } }
)
```
### Prompt Templates
Use Portkey's prompt management for versioned prompts:
```python theme={null}
from portkey_ai import Portkey
portkey = Portkey(api_key="YOUR_PORTKEY_API_KEY")
prompt_data = portkey.prompts.render(
prompt_id="YOUR_PROMPT_ID",
variables={"task": "research"}
)
agent = Agent(
name="Assistant",
instructions=prompt_data.data.messages[0]["content"],
model="@openai-prod/gpt-4o"
)
```
Prompt versioning and collaboration
## Switching Providers
Use any of 1600+ models:
```python theme={null}
# OpenAI
createHeaders(provider="@openai-prod")
# Anthropic
createHeaders(provider="@anthropic-prod")
# Google
createHeaders(provider="@google-prod")
```
See all 1600+ supported models
## Enterprise Governance
Set up centralized control for your workflows.
Go to [Model Catalog](https://app.portkey.ai/model-catalog) → Add Provider. Set budget limits and rate limits.
Go to [Configs](https://app.portkey.ai/configs):
```json theme={null}
{
"override_params": { "model": "@openai-prod/gpt-4o" }
}
```
Go to [API Keys](https://app.portkey.ai/api-keys). Create keys per team, attach configs.
Teams use their Portkey API key:
```python theme={null}
client = AsyncOpenAI(
base_url=PORTKEY_GATEWAY_URL,
api_key="TEAM_PORTKEY_API_KEY" # Config attached to key
)
```
Governance, security, and compliance
## FAQ
Yes. Export your workflow, add Portkey client initialization, and your code works unchanged.
Yes. Handoffs, tools, guardrails—all work with Portkey observability and reliability.
Add metadata to your requests. Filter by workflow type, user, or environment in the dashboard.
Yes. Portkey stores your provider keys securely. Rotate keys without code changes.
## Resources
Full SDK integration guide
Fallbacks, caching, and routing
Official documentation
Get implementation guidance