> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/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

**1. Design in Agent Builder**

Open [OpenAI Agent Builder](https://platform.openai.com/playground/agent-builder) and create your workflow using the visual canvas.

![](https://mintcdn.com/portkey-docs/yp2Ps0cNckQLzo91/images/libraries/openai-agent-builder.webp?fit=max\&auto=format\&n=yp2Ps0cNckQLzo91\&q=85\&s=dd2ae7746dd8a5d4332c90e6a886ce07)

**2. Export Code**

Click **Code** → **Agents SDK** to get the Python implementation.

![](https://mintcdn.com/portkey-docs/yp2Ps0cNckQLzo91/images/libraries/agent-builder-2.png?fit=max\&auto=format\&n=yp2Ps0cNckQLzo91\&q=85\&s=c6a4890ddca39435ac2417686e18faee)

**3. Install Packages**

```bash theme={"system"}
pip install -U openai-agents portkey-ai
```

**4. Add Portkey**

Replace the OpenAI client with Portkey:

```python theme={"system"}
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...
```

> [!NOTE]
>
> Update the `model` field to use Portkey's format: `@openai-prod/gpt-4o`

## Setup

**1. Add Provider in Model Catalog**

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`.

**2. Get Portkey API Key**

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:

![](https://mintcdn.com/portkey-docs/_Cb_bj7tVjxcfwsu/images/product/product-11-1.webp?fit=max\&auto=format\&n=_Cb_bj7tVjxcfwsu\&q=85\&s=d64ccfdd125ef6ca39bc3e344d7411a4)

Add trace IDs and metadata for filtering:

```python theme={"system"}
default_headers=createHeaders(
    provider="@openai-prod",
    trace_id="workflow-session-123",
    metadata={
        "workflow_type": "research",
        "_user": "user_123",
        "environment": "production"
    }
)
```

![Analytics with metadata filters](https://mintcdn.com/portkey-docs/EKxolPDRqqOR-ZgU/images/metadata.png?fit=max\&auto=format\&n=EKxolPDRqqOR-ZgU\&q=85\&s=43e9a3ef202a9d61460a098c4bb78218)

### Reliability

Enable fallbacks via [Configs](https://app.portkey.ai/configs):

```python theme={"system"}
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" } }
            ]
        }
    )
)
```

> [card] [Automatic Retries](https://docs.portkey.ai/docs/product/ai-gateway/automatic-retries.md)
>
> Handles temporary failures automatically

> [card] [Load Balancing](https://docs.portkey.ai/docs/product/ai-gateway/load-balancing.md)
>
> Distribute across multiple keys

> [card] [Conditional Routing](https://docs.portkey.ai/docs/product/ai-gateway/conditional-routing.md)
>
> Route based on request attributes

> [card] [Fallbacks](https://docs.portkey.ai/docs/product/ai-gateway/fallbacks.md)
>
> Switch to backup providers automatically

### Guardrails

Add input/output validation:

```python theme={"system"}
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

> [card] [Guardrails Guide](https://docs.portkey.ai/docs/product/guardrails.md)
>
> PII detection, content filtering, and custom rules

### Caching

Reduce costs with response caching:

```python theme={"system"}
default_headers=createHeaders(
    provider="@openai-prod",
    config={ "cache": { "mode": "semantic" } }
)
```

### Prompt Templates

Use Portkey's prompt management for versioned prompts:

```python theme={"system"}
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"
)
```

> [card] [Prompt Engineering Studio](https://docs.portkey.ai/docs/product/prompt-library.md)
>
> Prompt versioning and collaboration

## Switching Providers

Use any of 1600+ models:

```python theme={"system"}
# OpenAI
createHeaders(provider="@openai-prod")

# Anthropic
createHeaders(provider="@anthropic-prod")

# Google
createHeaders(provider="@google-prod")
```

> [card] [Supported Providers](https://docs.portkey.ai/docs/integrations/llms.md)
>
> See all 1600+ supported models

## Enterprise Governance

Set up centralized control for your workflows.

**1. Add Provider with Budget**

Go to [Model Catalog](https://app.portkey.ai/model-catalog) → Add Provider. Set budget limits and rate limits.

**2. Create Config**

Go to [Configs](https://app.portkey.ai/configs):

```json theme={"system"}
{
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

**3. Create Team API Keys**

Go to [API Keys](https://app.portkey.ai/api-keys). Create keys per team, attach configs.

**4. Distribute to Teams**

Teams use their Portkey API key:

```python theme={"system"}
client = AsyncOpenAI(
    base_url=PORTKEY_GATEWAY_URL,
    api_key="TEAM_PORTKEY_API_KEY"  # Config attached to key
)
```

> [card] [Enterprise Features](https://docs.portkey.ai/docs/product/enterprise-offering.md)
>
> Governance, security, and compliance

## FAQ

> [accordion] Can I use Portkey with existing Agent Builder workflows?
>
> Yes. Export your workflow, add Portkey client initialization, and your code works unchanged.

> [accordion] Does Portkey work with all Agent Builder features?
>
> Yes. Handoffs, tools, guardrails—all work with Portkey observability and reliability.

> [accordion] How do I track workflow costs?
>
> Add metadata to your requests. Filter by workflow type, user, or environment in the dashboard.

> [accordion] Can I use my own API keys?
>
> Yes. Portkey stores your provider keys securely. Rotate keys without code changes.

## Resources

> [card] [OpenAI Agents SDK](https://docs.portkey.ai/docs/integrations/agents/openai-agents.md)
>
> Full SDK integration guide

> [card] [Configs](https://docs.portkey.ai/docs/product/ai-gateway/configs.md)
>
> Fallbacks, caching, and routing

> [card] [OpenAI Agents Docs](https://openai.github.io/openai-agents-python/)
>
> Official documentation

> [card] [Book a Demo](https://www.paloaltonetworks.com/ai-security/ai-gateway#:~:text=See%20Prisma%20AIRS%20AI%20Gateway%20in%20Action)
>
> Get implementation guidance

***

> [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact)
>
> Contact Us


## Related topics

- [Overview](https://docs.portkey.ai/docs/integrations/libraries.md)
- [OpenAI Agents SDK (Python)](https://docs.portkey.ai/docs/integrations/agents/openai-agents.md)
- [OpenAI Agent Builder (TypeScript)](https://docs.portkey.ai/docs/integrations/libraries/openai-agent-builder.md)
- [OpenAI Agents SDK (TypeScript)](https://docs.portkey.ai/docs/integrations/agents/openai-agents-ts.md)
- [Python](https://docs.portkey.ai/docs/api-reference/sdk/python.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.