OpenAI Agents SDK integration

Converra uses your OpenAI Agents SDK conversations to diagnose behavior failures and test bounded fixes. You approve what goes live, then Converra reports a production verdict: verified, not fixed, or confounded.

Install

pip install converra openai-agents

Set CONVERRA_API_KEY, OPENAI_API_KEY, and OPENAI_MODEL in your server environment. Use a Python version supported by the OpenAI Agents SDK.

Send a text interaction

This example keeps the Agents SDK's model and runner unchanged. It sends the completed user and assistant exchange explicitly through Converra's Python SDK.

import asyncio
import os

from agents import Agent, Runner
from converra import Converra


async def main():
    converra = Converra(api_key=os.environ['CONVERRA_API_KEY'])
    agent = Agent(
        name='Refund support',
        instructions='Ask for an order number before discussing refund eligibility.',
        model=os.environ['OPENAI_MODEL'],
    )
    user_text = 'Can I get a refund?'
    try:
        result = await Runner.run(agent, user_text)
        if not isinstance(result.final_output, str) or not result.final_output:
            raise ValueError('This example requires a nonempty text output')
        run = await asyncio.to_thread(
            converra.send,
            agent=agent.name,
            messages=[
                {'role': 'user', 'content': user_text},
                {'role': 'assistant', 'content': result.final_output},
            ],
            metadata={'source': 'openai-agents'},
        )
        print(run.conversation_id)
    finally:
        await asyncio.to_thread(converra.shutdown)


if __name__ == '__main__':
    asyncio.run(main())

This is a text-conversation integration, not an OpenAI trace exporter. It does not capture intermediate handoffs, tool calls, or structured outputs. For those workflows, preserve the actual steps with enriched SDK messages and trace lineage rather than treating final_output as a full execution trace. Do not send the same interaction through a wrapper as well.

For multi-turn applications, keep the runner's history separately and append each new exchange to the Converra conversation_id; the Python integration explains that lifecycle. Configure the same agent instructions in Converra before starting an optimization.

Test a fix and check the verdict

Connect Converra MCP to your coding agent. Use get_run_step_diagnosis to inspect the failure before changing instructions. Converra can generate a prompt fix, run a head-to-head simulation against the current version, and check regression scenarios. Apply the approved instructions to the Agent in your application.

Keep capturing conversations after the change, then inspect get_deployment_impact and get_verification_evidence. See how verdicts are decided, including evidence thresholds and confounding limits.

References

Reviewed 2026-10-15: OpenAI Agents SDK quickstart for Agent, Runner.run, and final_output; Converra Python SDK version 0.5.1 for send and the returned conversation ID.