marlo-sdk 0.1.0

Open-source agent learning platform

Marlo

Open-source agent learning platform. Capture agent behavior, evaluate outcomes, and turn failures into learnings that make your agents better over time.

The Problem

AI agents fail silently in production. The same mistakes repeat across runs because there is no feedback loop -- failures are logged and forgotten. Marlo closes this gap.

How It Works

1. Capture    Record every LLM call, tool call, and outcome
2. Evaluate   Score task results automatically using Gemini
3. Learn      Generate structured learnings from failures
4. Apply      Inject learnings into future agent runs

Your agent gets smarter with every failure instead of repeating the same mistakes.

Quick Start

Three commands to get running:

pip install marlo-sdk
export GEMINI_API_KEY=your-key    # https://aistudio.google.com/apikey
marlo run                          # starts server + dashboard + postgres

Dashboard at localhost:5173. API at localhost:8000. Requires Docker.

Stop with marlo stop.

Python SDK

pip install marlo-sdk

import marlo

marlo.init()

# Register your agent
marlo.agent(
    name="support-bot",
    system_prompt="You are a customer support agent.",
    tools=[{"name": "lookup_order", "description": "Find order by ID"}],
)

# Track a task
with marlo.task(thread_id="thread-123", agent="support-bot") as t:
    t.input("Where is my order?")

    # Retrieve learnings from past failures
    learnings = t.get_learnings()
    # Inject into your prompt: system_prompt += learnings["learnings_text"]

    t.tool("lookup_order", {"id": "ORD-456"}, {"status": "shipped"})
    t.output("Your order has been shipped and arrives tomorrow.")

marlo.shutdown()

Multi-Agent

with marlo.task(thread_id="thread-1", agent="orchestrator") as parent:
    parent.input("Research AI trends and write a report")

    with parent.child(agent="researcher") as child:
        child.input("Search for recent AI developments")
        child.output("Found 3 relevant sources...")

    parent.output("Report complete.")

TypeScript SDK

npm install @marshmallo/marlo

import { init, agent, task, shutdown } from "@marshmallo/marlo";

await init();

agent("support-bot", "You are a customer support agent.", [
  { name: "lookup_order", description: "Find order by ID" },
]);

const t = task("thread-123", "support-bot").start();
t.input("Where is my order?");

const learnings = await t.getLearnings();
// Inject learnings into your prompt if available

t.tool("lookup_order", { id: "ORD-456" }, { status: "shipped" });
t.output("Your order has been shipped and arrives tomorrow.");
t.end();

await shutdown();

Dashboard

The dashboard gives you visibility into your agents:

• Traces -- browse sessions, tasks, LLM calls, and tool calls
• Learnings -- review, approve, or reject generated learnings
• Agents -- see registered agents, their tools, and model configs
• Rewards -- track evaluation scores over time
• Copilot -- ask questions about your agent data in natural language

No login required. Runs locally at localhost:5173.

Architecture

SDK (Python/TS)  --->  FastAPI Server  --->  PostgreSQL
                            |
                        Dashboard

The SDK captures events and sends them to the server over HTTP. The server stores trajectories in PostgreSQL, runs evaluation with Gemini, and generates learnings. The dashboard reads from the same server.

marlo run starts all three services via Docker Compose.

Configuration

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	--	Google Gemini key for evaluation
MARLO_ENDPOINT	No	http://localhost:8000	Server URL

Repository Structure

marlo/              Python SDK + FastAPI server
sdks/typescript/    TypeScript SDK (@marshmallo/marlo on npm)
dashboard/          React dashboard (Vite + TanStack Router)
docker/             Docker Compose config for local stack
tests/              Python test suite

Releases

Releases are tag-driven. Bump the version, merge to main, then tag:

# Python SDK
git tag v0.2.0 && git push origin v0.2.0

# TypeScript SDK
git tag ts-v0.2.0 && git push origin ts-v0.2.0

Tags trigger CI to publish to PyPI/npm and create a GitHub Release automatically.

Package	Registry	Tag format
marlo-sdk	PyPI	v*.*.*
@marshmallo/marlo	npm	ts-v*.*.*

Contributing

See CONTRIBUTING.md.

License

MIT