Loops

Agentic Loops are reusable deterministic graphs stored at project level. Create a loop once with /v1/loops, then assign it to one or more agents with assignedLoops on /v1/agents. Loops are not Missions. Missions orchestrate project work and tasks; loops define how an agent routes its own runtime behavior through deterministic steps. The runtime contract is ProjectLoopConfig JSON. You can also author a loop as static TypeScript DSL source (export default defineLoop({...})) and pass it as { "source": "..." }; Polpo compiles it to the same JSON before validation and storage. The compiler recognizes the DSL helpers statically. The DSL is an authoring layer, not arbitrary executable orchestration code. Use type: "tool" for deterministic sandbox/tool actions with no model turn. Use toolChoice on type: "agent" when the model should still reason but must call a tool. Loop JSON must not contain secrets; custom tools read external credentials from project Connections through ctx.connections. At runtime, Polpo executes the selected project loop as a shared context graph. A tool step writes its result into the context bag at saveAs (or the tool name when saveAs is omitted), and each later agent step receives that context as runtime data in its system prompt. saveAs does not create shell variables; for example saveAs: "timing.start" creates context.timing.start, which later guards and agent steps can read. When a chat completion or task specifies loop, the loop must be assigned to the target agent with assignedLoops. Loop selection is explicit; omitting loop uses the normal runtime behavior. allowedTools on the Loop narrows the agent-wide tool ceiling. An agent step may narrow it again with allowedTools (legacy tools remains accepted for authored-config compatibility). When a chat or Channel turn transitions into a Loop, Polpo recalculates tool access from the Loop and current step; the prior chat or Channel policy does not continue restricting the Loop. Session, canonical history, trusted identity, metadata, and grants remain continuous. Loops can also carry enterprise controls:

permissions are readable allow, deny, or approval gates for resources such as tool, step, model, human, and loop.
policies are expression-based compliance gates for rules that depend on runtime context or payload.
hooks run deterministic tool actions at lifecycle points such as loop:start, tool:before, tool:after, and loop:end.

Every run persists a trace. The dashboard uses that trace for Loop Run Audit, Permission Audit, Hook Audit, and the consolidated Loop Governance page. Every tool referenced by a tool step, a lifecycle hook, or an agent step toolChoice must exist in the project tool catalog and be enabled for the target agent. Client-interaction tools such as ask_user_question are intentionally unavailable inside project Loops. They require a durable user-driven suspend/resume contract that Loop runs do not currently expose. Loop creation rejects these references with loop_interactive_tool_not_supported. Applications should collect clarifications in direct chat or their own UI before starting the Loop.

List loops

Returns all project-level loop definitions.

Get loop

string

required

Loop name.

Create or replace loop

The request body can be either the canonical loop JSON or { "source": "...TypeScript DSL..." }.

curl

curl -X POST https://{project}.polpo.cloud/v1/loops \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "qa-flow",
    "context": "shared",
    "start": "clone_repo",
    "steps": {
      "clone_repo": {
        "type": "tool",
        "tool": "clone_repository",
        "input": {
          "repoUrl": "https://github.com/acme/app.git",
          "targetDir": "workspace/app"
        },
        "saveAs": "repo.clone",
        "next": "plan"
      },
      "plan": {
        "type": "agent",
        "systemPrompt": "Create a concise test plan.",
        "tools": ["read", "grep"],
        "next": "approve_plan"
      },
      "approve_plan": {
        "type": "human",
        "notify": ["ops"],
        "output": { "schema": { "decision": "string" } },
        "next": [
          { "when": "approve_plan.decision == '\''approve'\''", "to": "verify" },
          { "to": "end" }
        ]
      },
      "verify": {
        "type": "agent",
        "systemPrompt": "Run tests and summarize failures.",
        "tools": ["read", "bash"],
        "toolChoice": { "mode": "required", "tool": "bash" },
        "next": "end"
      }
    },
    "permissions": [
      {
        "id": "approve-bash",
        "resource": "tool",
        "effect": "approval",
        "match": { "tool": "bash", "hook": "tool:before" },
        "message": "Approve shell execution before verification."
      }
    ],
    "hooks": {
      "loop:start": [
        {
          "tool": "audit_event",
          "input": { "event": "qa-flow-started" },
          "saveAs": "audit.started"
        }
      ],
      "loop:end": [
        {
          "tool": "audit_event",
          "input": { "event": "qa-flow-ended" },
          "saveAs": "audit.ended",
          "onError": "continue"
        }
      ]
    }
  }'

