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 — the MCP client ships with this package, so there is nothing extra to install:

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 has its own tool registry — which most do past the prototype stage — there is a framework-free pair. as_openai_schema() is what to advertise to the model, and call() is what to do when it picks one:

attached = asyncio.run(redline_tools(task))

my_tools += attached.as_openai_schema()               # advertise
result = asyncio.run(attached.call(name, arguments))  # execute

Nothing there knows anything about your framework, and it is the whole integration for a hand-rolled loop.

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.

Monitoring — the same agent after it ships

@agent puts your agent inside an experiment, where the attacks are ours. @observe reports it doing real work, checked by the same detectors — one decorator on the handler your backend already has:

from redline import observe

@observe(agent="support-agent", session_arg="conversation_id",
         user_arg="user_id", input_arg="text")
async def handle_message(conversation_id: str, user_id: str, text: str) -> str:
    return await your_agent(text)

Every call becomes a session in Monitor → Sessions: the decorator records the input and the returned answer itself, and every LLM call, tool call and token count the process's OpenTelemetry instrumentation emits during the call — Pydantic AI, LangChain/LangGraph, CrewAI through their OpenInference instrumentors — lands in the same session automatically. Calls sharing session_arg's value land in the same transcript. Config is environment only — REDLINE_API_KEY, REDLINE_URL, REDLINE_AGENT — so a deploy needs no code; without the key the decorator is inert and the handler runs untouched. Errors are reported and re-raised; nothing in the decorator can take the handler down.

For a handler shape the decorator cannot wrap, create_monitor remains as the explicit low-level client underneath.

Docs

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

MIT.