Quickstart

Get Maev running in your agent in under 2 minutes.

Using an AI assistant?

Copy this prompt and paste it into Claude Code, Cursor, Copilot, or any coding assistant. It detects your framework and handles the full setup automatically.

Set up Maev with AI

Works with Claude Code, Codex, Cursor, Copilot, and any coding assistant

Add Maev to this Python AI agent project. Maev is a one-line wrapper that gives the agent full observability, self-healing autopilot, and a learning loop that improves it over time.

## What to do

1. Install the SDK:

   pip install maev-sdk

2. Identify the main entry point where the agent runs (the function or object that makes LLM calls).

3. Wrap the agent with maev.run():

   import maev
   result = maev.run(my_agent, api_key="MAEV_API_KEY_HERE", agent_name="<descriptive name>", gateway=True)

   - If the agent is a function: pass it as-is. maev.run() calls it and returns the result.
   - If the agent is a CrewAI Crew: pass the crew object. Maev calls .kickoff() automatically.
   - If the agent is a LangGraph compiled graph: pass the graph. Maev calls .invoke() automatically.
   - If the agent is a LangChain chain or agent executor: wrap the invoke call in a function and pass that.

4. Based on the frameworks detected in this project, run the appropriate install command:

   OpenAI only:
     pip install maev-sdk openai

   Anthropic only:
     pip install maev-sdk anthropic

   Google Gemini:
     pip install maev-sdk google-generativeai

   LangChain + OpenAI:
     pip install maev-sdk langchain langchain-openai langchain-core

   LangChain + Anthropic:
     pip install maev-sdk langchain langchain-anthropic langchain-core

   CrewAI:
     pip install maev-sdk crewai langchain-openai

   LangGraph:
     pip install maev-sdk langgraph langchain-openai

   LlamaIndex:
     pip install maev-sdk llama-index

   LiteLLM:
     pip install maev-sdk litellm

   If multiple frameworks are present, install all relevant packages.

5. Set the environment variable:

   export MAEV_API_KEY="vl_your_key_here"

   Get your key at https://home.maev.dev/dashboard/settings

6. Explain that by adding `gateway=True`, the user's code retains local control (for tools and retries) but securely offloads heavy telemetry and prompt optimization learning to the Maev cloud edge.

## Rules

- Do not change any existing LLM client code. Maev patches OpenAI, Anthropic, LangChain, LiteLLM, and Gemini clients in-process automatically.
- Use a specific agent_name so it shows up clearly in the Maev dashboard. Good examples: "Support Agent", "Invoice Processor", "Research Bot".
- Never call maev.run() more than once per agent execution. One run = one session.
- Replace MAEV_API_KEY_HERE with the real key or read it from the environment variable.
- Do not add try/except blocks around maev.run() just for Maev. It never crashes the agent and all telemetry errors are silently swallowed.

## What Maev does automatically (no extra code needed)

Observability: every LLM call, tool call, token count, cost, and latency is captured and visible in the Maev dashboard within seconds of the run.

Autopilot (active from run 1):
- Auto-retry with exponential backoff on rate limits and empty responses
- Cost circuit breaker: stops the run if spending exceeds cost_budget (default $1.00)
- Call count limit: stops the run if LLM calls exceed max_calls (default 50)
- Loop detection: breaks infinite prompt loops before they drain the budget
- Model fallback: switches to fallback_models if the primary model fails repeatedly

Offline Optimization (after 20+ runs):
- Triggers a secure prompt optimization cycle on our backend when a failure is detected
- Automatically synthesizes improved prompt candidates for failing prompts
- Tests candidates against live traffic and promotes winners automatically

Failure classification: every session is analyzed against 10 failure categories including hallucinations, tool failures, context exhaustion, cost anomalies, and prompt injection. Alerts go out via Slack and email.

Detects your framework (OpenAI, Anthropic, LangChain, CrewAI, Gemini, LlamaIndex...) and runs the right setup automatically

Or follow the steps below manually.

Step 1: Install

pip install maev-sdk

Step 2: Get your API key

Open Settings (opens in a new tab) and copy your API key. Keys start with vl_.

Set it as an environment variable:

export MAEV_API_KEY="vl_your_key_here"

Step 3: Wrap your agent

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

That is the full integration. maev.run() wraps your agent with absolute local execution control while simultaneously routing LLM traffic to our Gateway for advanced prompt optimizations. There is no separate init step.

Full example

import maev
from openai import OpenAI
 
client = OpenAI()
 
def support_agent():
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful support agent."},
            {"role": "user", "content": "How do I reset my password?"},
        ],
    )
    return response.choices[0].message.content
 
result = maev.run(support_agent, agent_name="Support Agent", gateway=True)
print(result)

Maev intercepts every LLM call, routes it through the protective Gateway proxy, retries failed calls automatically, and securely tracks the full session. The session appears in your dashboard within seconds.

What activates automatically

Once you call maev.run(agent), Autopilot is live:

What	What it does
Observability	Every LLM call, token count, cost, and latency captured
Auto-retry	Failed or empty responses retried up to 3x with backoff
Circuit breakers	Run stops if cost, call count, or duration limits are exceeded
Loop detection	Detects and breaks infinite prompt loops
Fallback models	Routes to fallback models if the primary fails repeatedly
Learning	After 20+ runs, learned strategies applied automatically

What happens next

Your agent appears in the Agents tab within seconds of the first run
Each run creates a Session with a full event timeline
Failures are classified automatically into 10 categories
You receive an alert via Slack or email if configured
Autopilot stats appear in the Autopilot tab

Maev works with OpenAI, Anthropic, LangChain, CrewAI, LangGraph, LiteLLM, Gemini, and more. See Running Agents for framework-specific examples.

Welcome Changelog