> ## 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 (TypeScript)

> 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 TypeScript 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 TypeScript 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"}
npm install @openai/agents openai portkey-ai
```

**4. Add Portkey**

Replace the OpenAI client with Portkey:

```typescript theme={"system"}
import { Agent, run, setDefaultOpenAIClient, setOpenAIAPI } from '@openai/agents';
import { OpenAI } from 'openai';
import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai';

const client = new OpenAI({
    baseURL: PORTKEY_GATEWAY_URL,
    apiKey: 'YOUR_PORTKEY_API_KEY',
    defaultHeaders: createHeaders({ provider: '@openai-prod' })
});
setDefaultOpenAIClient(client);
setOpenAIAPI('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:

```typescript theme={"system"}
defaultHeaders: createHeaders({
    provider: '@openai-prod',
    traceId: '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):

```typescript theme={"system"}
const client = new OpenAI({
    baseURL: PORTKEY_GATEWAY_URL,
    apiKey: 'YOUR_PORTKEY_API_KEY',
    defaultHeaders: 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:

```typescript theme={"system"}
defaultHeaders: 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:

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

### Prompt Templates

Use Portkey's prompt management for versioned prompts:

```typescript theme={"system"}
import { Portkey } from 'portkey-ai';

const portkey = new Portkey({ apiKey: 'YOUR_PORTKEY_API_KEY' });

const promptData = await portkey.prompts.render({
    promptId: 'YOUR_PROMPT_ID',
    variables: { task: 'research' }
});

const agent = new Agent({
    name: 'Assistant',
    instructions: promptData.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:

```typescript 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:

```typescript theme={"system"}
const client = new OpenAI({
    baseURL: PORTKEY_GATEWAY_URL,
    apiKey: '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-ts.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-js/)
>
> 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

- [OpenAI Agents SDK (TypeScript)](https://docs.portkey.ai/docs/integrations/agents/openai-agents-ts.md)
- [OpenAI Agent Builder (Python)](https://docs.portkey.ai/docs/integrations/libraries/openai-agent-builder-python.md)
- [June](https://docs.portkey.ai/docs/changelog/2025/june.md)
- [AWS AgentCore](https://docs.portkey.ai/docs/integrations/agents/agentcore.md)
- [OpenAI Agents SDK (Python)](https://docs.portkey.ai/docs/integrations/agents/openai-agents.md)


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