TypeScript DSL authoring example:

curl

curl -X POST https://{project}.polpo.cloud/v1/loops \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "source": "export default defineLoop({\n  name: 'qa-flow',\n  start: 'plan',\n  steps: {\n    plan: agentStep({\n      label: 'Plan',\n      systemPrompt: 'Create a concise test plan.',\n      tools: ['read', 'grep'],\n      next: 'verify'\n    }),\n    verify: agentStep({\n      label: 'Verify',\n      systemPrompt: 'Run verification and summarize failures.',\n      tools: ['read', 'bash'],\n      toolChoice: requireTool('bash'),\n      next: [when('verify.done == true', 'end'), otherwise('end')]\n    })\n  }\n});"
}
JSON

Result projection

Use optional result bindings to separate persisted structured data from the terminal text and actions shown by conversational clients:

{
  "result": {
    "data": { "$context": "finalization" },
    "presentation": {
      "text": { "$context": "finalization.response" },
      "actions": { "$context": "finalization.actions" }
    }
  }
}

Bindings are exact typed context paths, not string interpolation. Missing paths, wrong types, empty text, malformed actions, and unsafe URLs fail with loop_result_invalid. The non-streaming completion response exposes loop_result and loop_presentation; the terminal streaming chunk exposes the same fields together with loop_run_id.

Replace loop

Replaces the full loop definition. The request body uses the same shape as POST /v1/loops: canonical JSON or { "source": "...TypeScript DSL..." }.

Delete loop

Deletes the project-level loop definition. Agents that still reference the loop should be updated with /v1/agents/{name}.

Run audit

Lists recent loop runs. Filter with loopName, agentName, sessionId, user, status, and limit.

Returns one persisted loop run including status, context, approval state, and trace events.

Approves a loop run that is waiting on an approval gate and resumes execution from the checkpoint.

Rejects a loop run that is waiting on an approval gate.

Permission audit

Lists runtime permission, policy, and approval decisions extracted from loop traces. Filter with loopName, agentName, sessionId, user, kind, outcome, resource, hook, runStatus, and limit. Use this endpoint to answer why a tool, model, step, human gate, or loop transition was allowed, denied, or sent to approval.

Hook audit

Lists deterministic hook tool calls and results extracted from loop traces. Filter with loopName, agentName, sessionId, user, hook, tool, phase, outcome, runStatus, and limit. Use this endpoint to inspect setup/finalization hooks, before/after tool hooks, audit hooks, and failed hook executions.

Dashboard governance

Loop Studio includes dedicated audit surfaces:

Run detail shows the persisted trace, context bag, approval metadata, and event payloads for one loop run.
Permissions shows permission, policy, and approval decisions across runs.
Hooks shows lifecycle hook executions across runs.
Governance aggregates recent runs, controls, hook evidence, coverage, and attention signals for GRC review.

Minimal timing loop

{
  "name": "time-tracker",
  "context": "shared",
  "start": "capture_start",
  "steps": {
    "capture_start": {
      "type": "tool",
      "tool": "unix_time",
      "saveAs": "timing.start",
      "next": "capture_end"
    },
    "capture_end": {
      "type": "tool",
      "tool": "unix_time",
      "saveAs": "timing.end",
      "next": "summarize"
    },
    "summarize": {
      "type": "agent",
      "systemPrompt": "Read timing.start and timing.end from the loop runtime context. Compute duration = timing.end - timing.start and answer in seconds.",
      "next": "end"
    }
  }
}

Overview

Chat Completions

Agents

Tasks

Missions

Memory

Files

Sessions

Vault

Skills

Approvals

Schedules

Playbooks

Logs

Config

Watchers

Templates

Health

List loops

Get loop

Create or replace loop

Result projection

Replace loop

Delete loop

Run audit

Permission audit

Hook audit

Dashboard governance

Minimal timing loop

​List loops

​Get loop

​Create or replace loop

​Result projection

​Replace loop

​Delete loop

​Run audit

​Permission audit

​Hook audit

​Dashboard governance

​Minimal timing loop

List loops

Get loop

Create or replace loop

Result projection

Replace loop

Delete loop

Run audit

Permission audit

Hook audit

Dashboard governance

Minimal timing loop