docs: add agent API reference, onboarding guide, and universal skill
- 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.
This commit is contained in:
parent
e39a16498c
commit
d1a746a8cb
9 changed files with 1250 additions and 0 deletions
281
skill/SKILL.md
Normal file
281
skill/SKILL.md
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
---
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue