---
name: agent-fleet-integration
description: |
  Interact with the Agent Fleet Orchestrator. Use this skill when you need to:
  - Register as an agent and pull tasks for execution
  - Query task status or list tasks
  - Submit completion receipts
  - Retry failed tasks
  - Integrate with Forgejo Issue → Task → PR workflow
  
  Applies when the agent is acting as a worker in an Agent Fleet cluster,
  or when managing tasks on behalf of the fleet.
---

# Agent Fleet Integration Skill

## Quick Start (http_pull mode)

**Step 1.** Register your agent:
```bash
curl -X POST http://localhost:9090/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"my-agent","agent_type":"openclaw","hostname":"myhost","capabilities":["code:rust"],"max_concurrency":2}'
```

**Step 2.** Pull and execute a task:
```bash
curl -X POST http://localhost:9090/api/v1/tasks/dequeue \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"agent_id":"my-agent","capabilities":["code:rust"]}'
```

**Step 3.** Submit your result:
```bash
curl -X POST http://localhost:9090/api/v1/tasks/<task_id>/complete \
  -H 'Content-Type: application/json' \
  -d '{"task_id":"<task_id>","agent_id":"my-agent","status":"completed","duration_seconds":60,"summary":"done","artifacts":[],"error":null}'
```

---

## Choosing Your Execution Mode

| If you... | Use this mode |
|-----------|---------------|
| Have a CLI binary installed on a configured host | `ssh_cli` — Orchestrator calls you |
| Have your own scheduler or run outside configured hosts | `http_pull` — You call the API |

- `ssh_cli` agents do **not** need to call any API. The Orchestrator handles everything via SSH or local subprocess.
- `http_pull` agents must **register, heartbeat, dequeue, and complete** via HTTP API.

---

## Instructions

### http_pull Agent Lifecycle

```
Register → Heartbeat (loop) → Dequeue → Execute → Complete/Deregister
```

1. **Register** once at startup via `POST /api/v1/agents/register`.
2. **Heartbeat** periodically (every 60s recommended) via `POST /api/v1/agents/heartbeat`. Without heartbeats, you will be marked offline and your tasks requeued.
3. **Dequeue** when ready for work via `POST /api/v1/tasks/dequeue`. Returns a Task or 204 No Content.
4. **Update status** to `running` via `POST /api/v1/tasks/{task_id}/status`.
5. **Complete** the task via `POST /api/v1/tasks/{task_id}/complete` with a Receipt.
6. **Deregister** when shutting down via `POST /api/v1/agents/deregister`.

### ssh_cli Agent Notes

No API interaction required. Ensure:
- Your CLI binary is in `$PATH` on the configured host.
- Your CLI accepts a prompt via the configured template (default: `codex exec --json '{prompt}'` or `claude -p '{prompt}' --output-format json --dangerously-skip-permissions`).
- Your CLI outputs JSON to stdout with at minimum: `{"status": "completed", "summary": "..."}`.

---

## Examples

### Register

```bash
curl -X POST http://localhost:9090/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "worker-03",
    "agent_type": "openclaw",
    "hostname": "arm0",
    "capabilities": ["code:rust", "review"],
    "max_concurrency": 2,
    "metadata": {"version": "1.0"}
  }'
```

### Heartbeat

```bash
curl -X POST http://localhost:9090/api/v1/agents/heartbeat \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "worker-03"}'
```

### List Available Tasks

```bash
curl 'http://localhost:9090/api/v1/tasks?status=created'
```

### Dequeue

```bash
curl -X POST http://localhost:9090/api/v1/tasks/dequeue \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer my-token' \
  -d '{"agent_id": "worker-03", "capabilities": ["code:rust"]}'
```

Returns 200 with Task JSON, or 204 if no matching task.

### Get Task Detail

```bash
curl 'http://localhost:9090/api/v1/tasks/org%2Frepo%2342'
```

### Update Task Status

```bash
curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/status \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer my-token' \
  -d '{"status": "running"}'
```

### Complete Task with Receipt

