Your agents.
One operational view.

Choose your agent environment

Python 3.10+. Download beside your agent, verify your credential, then wrap your existing work. No packages required.

Invoke-WebRequest https://toolcaise.com/downloads/toolcaise_agent.py -OutFile toolcaise_agent.py
$secret = Read-Host 'Agent credential' -AsSecureString
$env:TOOLCAISE_AGENT_TOKEN = [System.Net.NetworkCredential]::new('', $secret).Password
python toolcaise_agent.py check

from toolcaise_agent import Toolcaise
from your_agent import main  # your existing function

client = Toolcaise()
with client.run("daily-work") as run_id:
    with client.span(run_id, "agent-work"):
        main()
# Add client.checkpoint(run_id) between safe steps to opt into controls.

Replace example imports and image names with your actual agent. The SDK reports metadata, never prompts, outputs, or exception text automatically. Runs send heartbeats every 60 seconds. Telemetry failures raise errors; handle them explicitly in your application.

Opt into controls at safe boundaries.

Add checkpoints between steps. A pause waits for resume; cancellation raises AgentCancelled. Network or authorization failures stop the guarded operation. Checkpoints cannot stop an external action already in progress. Use one SDK client per agent process; do not share it across concurrent runs.

# Python: your run must already be reported with client.run().
client.checkpoint(run_id)
result = client.guarded_action(
    run_id, "Approve report delivery",
    {"operation": "send_report", "report_id": report_id, "recipient": recipient},
    lambda approved: send_report(approved["report_id"], approved["recipient"]),
)
client.outcome(run_id, "Report delivery", status="succeeded")

// Node.js equivalent inside client.run():
await client.checkpoint(runId);
await client.guardedAction(runId, 'Approve report delivery',
  { operation: 'send_report', reportId, recipient },
  approved => sendReport(approved.reportId, approved.recipient));
await client.outcome(runId, 'Report delivery', { status: 'succeeded' });

Every execution parameter belongs in the action object; the callable must use the supplied snapshot. Toolcaise receives its SHA-256 digest and your safe title, not the action parameters. Approval consumption is single-use and never retried by the SDK; an uncertain response leaves the action unexecuted. A human approves or denies in Agent controls. Reported outcomes remain claims until reviewed.

Use span helpers for steps, tools, models, and retries. Optional model/tool names, token counts, and reportedCostUsd appear in run details. Span metadata accepts numbers and booleans only. Never place secrets in names, titles, labels, or event messages.

The v1 reporting contract

POST /api/v1/agents/telemetry. The credential supplies workspace and agent identity. Do not include orgId, agentId, or agent in the body.

IDs use 2–120 letters, digits, dots, underscores, colons, or hyphens. Historical event timestamps are accepted for backfills. Keep stable IDs when retrying: event inserts are deduplicated per agent, while run and delivery snapshots update. Send a run before or alongside events that reference it. Counts must be nonnegative integers; durationMs is capped at 24 hours. Event messages are limited to 600 characters.

Limits: 128 KB per request, 60 requests per minute per connection. Success returns 200 with agentId and receivedAt. 400 means invalid data, 401 invalid/revoked credential, 413 oversized body, 415 wrong content type, 429 rate limit (Retry-After: 60), and 503 temporary storage failure. Retry network errors, 429, and 503 with backoff and the same event IDs.