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
Metadata
Release files for marlo-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| marlo_sdk-0.1.0.tar.gz | 158.8 kB | With provenance | Details for marlo_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| marlo_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for marlo_sdk-0.1.0-py3-none-any.whl |
Total release size: 358.0 kB
Release files / marlo_sdk-0.1.0.tar.gz
| Download URL | marlo_sdk-0.1.0.tar.gz |
|---|---|
| Size | 158.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
24ce4b340c4a5cc35e86c0f46c037eb34560de860e033f34245dd0a60625e544
|
|
BLAKE2b-256 checksum How to use checksums |
bab1a841385ebd79cdc194346c006b9d9482017ee769abebc05eb44ae5836c7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 7, 2026.
Transparency logRelease files / marlo_sdk-0.1.0-py3-none-any.whl
| Download URL | marlo_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 199.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b17cbf9e011cd882629fe766a3c6a915c60a119e16887abc15b67881cd99bf2
|
|
BLAKE2b-256 checksum How to use checksums |
1c4f00318439f83671944f80e2864c0da7190b703ba0a717492ef31a2a31edc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 7, 2026.
Transparency logSecurity for marlo-sdk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for marlo_sdk-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.