Skip to content
Developer docs

Agent kit (ADK)

Write an agent in one agent.toml file or a few lines of Python, run and serve it locally, and let REM CloudHub run it with limits, checkpoints, permissions and telemetry.

The ADK (agent development kit) is how REM CloudHub agents are built. An agent is one agent.toml file or one Python file; only name and prompt are required, and everything else has a safe default. REM CloudHub runs every agent through the kit inside the agent's own sandbox, with REM CloudHub answering its permission questions and receiving its telemetry. You can also run the kit on your own machine.

Install and first run

The kit ships as a Python wheel (Python 3.12 or newer). Install it from the wheel file your platform provides, not from a public package index, where the name adk may belong to an unrelated package.

pip install adk-0.1.0-py3-none-any.whl     # add [postgres] for Postgres checkpoints
export OPENAI_BASE_URL="<your REM CloudHub AI endpoint>"
export OPENAI_API_KEY="$QFS_AI_KEY"          # a REM CloudHub AI key
adk new invoice-watcher                      # writes agent.toml
adk run agent.toml "hello"                   # runs it and prints the reply

Pointing the kit at the REM CloudHub AI gateway means its calls use your key's models, budget and spend tracking.

from adk import Agent

def word_count(text: str) -> int:
    """Count the words in a text."""
    return len(text.split())

agent = Agent.from_file("agent.toml", tools=[word_count])
print(agent.run("How many words are in: one small file is enough?").output)

The commands

Command

Does

Exit code

adk new NAME

Writes a starter agent.toml (never overwrites)

0, 1

adk run FILE [TEXT]

Runs and prints the reply

0 done, 1 error, 3 needs a person, 4 stopped

adk serve FILE --port 8000

Serves the HTTP API and runs the schedule

adk approve FILE RUN APPROVAL [--reject]

Answers an approval; the run continues

adk resume FILE RUN

Continues a paused or crashed run from its checkpoint

adk check FILE

Validates without running

0, 1

adk schema

Prints the JSON Schema of agent.toml

0

A mistake gets a plain answer with the line number, not a traceback:

agent.toml needs fixing:
  line 4: `limits.max_stepz` is not a setting ADK knows. Check the spelling, or remove the line.

A complete agent.toml

name = "invoice-watcher"
description = "Checks for new invoices every 15 minutes."
prompt = "Check for new invoices and report anything odd."
model = "mid"                       # high, mid, low, or a model id
knowledge = ["docs"]                # mounted read-only at /knowledge/0/
permissions = ["file:read", "report:write"]   # the most it may ever do
approvals = ["report:write"]        # a person says yes first

[trigger]
every = "15m"
input = "Check now."

[limits]
max_steps = 30
max_seconds = 300
max_spend_usd = 5
end_date = "2030-01-01T00:00:00"

[[mcp]]
name = "files"
url = "https://remcloudhub.com/mcp/files"
permission = "file:read"
headers = { Authorization = "env:FILES_MCP_AUTH" }

[[subagents]]
name = "summariser"
description = "Writes a short summary of a set of invoices."
prompt = "Summarise the invoices you are given in five lines."
model = "low"

Values such as env:FILES_MCP_AUTH read the environment, so no secret is written in the file. Unknown settings are errors, so a typo never silently drops a limit.

What you get without asking

Default

Limits

200 model calls and one hour of active work per run; transient model errors retried 4 times with back-off. A spend limit fails closed on a model with no known price

Checkpoints

Every step is checkpointed (SQLite next to the file, or Postgres); adk resume continues a killed run

Watchdog

On progress, not liveness: no progress for 300 s restarts the turn from the checkpoint; 3 failures pause the run

Permissions

Checked on every tool call, in the agent and every sub-agent. Effective permission = agent AND person AND holder, and a deny wins

Approvals

A gated call pauses only that thread until a person answers; permissions are checked again after the answer

Redaction

Secret-looking values (keys, tokens, passwords, private keys, credentials in URLs) are replaced by [REDACTED] in tool output and every telemetry event

Telemetry

Every model and tool call as an event; prompts are not recorded unless the agent is granted full capture

Auth

none for development only: with ADK_ENV=production an agent without authentication refuses to start

The kit enforces every tool call; it cannot control what the code inside an allowed tool does. Review your own tools as you would any code.

Serving it

adk serve exposes an HTTP API: GET /health, GET /.well-known/agent-card.json (an A2A agent card for discovery), GET /capabilities (tools, skills, MCP status and the permissions for this caller), POST /runs ({input, thread_id?}, answers 202 with the run), GET /runs/{id}, server-sent events for a run, approvals, resume, cancel, a kill switch, and POST /webhook (HMAC-signed with the secret named in trigger.secret_env). Authentication modes: none, oidc (an identity provider's tokens) or token (an HS256 secret of 32+ bytes or a JWKS URL).

How REM CloudHub runs your agent

When you create an agent in AI > Agents, REM CloudHub stores its spec as an immutable version, and each run starts the kit in the agent's sandbox with a short-lived run token (qchar_). The kit asks REM CloudHub, at each tool call, whether the person and the holder may do it; REM CloudHub can only narrow, never widen, what the agent's own spec allows. Spend goes to the agent's AI key; events go to the run's trace you see in the console. Pausing or stopping the agent revokes its tokens at once.

Related: Agents in the console · MCP server

Download: PDF · Word · Markdown