> ## Documentation Index
> Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentRail SDK overview: harnesses, MCP, and runners

> Learn when to use the TypeScript or Python SDK to build agent harnesses, MCP servers, and workflow runners, and when to use the CLI instead.

The AgentRail TypeScript and Python SDKs are clients for the AgentRail Task Lifecycle API. They do not start AgentRail, connect providers, wake local agents, or create local configuration. You must run an AgentRail API first, then point the SDK at it.

## When to use the SDK

Use the SDK when you are building any of the following outside the managed local runner:

* **External agent harness** — a Node.js or Python service that drives coding agents on your behalf
* **MCP server** — a Model Context Protocol server that needs to read or write AgentRail task state
* **Workflow runner** — an orchestration layer that submits work, polls CI, and ships when conditions are met
* **Internal service or test tool** — anything that should call AgentRail directly over HTTP

## When NOT to use the SDK

Managed local agents launched by `agentrail server start` do not need the SDK. Those agents receive a single run-scoped task and interact with AgentRail through the CLI:

```bash theme={null}
agentrail run current
agentrail run actions
agentrail agent report
```

These commands are scoped to the current run and do not expose task lists or provider credentials. Using the SDK from inside a managed agent would bypass that scoping.

## Available SDKs

AgentRail ships two SDKs with identical coverage of the Task Lifecycle API.

|         | TypeScript            | Python       |
| ------- | --------------------- | ------------ |
| Package | `@agentrail-core/sdk` | `agentrail`  |
| Runtime | Node.js 18+           | Python 3.10+ |
| HTTP    | Native `fetch`        | `httpx`      |
| Models  | TypeScript types      | Pydantic v2  |
| Style   | Promise-based         | Async-first  |

Both SDKs require you to supply `baseUrl` (or `base_url`) and `apiKey` (or `api_key`) explicitly. There are no hidden defaults that silently fall back to a local server.

<Note>
  Run `agentrail init` and `agentrail agent create` to generate `~/.agentrail/agent.env` with the two values you need before using either SDK.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Install the TypeScript SDK" icon="npm" href="/docs/sdk/typescript/installation">
    Set up `@agentrail-core/sdk` for Node.js 18+.
  </Card>

  <Card title="Install the Python SDK" icon="python" href="/docs/sdk/python/installation">
    Set up `agentrail` for Python 3.10+ with async/await.
  </Card>
</CardGroup>