OpenAI Agents SDK - TrueFoundry Docs

This guide provides instructions for integrating OpenAI Agents SDK with TrueFoundry’s AI Gateway.

Python SDK Documentation

Official OpenAI Agents SDK for Python

TypeScript SDK Documentation

Official OpenAI Agents SDK for JavaScript/TypeScript

What is OpenAI Agents SDK?

OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs. The SDK provides automatic tracing, session management, and support for complex agent patterns including handoffs, function calling, and human-in-the-loop workflows.

Key Features of OpenAI Agents SDK

Multi-Agent Workflows: Build teams of specialized agents that can hand off tasks to each other and collaborate on complex workflows
Function Tools: Equip agents with custom functions to interact with external systems and APIs
Session Memory: Built-in conversation history management across multiple agent runs
Automatic Tracing: Extensible tracing support with external destinations like Logfire, AgentOps, and Braintrust

How TrueFoundry Integrates with OpenAI Agents SDK

TrueFoundry enhances OpenAI Agents SDK with production-grade observability, cost management, and multi-provider support through its LLM Gateway.

Installation & Setup

Install OpenAI Agents SDK

Python
TypeScript

pip install openai-agents

npm install @openai/agents openai zod

Why Zod? The OpenAI Agents SDK uses Zod for schema validation and type-safe parameter definitions in function tools. This provides automatic runtime validation and better TypeScript type inference.

Get TrueFoundry Access Token

Sign up for a TrueFoundry account
Follow the steps here in Quick start

Configure OpenAI Agents SDK with TrueFoundry

Python
TypeScript

from agents import Agent, OpenAIChatCompletionsModel, Runner
from openai import AsyncOpenAI
import asyncio

# Configure AsyncOpenAI client with TrueFoundry
client = AsyncOpenAI(
    base_url="{GATEWAY_BASE_URL}",
    api_key="your_truefoundry_api_key"
)

async def main():
    # Create agent with TrueFoundry client
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant",
        model=OpenAIChatCompletionsModel(
            model="openai-main/gpt-4o",  
            openai_client=client
        )
    )

    # Run the agent
    result = await Runner.run(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Why AsyncOpenAI? The OpenAI Agents SDK is built on async/await patterns for non-blocking operations. While you can use the synchronous OpenAI client, AsyncOpenAI is recommended for production as it allows your agents to handle concurrent requests efficiently without blocking.

import { Agent, Runner, setDefaultOpenAIClient } from '@openai/agents';
import OpenAI from 'openai';

// Configure OpenAI client with TrueFoundry
const client = new OpenAI({
  baseURL: "{GATEWAY_BASE_URL}",
  apiKey: "your-truefoundry-api-key"
});

// Set as default client for all agents
// @ts-ignore - Version conflict between openai packages
setDefaultOpenAIClient(client);

// Create agent
const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant",
  model: "openai-main/gpt-4o"  // Format: provider-name/model-name
});

// Run the agent
const runner = new Runner();
const result = await runner.run(agent, "Write a haiku about recursion in programming.");
console.log(result.finalOutput);

Complete Example with Handoffs

Python
TypeScript

from agents import Agent, OpenAIChatCompletionsModel, Runner
from openai import AsyncOpenAI
import asyncio

# Configure TrueFoundry client
client = AsyncOpenAI(
    base_url="{GATEWAY_BASE_URL}",
    api_key="your_truefoundry_api_key"
)

# Create model instance to reuse
model = OpenAIChatCompletionsModel(
    model="openai-main/gpt-4o",
    openai_client=client
)

# Create specialized agents
spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
    model=model
)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
    model=model
)

# Create triage agent with handoffs
triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    model=model,
    handoffs=[spanish_agent, english_agent]
)

async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)
    # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?

if __name__ == "__main__":
    asyncio.run(main())

import { Agent, Runner, setDefaultOpenAIClient } from '@openai/agents';
import OpenAI from 'openai';

// Configure OpenAI client with TrueFoundry
const client = new OpenAI({
  baseURL: "{GATEWAY_BASE_URL}",
  apiKey: "your-truefoundry-api-key"
});

