> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neosantara.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Build autonomous multi-agent systems with the OpenAI Agents SDK and Neosantara via LiteLLM or direct client adapters.

The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python?utm_source=neosantara-docs\&utm_medium=referral) is OpenAI's official multi-agent orchestration framework designed for agentic loops, autonomous handoffs, and function tool execution. It integrates flexibly with Neosantara via the `LitellmModel` extension or standard direct client endpoints.

## Setup

Install the OpenAI Agents SDK package with the LiteLLM extension:

```bash theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
pip install "openai-agents[litellm]"
```

<CodeGroup>
  ```bash Bash / zsh icon="terminal" theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
  export NEOSANTARA_API_KEY="nsk_your_api_key_here"
  ```

  ```env .env icon="file-code" theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
  NEOSANTARA_API_KEY=nsk_your_api_key_here
  ```

  ```powershell PowerShell icon="terminal" theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
  $env:NEOSANTARA_API_KEY="nsk_your_api_key_here"
  ```
</CodeGroup>

## Integration via LiteLLM Model

Use the `LitellmModel` class with the `neosantara/<model>` prefix to execute gateway models. Credentials are automatically read from the `NEOSANTARA_API_KEY` environment variable:

```python theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
import os
from agents import Agent, Runner, set_tracing_disabled
from agents.extensions.models.litellm_model import LitellmModel

# Disable OpenAI tracing to eliminate OPENAI_API_KEY requirement
set_tracing_disabled(True)

# Initialize agent with Neosantara model
agent = Agent(
    name="Researcher",
    instructions="You are a technology infrastructure analyst providing concise, factual information.",
    model=LitellmModel(model="neosantara/gemini-3.8-flash")
)

result = Runner.run_sync(agent, "Explain the architecture of a regional AI gateway in one paragraph.")
print(result.final_output)
```

## Direct Client Integration

You can also point the default OpenAI client directly to the Neosantara gateway base URL (`https://api.neosantara.xyz/v1`):

```python theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
import os
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client, set_default_openai_api, set_tracing_disabled

set_tracing_disabled(True)

# Configure global Neosantara client
client = AsyncOpenAI(
    base_url="https://api.neosantara.xyz/v1",
    api_key=os.environ["NEOSANTARA_API_KEY"]
)
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")

agent = Agent(
    name="ArchitectBot",
    instructions="Answer technical infrastructure questions with rigorous detail.",
    model="deepseek-v4.1-flash"
)

result = Runner.run_sync(agent, "Compare local regional latency against global API endpoints.")
print(result.final_output)
```

## Function and Tool Calling

Define standard Python functions with the `@function_tool` decorator to equip agents with tool-calling capabilities:

```python theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
import os
from openai import AsyncOpenAI
from agents import Agent, Runner, function_tool, set_default_openai_client, set_default_openai_api, set_tracing_disabled

set_tracing_disabled(True)

client = AsyncOpenAI(
    base_url="https://api.neosantara.xyz/v1",
    api_key=os.environ["NEOSANTARA_API_KEY"]
)
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")

@function_tool
def check_tier_limits(tier: str) -> str:
    """Check RPM and ITPM rate limit ceilings for a specific Neosantara service tier."""
    limits = {
        "free": "10 RPM, 30,000 ITPM",
        "basic": "50 RPM, 500,000 ITPM",
        "standard": "1,000 RPM, 2,000,000 ITPM"
    }
    return limits.get(tier.lower(), "Tier not found.")

agent = Agent(
    name="QuotaSupport",
    instructions="Use check_tier_limits to answer user questions about throughput limits.",
    model="gemini-3.8-flash",
    tools=[check_tier_limits]
)

result = Runner.run_sync(agent, "What are the rate limits for the Basic tier?")
print(result.final_output)
```

## Agent Handoffs

The OpenAI Agents SDK relies on *handoffs* to transfer context and execution autonomously between specialized agents:

```python theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
import os
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client, set_default_openai_api, set_tracing_disabled

set_tracing_disabled(True)

client = AsyncOpenAI(
    base_url="https://api.neosantara.xyz/v1",
    api_key=os.environ["NEOSANTARA_API_KEY"]
)
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")

# Specialist agent for complex debugging
code_specialist = Agent(
    name="CodeSpecialist",
    instructions="You specialize in systems debugging and algorithm optimization. Resolve code issues thoroughly.",
    model="deepseek-v4.1-flash"
)

# Frontline triage agent
triage_agent = Agent(
    name="TriageAgent",
    instructions="Evaluate incoming requests. If the query requires code debugging or system architecture advice, hand off to CodeSpecialist.",
    model="gemini-3.8-flash",
    handoffs=[code_specialist]
)

result = Runner.run_sync(triage_agent, "I have a race condition in my Go concurrency pool, please help optimize it.")
print(result.final_output)
```

## Next Steps

* [Model Context Protocol (MCP) Guide](/en/agents/overview)
* [Model Catalog & Pricing](/en/gateway/models)
* [LiteLLM Native Integration](/en/integrations/litellm)
* [Google ADK Integration](/en/integrations/google-adk)


## Related topics

- [LiteLLM](/en/integrations/litellm.md)
- [Google ADK](/en/integrations/google-adk.md)
- [CrewAI](/en/integrations/crewai.md)
- [Chat Completions](/en/gateway/chat-completions.md)