OpenAI Agents SDK

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

agent.yml

apiVersion: v1
runtime: python3.12
entrypoint: agent.py:agent
dependencies: requirements.txt

requirements.txt

openai-agents>=0.21

agent.py

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.

A complete OpenAI Agents SDK example

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.

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.

The caller’s fields

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

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.

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.

Get started

Build your agent

Frameworks

Deploy

Call your agent

Observe

Production

Organizations

Resources

What is supported

A complete agent

A complete OpenAI Agents SDK example

The prompt and the reply

Events it reports

The caller’s fields

Known limits

Troubleshooting

​What is supported

​A complete agent

A complete OpenAI Agents SDK example

​The prompt and the reply

​Events it reports

​The caller’s fields

​Known limits

​Troubleshooting

What is supported

A complete agent

The prompt and the reply

Events it reports

The caller’s fields

Known limits

Troubleshooting