> ## 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 Prisma AIRS AI Gateway 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 the AI Gateway for:

* Complete observability of agent workflows
* Cost tracking and optimization
* Reliability features (fallbacks, retries)
* Access to 3,000+ LLMs
* Guardrails for safe agent behaviour

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

**4. Add the AI Gateway**

Replace the OpenAI client with the AI Gateway:

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

const client = new OpenAI({
    baseURL: "https://aigw.portkey.ai/v1",
    apiKey: 'YOUR_PORTKEY_API_KEY',
    defaultHeaders: { "x-portkey-provider": '@openai-prod' }
});
setDefaultOpenAIClient(client);
setOpenAIAPI('chat_completions');

// Your Agent Builder workflow code continues as exported...
```

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

## Setup

**1. Add Provider in Model Catalog**

Go to [Model Catalog → Add Provider](https://stratacloudmanager.paloaltonetworks.com/). Select your provider (OpenAI, Anthropic, etc.), enter API keys, and name it (e.g., `openai-prod`).

Your provider slug is `@openai-prod`.

**2. Get AI Gateway API Key**

Create an API key at [stratacloudmanager.paloaltonetworks.com](https://stratacloudmanager.paloaltonetworks.com/).

**Pro tip:** Attach a [config](https://stratacloudmanager.paloaltonetworks.com/) 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: {
    "x-portkey-provider": '@openai-prod',
    "x-portkey-trace-id": 'workflow-session-123',
    "x-portkey-metadata": JSON.stringify({
        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://stratacloudmanager.paloaltonetworks.com/):

```typescript theme={"system"}
const client = new OpenAI({
    baseURL: "https://aigw.portkey.ai/v1",
    apiKey: 'YOUR_PORTKEY_API_KEY',
    defaultHeaders: {
        "x-portkey-config": JSON.stringify({
            strategy: { mode: 'fallback' },
            targets: [
                { override_params: { model: '@openai-prod/gpt-4o' } },
                { override_params: { model: '@anthropic-prod/claude-sonnet-4' } }
            ]
        }),
    }
});
```

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

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

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

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

### Guardrails

Add input/output validation:

```typescript theme={"system"}
defaultHeaders: {
    "x-portkey-provider": '@openai-prod',
    "x-portkey-config": JSON.stringify({
        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

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

### Caching

Reduce costs with response caching:

```typescript theme={"system"}
defaultHeaders: {
    "x-portkey-provider": '@openai-prod',
    "x-portkey-config": JSON.stringify({ cache: { mode: 'semantic' } }),
}
```

## Switching Providers

Use any of 3,000+ models:

```typescript theme={"system"}
// Prefix the model with the provider slug to pick the integration.
model: '@openai-prod/gpt-4o'
model: '@anthropic-prod/claude-sonnet-4-20250514'
model: '@google-prod/gemini-2.0-flash'
```

> **[Supported Providers](https://docs.portkey.ai/docs/aigw/integrations/llms.md)**
>
> See all 3,000+ supported models

## Governance

Set up centralized control for your workflows.

**1. Add Provider with Budget**

Go to [Model Catalog](https://stratacloudmanager.paloaltonetworks.com/) → Add Provider. Set budget limits and rate limits.

**2. Create Config**

Go to [Configs](https://stratacloudmanager.paloaltonetworks.com/):

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

**3. Create Team API Keys**

Go to [API Keys](https://stratacloudmanager.paloaltonetworks.com/). Create keys per team, attach configs.

**4. Distribute to Teams**

Teams use their AI Gateway API key:

```typescript theme={"system"}
const client = new OpenAI({
    baseURL: "https://aigw.portkey.ai/v1",
    apiKey: 'TEAM_PORTKEY_API_KEY'  // Config attached to key
});
```

> **[Governance & Administration](https://docs.portkey.ai/docs/aigw/introduction/feature-overview.md#governance-%26-administration)**
>
> Access control, encryption, and audit trails

## FAQ

> **Can I use the AI Gateway with existing Agent Builder workflows?**
>
> Yes. Export your workflow, add AI Gateway client initialization, and your code works unchanged.

> **Does the AI Gateway work with all Agent Builder features?**
>
> Yes. Handoffs, tools, guardrails—all work with the AI Gateway observability and reliability.

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

> **Can I use my own API keys?**
>
> Yes. The AI Gateway stores your provider keys securely. Rotate keys without code changes.

## Resources

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

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

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


## Related topics

- [OpenAI Agents SDK (TypeScript)](https://docs.portkey.ai/docs/aigw/integrations/agents/openai-agents-ts.md)
- [OpenAI Agent Builder (Python)](https://docs.portkey.ai/docs/aigw/integrations/libraries/openai-agent-builder-python.md)
- [AWS AgentCore](https://docs.portkey.ai/docs/aigw/integrations/agents/agentcore.md)
- [Agentic Usage](https://docs.portkey.ai/docs/aigw/api-reference/inference-api/agentic-usage.md)
- [Mastra Agents](https://docs.portkey.ai/docs/aigw/integrations/agents/mastra-agents.md)


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