Skip to content
GONATURELLE
OpenAI Agents SDK logoAgent framework

GONATURELLE for OpenAI Agents SDK

Register an GONATURELLE tracing processor with the OpenAI Agents SDK so agent, generation, function, handoff and guardrail spans become assertable steps.

add_trace_processor()
tests/test_pharmacy_agents.py
from agents import Agent, Runner, add_trace_processor, function_tool
from gonaturelle import EvalSuite, TrajectoryTester
from gonaturelle.integrations.openai_agents import GonaturelleTraceProcessor

@function_tool
def check_interactions(drug_a: str, drug_b: str) -> str:
    '''Return the interaction severity for two drugs.'''
    from app.formulary import interaction
    return interaction(drug_a, drug_b)

pharmacist = Agent(name='Pharmacist', instructions='Answer medication questions using check_interactions.', tools=[check_interactions])
triage = Agent(name='Triage', instructions='Route medication questions to the Pharmacist.', handoffs=[pharmacist])

add_trace_processor(GonaturelleTraceProcessor(agent='pharmacy-triage'))

async def run_case(case):
    result = await Runner.run(triage, case.input)
    return result.final_output

def test_pharmacy_routing():
    results = EvalSuite.load('healthcare/triage-escalation').evaluate(agent=run_case, max_concurrency=10)
    t = TrajectoryTester(results)
    t.assert_handoff('Triage', 'Pharmacist', when={'tags': 'medication'})
    t.assert_called('check_interactions', when={'tags': 'medication'})

The OpenAI Agents SDK keeps agent definitions small: an Agent has instructions, tools declared with the function_tool decorator, optional handoffs to other agents and input or output guardrails, and Runner.run drives the loop. Built-in tracing records each run as a trace made of spans, with span data types for agents, model generations, function calls, handoffs and guardrails.

GONATURELLE plugs into that tracing system rather than wrapping your code. You register GonaturelleTraceProcessor with add_trace_processor, and the SDK delivers every span to it as runs complete. The processor maps function spans to tool steps with their input and output, handoff spans to transitions between agents, and guardrail spans to checks that either passed or tripped. Your existing processors, including export to the OpenAI traces dashboard, keep working because add_trace_processor adds to the list instead of replacing it.

In regulated deployments the guardrails and handoffs are the interesting parts. A triage agent that hands a medication question to a general assistant instead of the pharmacist agent, or an output guardrail that stops tripping after a prompt edit, will not show up in a final-answer score. Both are explicit steps in the trajectory, and both can be asserted on every case of every pull request.

What you can test with OpenAI Agents SDK.

Handoff routing assertions

Handoff spans record source and destination agents. assert_handoff checks that cases tagged for a specialist always reach that specialist, and never a general agent.

Guardrail coverage

Input and output guardrail spans are recorded with their triggered flag. Suites can require that a PHI-disclosure guardrail trips on every adversarial case and on no benign ones.

Function tool schemas

Tools defined with function_tool carry strict JSON schemas generated from type hints. GONATURELLE validates every call against them and adds your suite's parameter bounds.

Usage and cost tracking

Generation spans carry token usage, which feeds per-case cost and the cost drift threshold in the CI gate.

Set up in 5 steps.

Most teams have a first suite running against OpenAI Agents SDK in under an hour, then add the CI gate.

Get an API key
  1. 01

    Install gonaturelle alongside openai-agents in your project environment.

  2. 02

    Export GONATURELLE_API_KEY and OPENAI_API_KEY (or configure the SDK's model provider for another backend).

  3. 03

    Call add_trace_processor(GonaturelleTraceProcessor(agent='...')) once at test startup, before any run.

  4. 04

    Give the suite a function that awaits Runner.run(triage_agent, case.input) and returns result.final_output.

  5. 05

    Assert on handoffs, guardrails and tool order, then wire the fast path into CI.

OpenAI Agents SDK integration FAQ

Does this disable OpenAI's own tracing?

No. add_trace_processor appends GONATURELLE to the SDK's processors. If you want GONATURELLE to be the only destination, the SDK's set_trace_processors replaces the list, but most teams keep both.

Does it work with non-OpenAI models through the SDK?

Yes. The SDK can call other providers through its model abstractions, and spans are produced the same way, so the trajectory and assertions are unchanged. Generation spans record whichever model was used.

What about sensitive data in traces?

The SDK lets you exclude model and tool inputs and outputs from traces. GONATURELLE needs tool arguments for trajectory assertions, so it applies its own client-side redaction rules to those fields before upload instead.

Stop testing regulated agents on generic prompts.

Run your agent against 100 industry-standard clinical or financial edge cases in 5 minutes. 14-day free production trial, no card.