redlineai-sdk

Run your own agent inside a Redline experiment — from your repository, on your machine, against the same tasks and rubrics as the agents in the catalog.

Your agent does not move. It stays where it is, keeps its own dependencies and its own model keys, and Redline sends it work.

Install

pip install redlineai-sdk
redline init

init writes agents.py — one file, holding one TODO.

Wrap what you already wrote

from redline import agent
from myapp.agent import your_agent      # ← your existing code, unchanged


@agent(id="my-agent", name="My Agent", description="Describe what it is good at.")
def run(task, ctx):
    ctx.thinking("Working out what the task needs…")
    return your_agent(task.prompt)      # ← the one line that is yours

Then:

export REDLINE_API_KEY=rl_…            # Agents page → Connect your agent
redline dev

That registers the agent with your project and holds a connection open. It now appears on the Agents page, can be selected in an experiment, and runs on your machine when one is launched.

There is no endpoint to expose and nothing deployed to us — redline dev connects outbound and pulls its work, so it runs from a laptop behind NAT.

Telemetry you do not have to write

pip install "redlineai-sdk[otel]"

Any framework that speaks OpenTelemetry — Pydantic AI, LangChain's instrumentation, anything on the global tracer — has its LLM and tool spans land in the run's transcript by itself. ctx.thinking(...) is there for what the spans do not say.

What an experiment gives your agent

An experiment can attach MCP servers, skills, CLIs and repositories. Those arrive as real tools, not as prose in the prompt:

pip install "redlineai-sdk[mcp]"

import asyncio
from redline import agent, redline_tools


@agent(id="my-agent", name="My Agent")
def run(task, ctx):
    attached = asyncio.run(redline_tools(task))   # MCP tools + machine_run
    return your_agent(task.prompt, tools=attached.as_openai_schema())

AttachedTools also hands them over ready-shaped: for_pydantic_ai() returns Pydantic AI Tools, for_langchain() returns StructuredTools.

If your agent uses Pydantic AI or LangChain, you can skip even that. redline dev patches pydantic_ai.Agent, langgraph.prebuilt.create_react_agent and langchain.agents.create_tool_calling_agent as they are constructed, so the experiment's tools are already on your agent without a line of yours changing.

The machine

machine_run is there in every run — not only the ones that attached something. Your agent runs on your laptop; this is a shell on the project's Linux machine, in a directory of the run's own. Attach a repository and it is already cloned there; attach nothing and you still have a computer, which is what an agent needs the moment a task says "write a file".

attached = asyncio.run(redline_tools(task))
# → machine_run, plus a tool per attached MCP server

The machine starts when you first call the tool and never before, so a run that does not use it costs nothing.

Your repo's environment

redline dev is a second entry point into your app, and your real one almost always loads a .env first — so this one does too, searching the root and one level down. Shell variables always win. REDLINE_ENV_FILES=server/.env takes exact control.

Commands

Where agents are found

agents.py, or every *.py in an agents/ folder. Not redline.py — a file by that name in your working directory shadows this package on sys.path, and the import error it produces blames the wrong thing entirely.

Names

The npm package is scoped and PyPI has no scopes, so @redlineai/sdk cannot exist here — redlineai-sdk is the same name with the slash flattened. The import stays redline, which is what you type a hundred times more often than the install line.

pip install redline-sdk also works; it is a shim that installs this.

Docs

https://tryredlineai.co/docs/agents/your-agent

MIT.