feat(extensions): add Agentspan execution backend

[manan164]

Summary

Adds AgentspanRunner — a drop-in replacement for Runner that executes agents on Agentspan instead of directly against OpenAI.

Agentspan adds durability, observability, human-in-the-loop (HITL), and horizontal scaling to any agent built with the OpenAI Agents SDK, without changing how agents are defined or how tools are written.

Migration

Change one import line:

# Before — runs directly against OpenAI
from agents import Runner

# After — runs on Agentspan (durable, observable, scalable, HITL)
from agents.extensions.agentspan import AgentspanRunner as Runner

Everything else stays identical — Agent, @function_tool, result.final_output — no other code changes needed.

Example

from agents import Agent, function_tool
from agents.extensions.agentspan import AgentspanRunner

@function_tool
def get_weather(city: str) -> str:
    """Return current weather for a city."""
    return f"72°F and sunny in {city}"

agent = Agent(
    name="weather_assistant",
    model="gpt-4o",
    instructions="You are a helpful assistant.",
    tools=[get_weather],
)

result = AgentspanRunner.run_sync(agent, "What's the weather in NYC?")
print(result.final_output)

What Agentspan adds

Feature	Built-in Runner	AgentspanRunner
Execute agents	✅	✅
Durable (survives crashes)	❌	✅
Full execution history	❌	✅
Human-in-the-loop pauses	❌	✅
Distributed tool workers	❌	✅
Agentspan UI observability	❌	✅

Files changed

File	Change
src/agents/extensions/agentspan.py	New — AgentspanRunner + AgentspanRunResult
src/agents/extensions/__init__.py	Lazy export of AgentspanRunner
pyproject.toml	agentspan optional dependency

Installation

pip install openai-agents[agentspan]

Requires an Agentspan server (AGENTSPAN_SERVER_URL=http://localhost:6767/api by default). See agentspan.ai for setup.

[seratch]

While we don't have this module as part of this core SDK, please feel free to share it as your own package.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1fb172f32f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Pass a real ToolContext to converted function tools

_convert_function_tool invokes SDK tools as ft.on_invoke_tool(None, ...), but FunctionTool handlers dereference context fields (for example ctx.tool_name) during normal invocation. In practice this causes every converted @function_tool call to fail and return tool-error text instead of running the tool logic, so any agent using OpenAI Agents function tools will misbehave under AgentspanRunner.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Make run_streamed match Runner's synchronous API

This method is declared async, but the built-in Runner.run_streamed(...) API is synchronous and immediately returns a streaming result object. Using AgentspanRunner as Runner therefore changes call semantics: existing code that calls Runner.run_streamed(...) without await receives a coroutine instead of a stream, breaking drop-in compatibility for streaming flows.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve callable instructions instead of clearing them

Dynamic instructions are called as instructions() with no arguments and any exception is swallowed by setting instructions = "". In this SDK, callable instructions are expected to accept (context, agent), so this path drops prompts for valid dynamic-instruction agents and silently changes model behavior instead of evaluating the instructions function correctly.

Useful? React with 👍 / 👎.