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 replyPointing 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 |
|---|---|---|
| Writes a starter | 0, 1 |
| Runs and prints the reply | 0 done, 1 error, 3 needs a person, 4 stopped |
| Serves the HTTP API and runs the schedule | |
| Answers an approval; the run continues | |
| Continues a paused or crashed run from its checkpoint | |
| Validates without running | 0, 1 |
| Prints the JSON Schema of | 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); |
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 |
Telemetry | Every model and tool call as an event; prompts are not recorded unless the agent is granted full capture |
Auth |
|
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