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

# OpenAI Agents SDK

> Deploy an OpenAI Agents SDK agent as it is: streamed text, tool calls and results, and each handoff as a step.

## What is supported

`openai-agents` 0.21 and later. Onecortex recognises an `Agent` and runs it with the SDK's `Runner`, streamed. You do not call `Runner` yourself.

## A complete agent

```yaml agent.yml theme={null}
apiVersion: v1
runtime: python3.12
entrypoint: agent.py:agent
dependencies: requirements.txt
```

```text requirements.txt theme={null}
openai-agents>=0.21
```

```python agent.py theme={null}
from agents import Agent, function_tool


@function_tool
def word_count(text: str) -> int:
    """Counts the words in a piece of text."""
    return len(text.split())


# Reads OPENAI_API_KEY, which you add as a secret on the agent's Config tab.
agent = Agent(
    name="Assistant",
    instructions="Count the words in what the user says, then answer.",
    model="gpt-5",
    tools=[word_count],
)
```

Add `OPENAI_API_KEY` as a secret on the agent's **Config** tab, then deploy. Any model works: this one is an example. See [Configuration and secrets](/build/configuration).

<Card title="A complete OpenAI Agents SDK example" icon="github" href="https://github.com/onecortex-io/examples/tree/main/travel-concierge">
  `travel-concierge`: A triage agent handing off to a booking agent with a flight search tool, on the oldest supported release. It runs with no model key.
</Card>

## The prompt and the reply

The prompt is the run's input. The reply is the run's final output, streamed as it is written.

## Events it reports

| Events | From |
| - | - |
| `text` | The output text, streamed. An agent with structured output sends its final output once |
| `tool_call_start`, `tool_call_args`, `tool_call_end` | Each tool call |
| `tool_result` | Each tool's output |
| `step_start`, `step_end` | Each agent that runs, by name, so a handoff is a new step |
| `done` or `error` | The end of the run: always exactly one |

See [Streaming and events](/build/streaming).

## The caller's fields

In the run context, which the SDK hands to every tool as `ctx.context`:

```python theme={null}
from typing import Any

from agents import RunContextWrapper, function_tool


@function_tool
def search_flights(ctx: RunContextWrapper[Any], origin: str, destination: str) -> str:
    params = (ctx.context or {}).get("onecortex", {}).get("params", {})
    currency = params.get("currency", "GBP")
    ...
```

**Sessions:** Onecortex does not attach an SDK session. The same `sessionId` reaches the same running instance; keep conversation memory yourself if you need it. See [Sessions](/build/sessions).

## Known limits

* The SDK's own sessions are not connected to Onecortex sessions.

## Troubleshooting

| You see | Do this |
| - | - |
| The agent raises `OPENAI_API_KEY` is not set | Add the key as a secret on the **Config** tab and deploy. The smoke test uses a placeholder value, so an agent that catches the model's error still passes. |

More on [Troubleshooting](/production/troubleshooting) and [Errors](/production/errors).