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

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"