Agents & schedules

An agent is a deployed function given a persistent identity and an autonomy budget. Schedules make any function run on its own cadence. Together they are the platform's answer to "programs that act on their own — inside limits their owner set".

Agents

POST /api/cloud/v1/agents
{
  "slug": "price-watcher",
  "name": "Price Watcher",
  "functionId": "…",              // the deployed function this agent runs
  "capabilities": ["READ_CHAIN", "PERSIST_STATE"],
  "maxSpendPerRunNanm": "10000000",
  "dailySpendCapNanm": "100000000"
}

POST /api/cloud/v1/agents/{slug}/run     { "payload": { … } }

• An agent can carry its own native anim1… address — a real identity it can be paid at.
• maxSpendPerRunNanm and dailySpendCapNanm are enforced server-side by the host broker on every spend, atomically — an agent cannot exceed them no matter what its code does.
• Agent runs are ordinary executions (callerKind: "agent") with the full admission stack: plan, quotas, affordability, settlement.
• Status: ACTIVE / PAUSED / DISABLED / SUSPENDED — anything but ACTIVE refuses runs.

Agent-to-agent calls

Inside any execution, animica.call("owner/slug", payload) invokes another published function as a nested execution in the same call tree:

import animica

def main(request, ctx):
    # delegate to another published function — a real nested execution
    res = animica.call("examples/anm-toolkit", {"op": "convert", "anm": "0.25"})
    return {"delegated": res["status"], "cost_nanm": res["cost_nanm"], "out": res["result"]}

Each hop returns {status, result, request_id, cost_nanm}, and every nested run is a real execution row with parentExecutionId/rootId/depth — the whole trace is reconstructable and billed transparently. The working agent-calls-app example shows a paid nested call end to end.

Schedules

POST /api/cloud/v1/schedules
{ "functionId": "…", "kind": "interval", "intervalMinutes": 60, "payload": {} }

# or 5-field UTC cron (minute hour dom month dow; Vixie dom/dow semantics):
{ "functionId": "…", "kind": "cron", "cron": "*/15 * * * *" }

• The scheduler fires due schedules through the normal execution path — callerKind: "schedule", the schedule's owner as the paying account, full admission control applied. Since the owner is usually the function's developer, scheduled runs of your own function consume plan quota rather than ANM.
• Minimum interval is your plan's min_schedule_minutes (Free: hourly · Developer: 15 min · Pro/Business: 5 min), never below the platform floor of 5 minutes.
• Soft failures (quota, funds, capacity) defer the run; hard failures count toward auto-disable after 5 consecutive failures, with the reason recorded on the schedule.
• Use animica.state for memory between runs — see the working scheduled-agent example.