Python integration

Use Converra to diagnose failures in a Python agent, generate and test behavior fixes, and verify the approved change on production conversations. Each fix gets a production verdict: verified, not fixed, or confounded.

Install

pip install 'converra[openai]'

Set CONVERRA_API_KEY, OPENAI_API_KEY, and OPENAI_MODEL in your server environment. Use the model your agent already runs. The Converra SDK requires Python 3.9 or later.

Send a completed conversation

Explicit sending is useful when you already own the transcript or need to finish delivery before a short script exits. This example awaits the model response and then sends the user and assistant messages synchronously.

import os

from converra import Converra
from openai import OpenAI

converra = Converra(api_key=os.environ['CONVERRA_API_KEY'])
client = OpenAI()
instructions = 'Ask for an order number before discussing refund eligibility.'
user_text = 'Can I get a refund?'

try:
    response = client.chat.completions.create(
        model=os.environ['OPENAI_MODEL'],
        messages=[
            {'role': 'system', 'content': instructions},
            {'role': 'user', 'content': user_text},
        ],
    )
    answer = response.choices[0].message.content
    if not answer:
        raise ValueError('Expected a text response')
    run = converra.send(
        agent='Refund support',
        messages=[
            {'role': 'user', 'content': user_text},
            {'role': 'assistant', 'content': answer},
        ],
        session_id='support-session-123',
        metadata={'source': 'python-app'},
    )
    print(run.conversation_id)
finally:
    converra.shutdown()

Use your actual application messages in production. Keep the same agent name across turns, and register the system instructions on that agent in Converra before optimizing. Sending a transcript does not configure the system prompt.

For a longer conversation, send the first exchange with status='active', retain the returned conversation_id, then pass that ID when appending only the new messages. Finish with status='completed'. Keep system instructions separate from user and assistant turns. See the SDK reference for client wrapping, tool-call evidence, and trace lineage.

Fix and verify

Connect your coding agent through MCP. Inspect the failing step, generate a bounded prompt or configuration fix, compare it against the current agent in simulation, and check for regressions. You approve the change that your application applies.

Continue sending conversations after the change. Use get_deployment_impact and get_verification_evidence to inspect what happened to the targeted failure. See the verdict thresholds and limits; incomplete evidence cannot establish that a fix worked.

Source and compatibility

Example checked on 2026-10-15 against the published converra 0.5.1 SDK: Converra.send, session_id, metadata, SendResult.conversation_id, and shutdown. See PyPI and the Python SDK.