// Set as default client for all agents
// @ts-ignore - Version conflict between openai packages
setDefaultOpenAIClient(client);

// Create specialized agents
const spanishAgent = new Agent({
  name: "Spanish agent",
  instructions: "You only speak Spanish.",
  model: "openai-main/gpt-4o"
});

const englishAgent = new Agent({
  name: "English agent",
  instructions: "You only speak English",
  model: "openai-main/gpt-4o"
});

// Create triage agent with handoffs
const triageAgent = new Agent({
  name: "Triage agent",
  instructions: "Handoff to the appropriate agent based on the language of the request.",
  model: "openai-main/gpt-4o",
  handoffs: [spanishAgent, englishAgent]
});

const runner = new Runner();
const result = await runner.run(triageAgent, "Hola, ¿cómo estás?");
console.log(result.finalOutput);
// ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?

Example with Function Tools

Python
TypeScript

from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool
from openai import AsyncOpenAI
import asyncio

# Configure TrueFoundry client
client = AsyncOpenAI(
    base_url="{GATEWAY_BASE_URL}",
    api_key="your_truefoundry_api_key"
)

@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a city"""
    print(f"[debug] getting weather for {city}")
    return f"The weather in {city} is sunny."

async def main():
    agent = Agent(
        name="Weather Assistant",
        instructions="You are a helpful weather assistant.",
        model=OpenAIChatCompletionsModel(
            model="openai-main/gpt-4o",
            openai_client=client
        ),
        tools=[get_weather]
    )

    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)
    # The weather in Tokyo is sunny.

if __name__ == "__main__":
    asyncio.run(main())

import { Agent, Runner, setDefaultOpenAIClient, tool } from '@openai/agents';
import OpenAI from 'openai';
import { z } from 'zod';

// Configure OpenAI client with TrueFoundry
const client = new OpenAI({
  baseURL: "{GATEWAY_BASE_URL}",
  apiKey: "your-truefoundry-api-key"
});

// @ts-ignore - Version conflict between openai packages
setDefaultOpenAIClient(client);

// Define weather tool
const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the current weather for a given city',
  parameters: z.object({
    city: z.string().describe('The name of the city'),
  }),
  async execute({ city }) {
    console.log(`[debug] getting weather for ${city}`);
    return `The weather in ${city} is sunny and 22°C`;
  },
});

// Create agent with the tool
const agent = new Agent({
  name: "Weather Assistant",
  instructions: "You are a helpful weather assistant. Use the get_weather tool to provide accurate weather information.",
  model: "openai-main/gpt-4o",
  tools: [getWeatherTool]
});

// Run the agent
const runner = new Runner();
const result = await runner.run(agent, "What's the weather in Tokyo?");
console.log(result.finalOutput);
// Based on the current information, the weather in Tokyo is sunny and 22°C.

Observability and Governance

Monitor your OpenAI Agents through TrueFoundry’s metrics tab:

TrueFoundry metrics dashboard showing usage statistics, costs, and performance metrics

With TrueFoundry’s AI Gateway, you can monitor and analyze:

Performance Metrics: Track key latency metrics like Request Latency, Time to First Token (TTFS), and Inter-Token Latency (ITL) with P99, P90, and P50 percentiles
Cost and Token Usage: Gain visibility into your application’s costs with detailed breakdowns of input/output tokens and the associated expenses for each model
Usage Patterns: Understand how your application is being used with detailed analytics on user activity, model distribution, and team-based usage
Agent Execution Traces: Monitor individual agent runs with complete visibility into tool usage, handoffs, and state transitions
Rate Limiting and Virtual Models: Set up rate limiting and configure Virtual Models for intelligent routing and fallback across your models

Python SDK Documentation

TypeScript SDK Documentation

​What is OpenAI Agents SDK?

​Key Features of OpenAI Agents SDK

​How TrueFoundry Integrates with OpenAI Agents SDK

​Installation & Setup

​Complete Example with Handoffs

​Example with Function Tools

​Observability and Governance

What is OpenAI Agents SDK?

Key Features of OpenAI Agents SDK

How TrueFoundry Integrates with OpenAI Agents SDK

Installation & Setup

Complete Example with Handoffs

Example with Function Tools

Observability and Governance