Skip to main content
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:
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. 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.
Run agentrail init and agentrail agent create to generate ~/.agentrail/agent.env with the two values you need before using either SDK.

​
Next steps

Install the TypeScript SDK

Set up @agentrail-core/sdk for Node.js 18+.

Install the Python SDK

Set up agentrail for Python 3.10+ with async/await.