Python SDK

Installation

pip install maev-sdk

maev.init()

The only function you need to call.

maev.init(
    api_key="vl_xxx",
    agent_name="My Agent",   # optional
    endpoint="https://maevhq.com",  # optional
)

Parameters

api_key str (required)

Your Maev API key. Must start with vl_. Get it from dashboard settings (opens in a new tab).

maev.init(api_key="vl_0b2a5f...")

agent_name str (optional, default "default")

A human-readable name for this agent. Shown in the dashboard to identify which agent a session belongs to.

maev.init(api_key="vl_xxx", agent_name="Invoice Processing Agent")

Use descriptive names. If you run the same agent in multiple environments, consider including the environment:

maev.init(api_key="vl_xxx", agent_name="Support Agent (prod)")

endpoint str (optional, default "https://maevhq.com")

Override the ingest URL. Only needed if you are self-hosting Maev.

maev.init(api_key="vl_xxx", endpoint="https://maev.your-company.com")

maev.flush()

Flushes all pending telemetry and closes the current session immediately.

maev.flush()

When you need it

In a normal long-running process — a server, a script, a container — Maev automatically sends everything when the process exits. You don't need to call flush().

In serverless functions, the process doesn't exit cleanly. The moment your handler returns, the platform freezes or kills the process. Any telemetry still buffered in memory is dropped, and the session never closes in your dashboard.

flush() forces delivery before that happens:

import maev
 
maev.init(api_key="vl_xxx", agent_name="My Lambda")
 
def handler(event, context):
    result = run_agent(event)
 
    maev.flush()  # send everything before Lambda freezes
    return result

What it does

Two things, in order:

1. Calls force_flush() on the OpenTelemetry tracer provider — drains any LLM call spans still buffered in memory
2. Sends a session.end event to Maev — closes the session and triggers failure classification

Where you need it

Where it's optional

Servers (FastAPI, Flask), scripts, notebooks, and containers all exit cleanly — flush() is harmless to call but not required.

Notes

• Safe to call multiple times — only the first call does anything
• Default timeout is 5 seconds. Override with maev.flush(timeout=10.0)
• Will warn (but not raise) if called before maev.init()

Behavior

• maev.init() is idempotent. Calling it more than once emits a warning and has no effect
• Telemetry is sent asynchronously and never blocks agent execution
• A session is automatically closed when the Python process exits (via atexit)
• In serverless functions, call maev.flush() before returning — see above
• If the process is killed without flushing, the session is timed out after 1 hour

Error handling

maev.init() raises ValueError if the API key is missing or does not start with vl_:

try:
    maev.init(api_key="invalid")
except ValueError as e:
    print(e)
# Invalid Maev API key: must start with 'vl_'

All other errors (network failures, ingest errors) are silently swallowed. Maev will never crash your agent.

Requirements

• Python 3.9 or higher
• Works in any environment: scripts, web servers, notebooks, containers