Skip to main content
Use NexusOpenAITracingProcessor to capture every span emitted by the OpenAI Agents SDK and send it to Nexus automatically.

​
Install

pip install nexus-library[openai]

​
Set up the processor

import asyncio
import os
from agents import Agent, Runner, set_trace_processors
from nexus_library.nexus_core import NexusClient
from nexus_library.openai import NexusOpenAITracingProcessor

nexus_client = NexusClient(api_key=os.environ["NEXUS_API_KEY"])
dev_mode = os.getenv("NEXUS_DEV_MODE", "false").lower() == "true"
tracing_processor = NexusOpenAITracingProcessor(nexus_client, dev_mode=dev_mode)

set_trace_processors([tracing_processor])
Register the processor once at startup before any agents run. All subsequent Runner.run calls in the process are captured automatically.

​
Environment variables

VariableValuesBehavior
NEXUS_API_KEYyour API keyAuthenticates the Nexus client
NEXUS_DEV_MODEtrueDisables external trigger POST — use locally and in CI
NEXUS_DEV_MODEfalse (default)Fires the trigger endpoint — use in production

​
Full example

import asyncio
import os
from agents import Agent, Runner, set_trace_processors, function_tool
from dotenv import load_dotenv
from nexus_library.nexus_core import NexusClient
from nexus_library.openai import NexusOpenAITracingProcessor

load_dotenv()

nexus_client = NexusClient(api_key=os.environ["NEXUS_API_KEY"])
dev_mode = os.getenv("NEXUS_DEV_MODE", "false").lower() == "true"
tracing_processor = NexusOpenAITracingProcessor(nexus_client, dev_mode=dev_mode)

set_trace_processors([tracing_processor])


@function_tool
def hello_world():
    """Prints 'Hello, world!' to the console."""
    print("Hello, world!")


async def main():
    agent = Agent(
        name="my-agent",
        tools=[hello_world],
        instructions="You are a helpful assistant.",
    )
    result = await Runner.run(agent, "Say hello.")
    print(result.final_output)


asyncio.run(main())

​
Dev vs production

  • Development — set NEXUS_DEV_MODE=true in your .env file. The processor records traces locally without firing the external trigger endpoint.
  • Production — set NEXUS_DEV_MODE=false (or leave it unset). The processor fires POST {trigger_url}/catch_route_manual with user_id and trace_id after each root span completes.

​
Best practices

  • Store NEXUS_API_KEY in environment variables — never hardcode it.
  • Reuse one NexusClient for the lifetime of the process.
  • Call set_trace_processors once at startup, before any Runner.run calls.
Get your nexus_api_key from the Nexus platform: Nexus platform.