Configuration

All configuration is passed directly to maev.run(). There is no separate init step.

API key

Your API key is in the Maev dashboard under Settings. Keys always start with vl_.

The preferred way is via environment variable:

export MAEV_API_KEY=vl_your_key_here

import maev
 
maev.run(my_agent, gateway=True)  # reads MAEV_API_KEY automatically

Or pass it directly:

maev.run(my_agent, api_key="vl_your_key_here", gateway=True)

Agent name

You can also set the agent name via environment variable instead of passing it every call:

export MAEV_AGENT_NAME="Customer Support Bot"

maev.run(my_agent, gateway=True)  # agent_name auto-read from MAEV_AGENT_NAME

Priority: explicit agent_name= argument > MAEV_AGENT_NAME env var > auto-detected from function/class name.

Agent naming

Use agent_name to give your agent a human-readable name in the dashboard:

maev.run(my_agent, agent_name="Invoice Processing Agent", gateway=True)

Naming conventions that work well:

• Use the function or role of the agent: "Email Drafter", "Lead Scorer", "Code Reviewer"
• Include the environment if you use the same key across staging and production: "Support Agent (prod)"
• Keep names consistent across deployments so history accumulates on one agent in the dashboard

If agent_name is omitted, Maev auto-detects the name from the function or class name.

Budget and safety limits

maev.run(
    my_agent,
    gateway=True,
    cost_budget=0.50,       # stop the run if it costs more than $0.50
    max_calls=30,           # stop after 30 LLM calls
    max_duration_s=120.0,   # stop after 2 minutes
)

If any limit is exceeded, Maev stops the run and raises maev.CircuitBrokenError.

Model fallbacks

Provide an ordered list of fallback models to use if the primary model fails repeatedly:

maev.run(
    my_agent,
    gateway=True,
    fallback_models=["gpt-4o-mini", "gpt-3.5-turbo"]
)

Using a .env file

# .env
MAEV_API_KEY=vl_your_key_here
MAEV_AGENT_NAME=My Agent

from dotenv import load_dotenv
import os
import maev
 
load_dotenv()
 
maev.run(
    my_agent,
    gateway=True,
    agent_name=os.environ.get("MAEV_AGENT_NAME", "default"),
)

Docker and containers

Pass the API key as an environment variable in your container config:

# docker-compose.yml
services:
  agent:
    environment:
      - MAEV_API_KEY=vl_your_key_here

# Dockerfile
ENV MAEV_API_KEY=""

Serverless functions

In serverless environments, the process freezes immediately after your handler returns. Wrap the agent call with maev.run() and it handles telemetry flushing automatically before the process is frozen:

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

If you need more control over flush timing, call maev.flush() explicitly before the handler returns:

import maev
 
def handler(event, context):
    result = maev.run(run_agent, event, gateway=True)
    maev.flush(timeout=5.0)
    return result

CI/CD

In GitHub Actions:

- name: Run agent
  env:
    MAEV_API_KEY: ${{ secrets.MAEV_API_KEY }}
  run: python agent.py

Self-hosting

If you run your own Maev instance, override the ingest endpoint:

maev.run(my_agent, endpoint="https://maev.your-company.internal", gateway=True)