SDK

Build with the AgentBackend Python and TypeScript SDKs, or use the MCP server with Claude Code, Cursor, and Windsurf.

Installation

Requires Python 3.8+. Install via pip:

bash
pip install agentbackend

Basic Usage

Initialize the client with your API key, then call .agent(id).run(message) to get a response.

python
from agentbackend import AgentBackend

ab = AgentBackend("ak_your_key")

# Run an agent
response = ab.agent("agent_id").run("Hello!")
print(response.output)

Streaming

Use .stream() to receive tokens as they're generated. See Streaming docs for SSE protocol details.

python
for chunk in ab.agent("agent_id").stream("Tell me a story"):
    print(chunk, end="", flush=True)

Async Usage

For async/await applications, use AsyncAgentBackend as a context manager. Both .run() and .stream() have async equivalents.

python
from agentbackend import AsyncAgentBackend

async with AsyncAgentBackend("ak_your_key") as ab:
    response = await ab.agent("agent_id").run("Hello!")

    async for chunk in ab.agent("agent_id").stream("Tell me a story"):
        print(chunk, end="", flush=True)

Create Agents

Create agents from natural language or a structured config. See Agents docs for all configuration fields and orchestration types.

python
# From natural language
agent = ab.agents.create("müşteri destek botu yap")
response = agent.run("Siparişim nerede?")

# From config
agent = ab.agents.create(
    name="Support Bot",
    instructions="You are a helpful support agent.",
    model="openai/gpt-4o-mini",
    tools=[{"name": "web_search", "type": "catalog"}],
)

Knowledge (RAG)

Upload documents for retrieval-augmented generation. The SDK handles polling until the document is processed and ready. See Knowledge docs for supported formats and limits.

python
doc = ab.knowledge.upload("agent_id", "manual.pdf")
ab.knowledge.wait_for_ready(doc.id)

Data Store

Design schemas and query structured data with the Database Agent and tenant tools.

python
# The Database Agent is a built-in system agent
conv = ab.agent("database").conversation()
conv.send("Create a customers table with name, email, phone")
conv.send("Create an orders table linked to customers")

Check status

python
status = ab.tenant.status()
print(status["tables"])  # [{"table_name": "customers", ...}]

Rollback migration

python
ab.tenant.rollback(version=3)

Sessions

Pass a session_id to maintain conversation context across multiple runs. The agent remembers previous messages in the session.

python
ab.agent("agent_id").run("My name is Halit", session_id="sess_1")
ab.agent("agent_id").run("What's my name?", session_id="sess_1")  # → "Halit"

Schedules

Run agents on a cron schedule. See Schedules docs for cron syntax, delivery options, and tier limits.

python
ab.schedules.create(
    agent_id="agent_id",
    name="Daily summary",
    cron_expression="0 9 * * *",
    message="Summarize today's news",
)

Channels

Deploy agents to Telegram or Slack. Register a bot, link it to an agent, and users can message the bot directly. See Channels docs for full setup guides.

python
bot = ab.channels.register_bot("telegram", "BOT_TOKEN")
ab.channels.link_agent("agent_id", bot["id"])

Error Handling

The SDK raises typed exceptions. Catch specific errors for granular handling, or catch the base AgentBackendError for a catch-all.

python
from agentbackend import AgentBackendError, AuthenticationError, RateLimitError

try:
    response = ab.agent("agent_id").run("Hello")
except AuthenticationError:
    print("Check your API key")
except RateLimitError:
    print("Too many requests")
except AgentBackendError as e:
    print(f"Error {e.status_code}: {e}")

MCP Server

Use AgentBackend as an MCP server in Claude Code, Cursor, Windsurf, or any MCP-compatible client. Install the server package:

bash
pip install agentbackend-mcp

Claude Code

json
// ~/.claude/settings.json
{
  "mcpServers": {
    "agentbackend": {
      "command": "uvx",
      "args": ["agentbackend-mcp"],
      "env": { "AGENTBACKEND_API_KEY": "ak_..." }
    }
  }
}

Cursor / Windsurf

json
// .cursor/mcp.json
{
  "mcpServers": {
    "agentbackend": {
      "command": "uvx",
      "args": ["agentbackend-mcp"],
      "env": { "AGENTBACKEND_API_KEY": "ak_..." }
    }
  }
}
The MCP server exposes your agents as tools — your IDE can run agents, manage knowledge, and query sessions directly from the editor.