maev-sdk 0.5.1

Maev AI Agent Observability SDK — one-liner instrumentation for AI agents

Maev Python SDK

One line. Full control over your agent in production.

Installation

pip install maev-sdk

Quickstart

import maev

result = maev.run(my_agent, gateway=True)

maev.run() wraps your agent with full observability, self-healing circuit breakers, and self-improving prompt optimization — in one call. The gateway=True flag transparently routes your LLM traffic through Maev's cloud edge for backend learning.

What activates automatically

Feature	What it does
Observability	Every LLM call, token count, cost, and latency captured
Auto-retry	Failed or empty responses retried up to 3× with exponential backoff
Cost circuit breaker	Run stops if cost exceeds your cost_budget
Call count limit	Run stops if max_calls is exceeded
Duration limit	Run stops if max_duration_s is exceeded
Loop detection	Breaks infinite prompt loops before they drain the budget
Fallback models	Switches to backup models if the primary fails repeatedly
Backend optimization	After 20+ runs, generates and tests shadow prompt candidates automatically

Parameters

maev.run(
    agent,                          # required: callable or agent object
    gateway=True,                   # enable Gateway for self-reflection and optimization
    api_key="vl_xxx",               # or set MAEV_API_KEY env var
    agent_name="My Agent",          # or set MAEV_AGENT_NAME env var
    cost_budget=1.0,                # max $ per run (default $1.00)
    max_calls=50,                   # max LLM calls per run (default 50)
    max_duration_s=300.0,           # max seconds per run (default 300)
    fallback_models=["gpt-4o-mini"],# fallback model list
)

Supported frameworks

Maev actively intercepts LLM calls for:

• OpenAI — including AzureOpenAI, AsyncOpenAI, AsyncAzureOpenAI
• Anthropic — including AsyncAnthropic
• LangChain — all BaseChatModel subclasses
• CrewAI — detected via .kickoff()
• LiteLLM — via callback hooks; redirected to gateway when gateway=True

Telemetry is also captured for Gemini, Cohere, AWS Bedrock, Mistral, Groq, LlamaIndex, and more.

Works with any framework

Because gateway=True makes Maev an OpenAI-compatible proxy, any library that accepts a custom base_url works automatically:

# LangChain
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    base_url="https://gateway.maev.dev/v1",
    default_headers={"x-api-key": "vl_xxx", "x-agent-name": "My Agent"},
)

# Direct OpenAI client
from openai import OpenAI
client = OpenAI(
    base_url="https://gateway.maev.dev/v1",
    default_headers={"x-api-key": "vl_xxx", "x-agent-name": "My Agent"},
)

Serverless environments

In serverless environments (AWS Lambda, Cloud Functions, Vercel), call maev.flush() before the handler returns:

import maev

def handler(event, context):
    result = maev.run(my_agent, event, gateway=True)
    maev.flush()
    return result

Or use the one-liner form — Maev handles flushing automatically:

def handler(event, context):
    return maev.run(my_agent, event, gateway=True)

Error handling

try:
    maev.run(agent, gateway=True, cost_budget=0.10)
except maev.CircuitBrokenError as e:
    print(e)
# Run stopped: cost limit exceeded ($0.10)

Requirements

• Python >= 3.9
• Works in scripts, servers, notebooks, containers, and serverless

API Key

Get your key at home.maev.dev/dashboard/settings.
Keys start with vl_. Set as environment variable:

export MAEV_API_KEY="vl_your_key_here"