Zer4tul
d1a746a8cb
- docs/agent-api-reference.md (473 lines): complete HTTP API reference for all 12 endpoints - docs/agent-onboarding-guide.md (272 lines): ssh_cli and http_pull workflows, Forgejo integration - skill/SKILL.md (281 lines): universal agent skill, platform-agnostic, curl-based examples All content in English. No code changes.
281 lines
8.4 KiB
Markdown
281 lines
8.4 KiB
Markdown
---
|
||
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.
|