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.

machine_run is the interesting one. An experiment that attaches a repository clones it onto the project's machine, and your agent — running on your laptop — reaches that machine through the tool. It is a computer with your task's materials already on it.

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.