Skip to Content
SdkPythonPython SDK

Python SDK

The Marlo Python SDK captures your agent’s behavior and sends it to Marlo for evaluation and learning. In just a few lines of code, you can start tracking tasks, recording interactions, and applying learnings.

Installation

pip install marlo-sdk

Quick Start

Here’s the fastest way to get Marlo working with your agent:

import os
import marlo
from openai import OpenAI
 
# 1. Initialize Marlo (once at startup)
marlo.init(api_key=os.getenv("MARLO_API_KEY"))
marlo.instrument_openai()  # Auto-capture all OpenAI calls
 
# 2. Register your agent
marlo.agent(
    name="my-agent",
    system_prompt="You are a helpful assistant.",
    tools=[],
    mcp=[],
)
 
# 3. Wrap your agent logic in a task
client = OpenAI()
 
with marlo.task(thread_id="user-123", agent="my-agent") as task:
    task.input("What is 2 + 2?")
    
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "What is 2 + 2?"}]
    )
    
    answer = response.choices[0].message.content
    task.output(answer)
 
# 4. Shutdown before exit
marlo.shutdown()

That’s it! Your agent’s behavior is now being captured, evaluated, and turned into learnings.

Configuration

Initialize the SDK once when your application starts. You’ll find your API key in Settings → Project at marshmallo.ai .

import os
import marlo
 
marlo.init(api_key=os.getenv("MARLO_API_KEY"))

For async applications (FastAPI, LangGraph, etc.), use the async initializer:

await marlo.init_async(api_key=os.getenv("MARLO_API_KEY"))

Or initialize in a background thread to avoid blocking:

marlo.init_in_thread(api_key=os.getenv("MARLO_API_KEY"))

Core Concepts

Tasks

A task represents a single agent execution—from receiving user input to producing output. Wrap your agent logic with marlo.task():

with marlo.task(
    thread_id="user-123-session-456",
    agent="my-agent",
    thread_name="Support Chat",
) as task:
    task.input("User's question here")
    
    # Your agent logic...
    
    task.output("Agent's response here")

Parameters:

  • thread_id (str): Stable identifier for the conversation. Tasks with the same thread_id are grouped together.
  • agent (str): Name of the registered agent handling this task.
  • thread_name (str, optional): Human-readable label shown in the dashboard.

Agents

Register your agent’s configuration so Marlo knows what it’s capable of:

marlo.agent(
    name="support-agent",
    system_prompt="You are a helpful customer support agent.",
    tools=[
        {
            "name": "lookup_order",
            "description": "Find order details by order ID",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        }
    ],
    mcp=[],
    model_config={"model": "gpt-4"},
)

Shutdown

Always call marlo.shutdown() before your application exits to ensure all events are sent:

marlo.shutdown()

For web frameworks:

# FastAPI
@app.on_event("shutdown")
def shutdown():
    marlo.shutdown()
 
# Flask
import atexit
atexit.register(marlo.shutdown)

What’s Next?

Last updated on
API ReferenceLLM Tracking