Motif

An observability and prompt-engineering toolkit for multi-agent systems built on LangGraph.

Building agentic workflows is slow because small prompt changes have unpredictable, system-wide effects. Developers iterate in two loops: an inner loop refining one agent at a time, and an outer loop running the full workflow to see how agents interact. Motif gives both loops a dedicated surface.

• Graph supports the outer loop: visualize your agent topology, replay execution traces step by step, compare runs, and edit any node's prompt right where it runs.
• Playground supports the inner loop: browse your prompt library, run an agent dozens of times, and use the output map to see and fix how its behavior scatters.

Setup Guide

Prerequisites

• Python 3.11 or later
• uv (recommended) or pip as your package manager
• Node.js v18 or later and npm (for building the frontend)
• A LangGraph workflow you want to instrument (langgraph installed in your project)
• An OpenAI API key if you plan to use the Playground or the AI description features

1. Clone the repository

git clone https://github.com/fig-x/motif.git
cd motif

2. Install dependencies

We recommend using uv for fast, reliable dependency management.

uv sync --extra server

3. Configure environment

Export your OpenAI API key in the shell where you'll run motif serve:

export OPENAI_API_KEY=sk-...

Optional: Instead of exporting, you can create a .env file in the directory where you run motif serve with OPENAI_API_KEY=sk-... — the server will load it automatically on startup.

4. Start the server

uv run motif serve

On the first run, this automatically builds the frontend (npm install + npm run build inside playground-ui/). Later runs rebuild only when the frontend sources are newer than the built bundle.

Open http://localhost:8000 in your browser. The Graph page will be empty until you register a workflow.

Tip: Pass --skip-build to skip the automatic build entirely.

Optional: try the bundled example

sample_mas/ is a small data-analysis multi-agent system already instrumented with Motif. With the server running:

uv sync --extra dev            # adds langgraph, langchain-openai, pandas, seaborn
cd sample_mas
uv run python seed_prompts.py  # one-time: registers the sample's prompts
uv run python main.py --sample --query "Which region has the highest revenue?"

Then refresh the Graph page — the data-analysis-mas workflow and its run appear.

5. Install the Motif SDK in your app

The steps above install Motif inside this repository so you can run the server. To instrument your own LangGraph application, you also need the motif Python package available in your app's environment, so import motif resolves.

From inside your application's project (not this repo), run:

pip install git+https://github.com/fig-x/motif.git

Why a separate install? The cloned repo runs the Motif server (UI + API at http://localhost:8000). Your application is a different process, usually with its own virtualenv, and needs the SDK installed there so it can publish its graph topology and stream traces to that server.

6. Instrument your LangGraph app

Import motif, register the compiled graph, and wrap invocations with motif.trace().

import motif

# compile your LangGraph workflow as usual
app = workflow.compile()

# register the graph topology with the Motif server
motif.init(
    app,
    graph_id="my-workflow",
    name="My Workflow",
)

# wrap any invocation in motif.trace() to record it
with motif.trace():
    result = app.invoke(initial_state)

• motif.init() publishes the graph topology and patches invoke / ainvoke to attach tracing callbacks.
• motif.trace() records the full execution and streams events to the server.
• The server URL resolves in order: the server_url= argument to motif.init(), the MOTIF_SERVER_URL environment variable, then http://localhost:8000.

License

See LICENSE for details.