SDK reference

API for building agents with the RunForge agent-runtime SDK.

AgentRuntime

Create one runtime per project. Register your entrypoint with the @runtime.agent(name) decorator.

python

from agent_runtime import AgentRuntime

app = AgentRuntime()

@app.agent("my-agent")   # name used in logs and dashboard
def run(ctx, input):
    # ctx: RunContext, input: dict (run payload)
    return {"status": "ok"}

Entrypoint format: module:function (e.g. agent:run). The module must expose an AgentRuntime instance with at least one registered agent.
Local dev: app.serve() starts the dev server (optional).

RunContext (ctx)

Your agent function receives (ctx, input). ctx is the per-run context.

ctx.state: Dict persisted across steps and checkpoints. Use it to pass data between safe steps. Must be JSON-serializable.
ctx.log(message): Append a line to the run log (visible in run detail).
ctx.artifact(name, data, content_type): Store a file for this run. data can be bytes or str. content_type defaults to application/octet-stream. Shown in run detail.
ctx.browser: Playwright browser when browser: true in agent.yaml. Use ctx.browser.new_page(), etc. Not used for tool-only agents.
ctx.tools: Tool clients when tools are enabled (e.g. ctx.tools.gmail.read_inbox(...), ctx.tools.gmail.send_email(...)). See Tools doc.

Steps

Use safe steps for read-only or processing work; they are checkpointed and can be resumed. Use commit steps for side effects; they require approval by default.

ctx.safe_step(name)

Context manager. No approval. On success, a checkpoint is saved so the run can resume from here. Use for: reading data, computing, storing results in ctx.state or ctx.artifact.

python

with ctx.safe_step("read_inbox"):
    result = ctx.tools.gmail.read_inbox(max_results=5)
    ctx.state["emails"] = result.get("messages", [])

ctx.commit_step(name, description=None, pre_approved=False, preview=None)

Context manager. By default the run pauses until a human approves in the dashboard. Use for: sending email, submitting forms, any irreversible action. description is shown in the approval UI. pre_approved=True skips the approval prompt.

Approval context (optional): You can pass preview (a dict with e.g. type, to, subject, body_preview) so the UI shows what will happen. If you omit it, the platform automatically builds the context from the first tool call inside the step.

python

with ctx.commit_step("send_email", description="Send digest to user@example.com"):
    ctx.tools.gmail.send_email(to="user@example.com", subject="Digest", body=digest)

Agent function signature

Your registered function must have the form:

python

def run(ctx: RunContext, input: dict) -> dict:

input — JSON payload passed when triggering the run (optional). Use input.get("key", default) for optional keys.
return — A dict is stored as the run result and shown in the dashboard.

agent.yaml (optional)

In the repo root. The platform reads: name, entrypoint, python_version, browser, tools. Example:

yaml

name: my-agent
entrypoint: agent:run
python_version: "3.11"
browser: false
tools:
  - gmail

← PreviousGetting started Next →Deploy & run