SDK reference

Everything the SDK gives your agent, and everything it asks of it.

The CLI

Command	What it does
`redline init`	Scaffolds the doorway file (and `redline.config.ts` in TypeScript).
`redline dev`	Connects: registers your agents and executes their runs. Leave it running.
`redline doctor`	Checks the wiring — key, URL, agent file, env files, tool injection — without spending a run.

In a Node project, prefix with npx. Two environment variables matter:

Variable	What it is
`REDLINE_API_KEY`	Your project’s runner key (`rl_…`), created on the Agents page.
`REDLINE_URL`	Where the platform lives. Only needed if it is not the default.

`defineAgent`

import { defineAgent } from "@redlineai/sdk";

export const myAgent = defineAgent({
  id: "my-agent",           // a kebab-case slug: letters, digits, dashes
  name: "My Agent",         // the display name on the Agents page
  description: "…",         // optional
  run: async (task, ctx) => "the final answer",
});

run must return the final answer as a string (an object is serialised). Throwing marks the run errored with that message.

In Python it is a decorator:

from redline import agent

@agent(id="my-agent", name="My Agent")
def run(task, ctx):
    return "the final answer"

`task` — what your function is given

Field	What it holds
`task.prompt`	The instructions the experiment’s task carries, plus a briefing of anything attached.
`task.name`	The task’s name, for your logs.
`task.files`	What was attached: `id`, `name`, `kind`, and a source when there is one.
`task.assets`	The MCP servers, skills, CLIs, SDKs and plugins the experiment attached.
`task.attempt` / `task.maxAttempts`	Which attempt this is, of how many trials.
`task.experiment`	`{ id, name }` — the experiment this run belongs to.

`ctx` — the run’s reporter

Everything here lands in the run’s transcript live. All of it is optional; with an OpenTelemetry-speaking framework most of it is captured for you.

Method	What it records
`ctx.thinking(text)`	A line of reasoning.
`ctx.tool(name, input?)`	A tool call.
`ctx.toolResult(name, result?, isError?)`	What that call returned.
`ctx.log(text)`	Anything worth keeping that is neither.
`ctx.artifact(name, content)`	A named file or report, kept on the run.
`ctx.usage(tokens, costCents?)`	Model usage, when your agent knows it. Adds up across calls.
`ctx.cancelled`	`true` once the run has been cancelled. Long loops should check it.

Python has the same surface with snake_case: ctx.thinking(), ctx.tool(), ctx.tool_result(), ctx.artifact(), ctx.usage(), ctx.cancelled.

`redlineTools(task, options?)`

Turns what the experiment attached into tools your agent can call.

const attached = await redlineTools(task);

On the result	What it is
`attached.tools`	Ready to spread into a Vercel AI SDK `tools:` object.
`attached.list`	The same tools, framework-neutral, with plain JSON Schema.
`attached.langchain()`	LangChain `StructuredTool`s, when `@langchain/core` is installed.
`attached.skipped`	What could not be wired up, and why — so a run never silently lacks a tool.
`attached.close()`	Closes the MCP connections. Also runs at process exit.

Options: timeoutMs (how long to wait for a server to connect and list its tools, default 30s), skillTool (also expose skills as a read_skill tool — off by default, since skills already arrive in the prompt), and machine (used internally to attach the run’s machine).

In Python: attached = await redline_tools(task), then attached.for_pydantic_ai(), attached.for_langchain() or attached.as_openai_schema(), closed with await attached.close(). Needs pip install redlineai-sdk[mcp].

`machine_run`

When the experiment attached something that has to physically exist — a repository, an upload, a CLI, an SDK package, a plugin — the run is given a container, and this tool appears in your agent’s tool list automatically.

machine_run({ command: "ls -la", cwd: "billing-api" })

It is a real bash line on Ubuntu, starting in /workspace, with node, python3, git and sudo available. cwd may be relative — it resolves against the workspace. The box is built on the first call and destroyed once the run and its judging are over; a run that never calls it never builds one.

`installClis(task)`

Runs the install command of every CLI the experiment attached, on your own machine. Redline never does this for you — see the warning in Bring your own agent. Returns one { name, ok, output } per CLI.

`redline.config.ts`

import { defineConfig } from "@redlineai/sdk";

export default defineConfig({
  url: "https://redline.example.com",   // usually left out
  apiKey: process.env.REDLINE_API_KEY,  // usually left out; the env var is read
  agents: ["redline/*.ts"],             // globs, from this file's directory
  envFiles: [".env", "server/.env"],    // usually left out — see below
});

Leave envFiles out and redline dev finds them itself: .env and .env.local in the repository root and up to two levels down (server/.env, apps/api/.env). Variables already in your shell are never overwritten. Set env: false to load nothing, when your process is already configured.