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))   # the experiment's MCP tools
    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.

Not here yet: the machine

The TypeScript SDK also hands the agent a machine_run tool — a shell on the project's machine, where the experiment's repositories and CLIs live. This SDK does not have it yet, so a Python agent gets the MCP tools and nothing else. If your task needs a computer, that is the gap to know about.

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.