> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-chore-v2-11-2.mintlify.site/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
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 TypeScript implementation.
```bash theme={null}
npm install @openai/agents openai portkey-ai
```
Replace the OpenAI client with Portkey:
```typescript theme={null}
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...
```
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:
```typescript theme={null}
defaultHeaders: createHeaders({
provider: '@openai-prod',
traceId: 'workflow-session-123',
metadata: {
workflow_type: 'research',
_user: 'user_123',
environment: 'production'
}
})
```
### Reliability
Enable fallbacks via [Configs](https://app.portkey.ai/configs):
```typescript theme={null}
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' } }
]
}
})
});
```
Handles temporary failures automatically
Distribute across multiple keys
Route based on request attributes
Switch to backup providers automatically
### Guardrails
Add input/output validation:
```typescript theme={null}
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
PII detection, content filtering, and custom rules
### Caching
Reduce costs with response caching:
```typescript theme={null}
defaultHeaders: createHeaders({
provider: '@openai-prod',
config: { cache: { mode: 'semantic' } }
})
```
### Prompt Templates
Use Portkey's prompt management for versioned prompts:
```typescript theme={null}
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'
});
```
Prompt versioning and collaboration
## Switching Providers
Use any of 1600+ models:
```typescript 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:
```typescript theme={null}
const client = new OpenAI({
baseURL: PORTKEY_GATEWAY_URL,
apiKey: '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