avenza 1.0.0

Instrument AI agents in one line. Cost, value, and SLO tracking, automatically.

Avenza Python SDK

Instrument AI agents in one line. Cost, value, and SLO tracking — automatically.

Install

pip install avenza

Quickstart (3 lines)

from avenza import Agent

agent = Agent(name='Invoice Bot', risk_tier='T2')

with agent.run() as run:
    result = process_invoice(data)
    run.success = result.is_valid
    run.log_value('task_completed', quantity=1, unit_value_usd=1.50)

That's it. If you're using the official Anthropic, OpenAI, or Gemini client, token usage is captured automatically with zero additional code.

Setup wizard

avenza init

Interactive wizard that verifies your API key and writes a working starter script — not a docs page to interpret.

Diagnose

avenza doctor

Self-diagnose connection issues, missing instrumentation, and proxy configuration.

Auto-instrumentation

The SDK patches the official provider clients the moment it's imported:

import anthropic
from avenza import Agent

agent = Agent(name='Support Bot')
client = anthropic.Anthropic()

with agent.run() as run:
    # Token usage captured automatically from this call
    response = client.messages.create(model='claude-sonnet-4-6', ...)
    run.success = True

Works across threads and async/await via Python's contextvars.

Manual token fallback

with agent.run() as run:
    response = my_llm_client.call(...)
    run.set_tokens(response.input_tokens, response.output_tokens)
    run.success = True

LangChain

from avenza.integrations.langchain import AvenzaCallbackHandler
from langchain_anthropic import ChatAnthropic

handler = AvenzaCallbackHandler(agent_name='Support Classifier', risk_tier='T1')
llm = ChatAnthropic(model='claude-sonnet-4-6', callbacks=[handler])
response = llm.invoke('Classify this ticket: ...')

Testing

from avenza.testing import MockAgent

def test_my_agent():
    agent = MockAgent(name='Invoice Bot')
    with agent.run() as run:
        run.success = True
        run.log_value('task_completed', quantity=1, unit_value_usd=1.50)

    assert agent.runs[-1].success is True
    assert agent.runs[-1].value_events[0]['quantity'] == 1

Configuration

Parameter	Default	Description
name	required	Agent display name
risk_tier	'T1'	T1 (autonomous), T2 (approve-first), T3 (assist-only)
api_key	AVENZA_API_KEY env	Bearer token from Settings → API Tokens
model	None	LLM model for cost lookup (auto-detected when using auto-instrumentation)
auto_instrument	True	Patch provider clients automatically
offline_buffer	True	Queue failed sends to disk and retry
base_url	https://app.avenza.app	Override for self-hosted

Never blocks. Never raises.

Every network call is fire-and-forget on a background thread. Avenza being down, slow, or returning errors will never crash your agent or add latency to your agent's actual work. Failed sends are buffered to .avenza_buffer.jsonl and retried on next startup.