```bash
curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/complete \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "org/repo#42",
    "agent_id": "worker-03",
    "status": "completed",
    "duration_seconds": 180,
    "summary": "Implemented the feature as described",
    "artifacts": [
      {"artifact_type": "pr", "url": "https://git.example/org/repo/pulls/15"}
    ],
    "error": null
  }'
```

### Submit Receipt

```bash
curl -X POST http://localhost:9090/api/v1/receipts \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "org/repo#42",
    "agent_id": "worker-03",
    "status": "completed",
    "duration_seconds": 180,
    "summary": "Done",
    "artifacts": [],
    "error": null
  }'
```

### Retry a Failed Task

```bash
curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/retry
```

Only works for tasks in `failed` or `agent_lost` status.

### List Agents

```bash
curl 'http://localhost:9090/api/v1/agents?status=online&capability=code:rust'
```

### Deregister

```bash
curl -X POST http://localhost:9090/api/v1/agents/deregister \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "worker-03"}'
```

### Health Check

```bash
curl http://localhost:9090/healthz
```

---

## Guidelines

### Authentication

- **http_pull endpoints** (`dequeue`, `status update`): require `Authorization: Bearer <token>` if `http_pull_token` is configured. If not configured, no auth is needed.
- **All other endpoints**: no authentication required.
- **Webhook endpoint**: requires HMAC-SHA256 signature header.

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 401 | Unauthorized | Check your Bearer token. If expired, re-register to get a new one. |
| 404 | Not Found | Task may have been completed or never existed. Move on. |
| 400 | Bad Request | Check task status — the operation may not be valid for the current state (e.g. retrying a `running` task). |
| 204 | No Content (dequeue) | No matching tasks available. Wait and retry. |
| 500 | Server Error | Retry with exponential backoff. Report if persistent. |

### Retry Strategy

- Use exponential backoff for transient errors (network, 500s): 1s, 2s, 4s, 8s, max 30s.
- Do not retry 400 errors — fix your request.
- For 404 on dequeue: poll again after a reasonable interval (e.g. 10–30 seconds).
- The Orchestrator has its own retry logic for `ssh_cli` tasks (up to `max_retries`, default 2).

### Task Status Flow

```
created → assigned → running → review_pending → completed
                               ↘ failed
                  ↘ agent_lost
         ↘ cancelled
```

- `failed` and `agent_lost` tasks can be retried via the retry endpoint.
- `review_pending` means a PR was opened and is awaiting merge/review.
- `completed` and `cancelled` are terminal states.

### Heartbeat Requirements

- Send heartbeats at least every `heartbeat_interval_secs` (default: 60s).
- If the Orchestrator doesn't receive a heartbeat within `heartbeat_interval_secs × heartbeat_timeout_threshold` (default: 60 × 3 = 180s), your agent is marked offline.
- All active tasks assigned to an offline agent are requeued to `created` status.

---

## Forgejo Workflow

### Task Creation (Issue → Task)

1. Open a Forgejo Issue with a label `agent:<type>` (e.g. `agent:code`).
2. The webhook creates a task with `task_id = {repo}#{issue_number}`.
3. Optional labels: `priority:urgent`, `priority:high`, `priority:low` control priority.

### Branch Naming

- Branch: `task/{url_encoded_task_id}`
- Example: `org/repo#42` → branch `task/org%2Frepo%2342`

### PR Workflow

1. Work on the `task/*` branch.
2. Open a PR from that branch.
3. Orchestrator receives `pull_request.opened` webhook → task goes to `review_pending`.
4. Pushes to the branch update `last_activity_at`.
5. When the PR is merged → task goes to `completed` with an auto-generated receipt.

### For http_pull Agents

After dequeuing a task, create the branch and PR yourself:

```bash
git checkout -b task/org%2Frepo%2342
# ... do the work ...
git push origin task/org%2Frepo%2342
# Create PR via Forgejo API
# The webhook will update the task automatically
```

### For ssh_cli Agents

The Orchestrator passes the branch name in the structured prompt. Create the branch, push, and open the PR as part of your CLI execution. The webhooks handle status updates.