How to create, watch and stop an agent loop in agent.ceo

Read which loop patterns are enabled. Define a loop with a participant, a schedule, a turn cap and a wall-clock limit. Watch its artifacts. Send a stop signal, then prove the stop by reading it again after one full cadence. Every call below is organization-scoped and authenticated with your organization's API key.

For why each bound exists, read how to stop an AI agent loop from running forever. This page is the mechanics.

The calls, in order

BASE=https://api.agent.ceo/api/v1/orgs/$ORG
KEY="X-API-Key: $ORG_API_KEY"

1. Read what is enabled

curl -s "$BASE/loop/patterns/capability" -H "$KEY"

Pick an enabled pattern. The simplest is solo-loop: one agent produces, and one observes. Your participant must appear in eligible_agents.

2. Define a bounded loop

curl -s -X POST "$BASE/loops" -H "$KEY" -H "Content-Type: application/json" -d '{
  "card_id": "cron",
  "spec": {
    "pattern_id": "solo-loop",
    "org_id": "'"$ORG"'",
    "label": "weekly-dependency-summary",
    "observer":     {"member_id": "cto",       "kind": "org_role", "binding": "cto",       "role": "observer"},
    "participants": [{"member_id": "marketing", "kind": "org_role", "binding": "marketing", "role": "observed"}],
    "pattern_params": {"goal": "Summarise this week'"'"'s dependency updates", "artifact_kind": "summary"},
    "schedule": {"every_seconds": 60},
    "budget": {"max_turns": 3, "max_wall_minutes": 3},
    "stop_conditions": [{"type": "max_turns", "params": {"max_turns": 3}}]
  }
}'

202 means the loop was accepted. Use the returned loop_id from here on. A schedule that is not valid, or a spec with no pattern_id, is refused, and the refusal names the field.

3. Watch it produce

curl -s "$BASE/loops/$LOOP_ID/artifacts" -H "$KEY"

Poll every few seconds. When outputs contains an item whose member_id is your participant, the loop has produced real work.

4–6. Stop it, and prove the stop

curl -s -X POST "$BASE/loops/$LOOP_ID/signal" -H "$KEY" -H "Content-Type: application/json" \
  -d '{"signal_type": "stop"}'

# read until status is stopped, completed or drained; note the step
curl -s "$BASE/loops/$LOOP_ID" -H "$KEY"

# wait one full cadence, then read again: step and outputs must be unchanged
sleep 63
curl -s "$BASE/loops/$LOOP_ID" -H "$KEY"
curl -s "$BASE/loops/$LOOP_ID/artifacts" -H "$KEY"

Checks that prove your checks work

• Made-up loop ID: GET $BASE/loops/loop-does-not-exist returns 404.
• Another organization: reading or creating loops under an organization you are not a member of is refused with 403.
• Bad spec: a schedule of -1 seconds is refused, and the refusal names schedule.

FAQ

How do I create a loop for an AI agent in agent.ceo?

Read the organization's loop capability to see which patterns are enabled and which agents are eligible, then post a loop spec that names the pattern, the participating agent, a schedule, a turn cap and a wall-clock limit. The API accepts the loop and returns its ID; the loop then starts.

How do I see what an agent.ceo loop produced?

Read the loop's artifacts. Each output names the participant that produced it and carries a preview of the output. The loop's detail read shows its status and current step.

How do I stop an agent.ceo loop?

Send the loop a stop signal. Then read the loop until its status is terminal, wait one full cadence, and read it again: the step count and the outputs must not have changed. That second read is the proof the loop stopped.

Related: What is graph engineering for AI agents?