maev-sdk 0.4.6

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

Maev Python SDK

One-liner observability for AI agents.

Installation

pip install maev-sdk

Quickstart

import maev

maev.init(api_key="vl_xxx")

That's it. Add this before your agent runs. Maev automatically instruments OpenAI, Anthropic, LangChain, CrewAI, LiteLLM, Gemini, Cohere, LlamaIndex, and other popular LLM libraries, and sends all telemetry to your Maev dashboard.

Serverless functions (Lambda, Cloud Functions, Vercel, etc.)

In long-running processes (servers, scripts, notebooks), Maev automatically sends all telemetry when the process exits. No extra code needed.

In serverless functions, the process doesn't exit cleanly — it gets frozen or killed by the platform the moment your handler returns. Any telemetry still in the buffer is silently dropped, and your session never closes in the dashboard.

Call maev.flush() at the end of your handler to force delivery before the freeze:

import maev

maev.init(api_key="vl_xxx", agent_name="My Lambda")

def handler(event, context):
    # ... your agent logic ...

    maev.flush()  # send everything before Lambda freezes
    return result

flush() does two things in order:

1. Forces the OpenTelemetry exporter to drain any buffered spans (LLM call data)
2. Sends a session.end event so Maev closes and classifies the session

It is safe to call multiple times — only the first call does anything.

Environments where you must call flush():

Platform	Why
AWS Lambda	Handler returns → process frozen immediately
Google Cloud Functions	Same — process suspended after return
Vercel / Netlify Functions	Execution context torn down after response
Azure Functions	Consumption plan freezes after invocation

Environments where flush() is optional (but harmless):

• Long-running servers (FastAPI, Flask, Django)
• CLI scripts
• Jupyter notebooks
• Docker containers

How it works

• Telemetry is collected and sent asynchronously — zero impact on your agent's performance.
• Sessions are automatically tracked from the first LLM call through to process exit.
• Failures are detected and classified server-side — no configuration required.
• Every failure triggers an alert in your Maev dashboard and via email.
• Active Maev Fix prompts refresh in the background and inject automatically into supported libraries.
• The SDK prints a terminal notice when a newer maev-sdk version is available on PyPI.

Supported Libraries

Maev auto-instruments all major LLM frameworks including:

• OpenAI
• Anthropic
• LangChain
• CrewAI
• LiteLLM
• Google Gemini (google-generativeai)
• Cohere
• LlamaIndex
• Mistral
• AWS Bedrock
• And more

Requirements

• Python >= 3.9

Your API Key

Find your API key in the Maev Dashboard under Settings. Keys follow the format vl_ followed by 64 hex characters.

Self-hosting

If you are running Maev on your own infrastructure, pass the endpoint parameter:

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