diff --git a/agents/templates.mdx b/agents/templates.mdx deleted file mode 100644 index 15a93f4..0000000 --- a/agents/templates.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Templates" -description: "The shipped sample directory — pre-built agents you can install with one command." ---- - -A **template** is a directory with a valid `SKILL.md` and `TRIGGER.md`. Pick one, install it, get a working agent. - -```bash -agentsfleet install --from -``` - -The `agentsfleet` package ships sample directories under `~/.config/agentsfleet/samples/`. - -## Catalogue - -### `platform-ops` - -The flagship v2 sample. Wakes on a GitHub Actions deploy failure, gathers evidence from your hosting provider and the failed workflow, and posts an evidenced diagnosis to Slack. Read-only against your infrastructure; the only write path is the channel post. - -- **Tools:** `http_request`, `memory_recall`, `memory_store`, `cron_add`, `cron_list`, `cron_remove`. -- **Credentials:** `github` (with `webhook_secret` for signature verification), `slack` (bot token). -- **Trigger:** `webhook` from GitHub Actions (`workflow_run.conclusion=failure`). - -For the full install walkthrough — host agent, gating questions, webhook wiring — see [Quickstart](/quickstart). Don't duplicate the steps here. - -More samples land as new flagships ship. - -## Writing your own - -A template is just a directory with `SKILL.md` and `TRIGGER.md`. See [Authoring an agent](/agents/authoring) for the file references; install with: - -```bash -agentsfleet install --from . -``` - -## Sharing - -Templates are markdown — commit `my-agent/` to git, clone it on a new machine, `agentsfleet install --from .`. Credentials never live in the template; they live in the workspace vault. Template-safe to share publicly; credentials are not. - - - A hosted template marketplace (community-contributed agents, one-click install) is on the roadmap. For now, git is the distribution mechanism. - diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 87eebb9..378ae2b 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -10,8 +10,8 @@ Every `4xx` and `5xx` response uses `Content-Type: application/problem+json`: ```json { "docs_uri": "https://docs.agentsfleet.net/api-reference/error-codes#UZ-AGT-009", - "title": "Agent not found", - "detail": "No agent with id '0198a7ba-2c1d-7f08-8a45-3e9b6d2f1c70' in this workspace.", + "title": "Fleet not found", + "detail": "No fleet with id '0198a7ba-2c1d-7f08-8a45-3e9b6d2f1c70' in this workspace.", "error_code": "UZ-AGT-009", "request_id": "0198a7b5-3c8d-7e41-9a2b-6f1d4c7e8a05" } @@ -89,7 +89,7 @@ Tenant- and workspace-scoped API keys (`agt_t` / `agt_a` prefixes) managed via ` | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-AGENT-001` | 404 | Agent key not found | Agent key (`agt_a`) lookup — verify the `agent_key_id`. Distinct namespace from the tenant `UZ-APIKEY-*` codes below. | +| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key (`agt_a`) lookup — verify the `fleet_key_id`. Distinct namespace from the tenant `UZ-APIKEY-*` codes below. | | `UZ-APIKEY-001` | 401 | Invalid API key | Key is invalid or revoked | | `UZ-APIKEY-003` | 404 | API key not found | No key matches the supplied id for this tenant. Verify with `GET /v1/api-keys`. | | `UZ-APIKEY-004` | 401 | API key has been revoked | Revoked key can no longer authenticate. Mint a replacement with `POST /v1/api-keys`. | @@ -122,42 +122,55 @@ Load-shedding on a saturated API instance — back off and retry. | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-WH-001` | 404 | Agent not found for webhook | Webhook routing found no matching agent | +| `UZ-WH-001` | 404 | Fleet not found for webhook | Webhook routing found no matching fleet | | `UZ-WH-002` | 400 | Malformed webhook | Webhook body is missing required fields | | `UZ-WH-010` | 401 | Invalid webhook signature | HMAC or Svix signature verification failed. Verify the `secret_ref` vault entry matches the signing secret configured with the provider. | | `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook timestamp is older than 5 minutes (replay protection). Ensure the sender clock is not skewed. | -| `UZ-WH-020` | 401 | Webhook credential not configured | No webhook credential is configured for this agent's source. Run `agentsfleet credential add --data=@-` with `{ "webhook_secret": "..." }` in the agent's workspace, then resend. | +| `UZ-WH-020` | 401 | Webhook credential not configured | No webhook credential is configured for this fleet's source. Run `agentsfleet credential add --data=@-` with `{ "webhook_secret": "..." }` in the fleet's workspace, then resend. | | `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload at the source or filter fields before forwarding. | ## Tool | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-TOOL-005` | 400 | Unknown tool | Tool name not recognized — typo against the [Tools catalogue](/agents/tools) is the usual cause. | +| `UZ-TOOL-005` | 400 | Unknown tool | Tool name not recognized — typo against the [Tools catalogue](/fleets/tools) is the usual cause. | -**Registered, not always emitted.** `UZ-TOOL-005` is registered, but in v2 today a missing or misspelled tool usually surfaces as a NullClaw-level "no such tool" message in the activity stream rather than this wire code. Treat the code as authoritative for *meaning* if you see it, but audit `agentsfleet logs ` for the actual error text. +**Registered, not always emitted.** `UZ-TOOL-005` is registered, but in v2 today a missing or misspelled tool usually surfaces as a NullClaw-level "no such tool" message in the activity stream rather than this wire code. Treat the code as authoritative for *meaning* if you see it, but audit `agentsfleet logs ` for the actual error text. -## Agent +## Fleet | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-AGT-003` | 424 | Agent credential missing | A required vault credential is absent. Add it with `agentsfleet credential add `. | -| `UZ-AGT-004` | 500 | Agent claim failed | Agent could not be claimed from the database. Verify the `agent_id` exists and status is `active`. | -| `UZ-AGT-006` | 409 | Agent name already exists | Name taken. Kill the existing agent first, then re-install. | -| `UZ-AGT-008` | 400 | Invalid agent config | `TRIGGER.md` config_json fails schema validation. Verify trigger, tools, credentials, and budget fields. | -| `UZ-AGT-009` | 404 | Agent not found | No agent with this ID in the workspace. | -| `UZ-AGT-010` | 409 | Agent state transition not allowed | The requested lifecycle action is not valid from the agent's current state. The response detail names the specific transition that was refused. | -| `UZ-AGT-011` | 400 | SKILL.md and TRIGGER.md disagree on `name:` | Top-level `name:` must match across both files. One identity per agent bundle. | -| `UZ-AGT-012` | 409 | Agent is paused | Agent is not active and refuses new work. Resume with `agentsfleet resume `, then retry. | +| `UZ-AGT-003` | 424 | Fleet credential missing | A required vault credential is absent. Add it with `agentsfleet credential add `. | +| `UZ-AGT-004` | 500 | Fleet claim failed | Fleet could not be claimed from the database. Verify the `fleet_id` exists and status is `active`. | +| `UZ-AGT-006` | 409 | Fleet name already exists | Name taken. Kill the existing fleet first, then re-install. | +| `UZ-AGT-008` | 400 | Invalid fleet config | `TRIGGER.md` config_json fails schema validation. Verify trigger, tools, credentials, and budget fields. | +| `UZ-AGT-009` | 404 | Fleet not found | No fleet with this ID in the workspace. | +| `UZ-AGT-010` | 409 | Fleet state transition not allowed | The requested lifecycle action is not valid from the fleet's current state. The response detail names the specific transition that was refused. | +| `UZ-AGT-011` | 400 | SKILL.md and TRIGGER.md disagree on `name:` | Top-level `name:` must match across both files. One identity per fleet bundle. | +| `UZ-AGT-012` | 409 | Fleet is paused | Fleet is not active and refuses new work. Resume with `agentsfleet resume `, then retry. | + +## Fleet Bundle + +Import + snapshot of a Fleet Bundle (the SKILL.md/TRIGGER.md package behind a Fleet) via `POST /v1/workspaces/{workspace_id}/fleets/bundles/snapshots`. + +| Code | HTTP | Title | Common Causes | +|---|---|---|---| +| `UZ-BUNDLE-001` | 400 | Invalid Fleet Bundle | The supplied bundle is missing `SKILL.md` or contains unsafe, oversized, or malformed files. | +| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | No Fleet Bundle snapshot matches the supplied `bundle_id` in this workspace. | +| `UZ-BUNDLE-003` | 424 | Fleet Bundle credentials missing | Add the missing workspace credentials before installing this bundle. | +| `UZ-BUNDLE-004` | 502 | Fleet Bundle fetch failed | The bundle source could not be fetched from GitHub — the repository may be missing or private, or GitHub may be unreachable. Verify the source reference and retry. | +| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | Snapshot storage is not configured or is unavailable, so the validated bundle could not be stored. Retry later or contact the operator. | +| `UZ-BUNDLE-006` | 429 | Too many Fleet Bundle imports in flight | This instance is at its concurrent import ceiling. Honor the `Retry-After` header and retry with backoff. | ## Integration grants | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-GRANT-001` | 403 | No integration grant for service | This agent has no approved grant for the target service. Request one with `POST /v1/agents/{id}/integration-requests`. | -| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this agent, or it was already revoked. List current grants with `GET /v1/workspaces/{workspace_id}/agents/{agent_id}/integration-grants`. | +| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with `POST /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-requests`. | +| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this fleet, or it was already revoked. List current grants with `GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-grants`. | ## Approval gate @@ -181,7 +194,7 @@ Load-shedding on a saturated API instance — back off and retry. | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-MEM-002` | 404 | Agent not found for memory op | The `agent_id` on the memory call does not exist in the workspace. A cross-workspace `agent_id` also returns this 404 (not a 403) so existence is not leaked. | +| `UZ-MEM-002` | 404 | Fleet not found for memory op | The `fleet_id` on the memory call does not exist in the workspace. A cross-workspace `fleet_id` also returns this 404 (not a 403) so existence is not leaked. | | `UZ-MEM-003` | 503 | Memory backend unavailable | Memory store is unreachable. Retry the trigger; if persistent, file an issue. | ## Startup @@ -214,8 +227,8 @@ Execution-path failures from the sandboxed runner engine. | `UZ-EXEC-009` | 500 | Execution startup posture failure | Execution startup posture check failed. Verify runner security config. | | `UZ-EXEC-010` | 500 | Execution crash | The execution process crashed. Check logs for details. | | `UZ-EXEC-011` | 403 | Landlock policy deny | A Landlock (or seccomp) policy denied a filesystem or syscall operation. | -| `UZ-EXEC-012` | 500 | Runner agent init failed | Runner agent initialization failed. Check configuration. | -| `UZ-EXEC-013` | 500 | Runner agent run failed | Runner agent execution failed. Check logs for details. | +| `UZ-EXEC-012` | 500 | Runner fleet init failed | Runner fleet initialization failed. Check configuration. | +| `UZ-EXEC-013` | 500 | Runner fleet run failed | Runner fleet execution failed. Check logs for details. | | `UZ-EXEC-014` | 400 | Runner invalid config | Runner configuration is invalid. Check `config_json` fields. | ## Runner control plane @@ -237,4 +250,4 @@ The runner ↔ control-plane lease protocol (`/v1/runner/*`). Codes a runner hos ## Removed surfaces -Pipeline v1 (`/v1/runs/*`, `/v1/specs`) was permanently removed — those endpoints now return **404** (the pre-2.0 convention), not a dedicated code. Use the agent event model instead. Webhook delivery to a paused agent, cross-agent memory scope, and the legacy CLI login error-map no longer have dedicated codes either; the live equivalents are `UZ-AGT-012` (paused), `UZ-MEM-002` (memory scope → 404), and the typed CLI login codes above. +Pipeline v1 (`/v1/runs/*`, `/v1/specs`) was permanently removed — those endpoints now return **404** (the pre-2.0 convention), not a dedicated code. Use the fleet event model instead. Webhook delivery to a paused fleet, cross-fleet memory scope, and the legacy CLI login error-map no longer have dedicated codes either; the live equivalents are `UZ-AGT-012` (paused), `UZ-MEM-002` (memory scope → 404), and the typed CLI login codes above. diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 334eeb8..befe0e6 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,6 +1,6 @@ --- title: 'API Reference' -description: 'agentsfleet Control Plane API — deploy, observe, and control agents programmatically.' +description: 'agentsfleet Control Plane API — deploy, observe, and control fleets programmatically.' --- ## Base URL @@ -14,7 +14,7 @@ https://api.agentsfleet.net All API endpoints require a Bearer token in the `Authorization` header, except health checks and the initial auth session creation. ```bash -curl https://api.agentsfleet.net/v1/workspaces/0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50/agents \ +curl https://api.agentsfleet.net/v1/workspaces/0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50/fleets \ -H "Authorization: Bearer $AGENTSFLEET_API_KEY" ``` @@ -43,7 +43,7 @@ Error codes follow the `UZ--NNN` scheme in the `error_code` field. Every - **IDs** are UUIDv7. - **Timestamps** are Unix milliseconds. -- **State transitions** are partial updates on the parent resource (e.g., `PATCH /v1/workspaces/{workspace_id}/agents/{agent_id}` with body `{status: "stopped"}`). Sub-resources (e.g., `/messages`, `/events`, `/events/stream`) handle data-flow operations. +- **State transitions** are partial updates on the parent resource (e.g., `PATCH /v1/workspaces/{workspace_id}/fleets/{fleet_id}` with body `{status: "stopped"}`). Sub-resources (e.g., `/messages`, `/events`, `/events/stream`) handle data-flow operations. - **Streaming endpoints** (activity stream) return Server-Sent Events. ## Rate limits diff --git a/billing/budgets.mdx b/billing/budgets.mdx index cb1f172..f26818b 100644 --- a/billing/budgets.mdx +++ b/billing/budgets.mdx @@ -1,17 +1,17 @@ --- title: "Budgets and cost control" -description: "Per-agent dollar ceilings, tenant-wide spend caps, and how debits work." +description: "Per-fleet dollar ceilings, tenant-wide spend caps, and how debits work." --- -agentsfleet enforces budgets at two levels: per-agent ceilings declared in `TRIGGER.md`, and a tenant-wide balance that every run debits against. +agentsfleet enforces budgets at two levels: per-fleet ceilings declared in `TRIGGER.md`, and a tenant-wide balance that every run debits against. **Free until July 31, 2026.** During the launch trial, hosted execution is free — the tenant-wallet mechanics below apply **after** the trial. See [pricing](https://agentsfleet.net/pricing). -## Per-agent ceilings (`daily_dollars` / `monthly_dollars`) +## Per-fleet ceilings (`daily_dollars` / `monthly_dollars`) -Every agent declares its own dollar ceilings in `TRIGGER.md`: +Every fleet declares its own dollar ceilings in `TRIGGER.md`: ```yaml budget: @@ -22,7 +22,7 @@ budget: - `daily_dollars` caps spend over a rolling 24-hour window. - `monthly_dollars` caps spend over the calendar month. -When either ceiling is reached the agent stops processing new events and a budget breach is recorded in the activity stream. This is the first line of defence — one bad prompt never becomes an infinite burn on a single agent. +When either ceiling is reached the fleet stops processing new events and a budget breach is recorded in the activity stream. This is the first line of defence — one bad prompt never becomes an infinite burn on a single fleet. Per-event token and wall-clock caps are internal runtime controls. They are not user-configurable in `TRIGGER.md` today. @@ -43,7 +43,7 @@ Set a monthly spend cap on your tenant from the billing page at [app.agentsfleet Cancel an in-flight run at any time via CLI or API: ```bash -agentsfleet kill +agentsfleet kill ``` Cancelling stops the run at the next lease renewal. The run time already elapsed is metered and debited — cancelling doesn't refund the work done so far. See [Credit deduction timing](#credit-deduction-timing) below for the full rule. diff --git a/billing/plans.mdx b/billing/plans.mdx index 889e321..1543563 100644 --- a/billing/plans.mdx +++ b/billing/plans.mdx @@ -3,7 +3,7 @@ title: "Plans" description: "One credit-based model — the starter credit and how per-second run billing works." --- -agentsfleet has a single credit-based model. Every tenant gets the full platform — always-on agent hosting, the tool bridge, activity stream, webhook ingestion, kill switch — and pays from one shared credit wallet. There are no tiers to choose between or upgrade to. +agentsfleet has a single credit-based model. Every tenant gets the full platform — always-on fleet hosting, the tool bridge, activity stream, webhook ingestion, kill switch — and pays from one shared credit wallet. There are no tiers to choose between or upgrade to. **Free until July 31, 2026.** During the launch trial, hosted execution — every event receipt and run — is free. The billing details below describe charging **after** the trial. See [pricing](https://agentsfleet.net/pricing). @@ -16,7 +16,7 @@ New tenants start with **$5 (500¢)** seeded into the tenant balance automatical | Feature | Details | |---------|---------| | Starter credit | $5 (500¢), tenant-scoped | -| Agents per workspace | Unlimited | +| Fleets per workspace | Unlimited | | Workspaces | Unlimited | | Event processing | Included | | Support | Community (Discord, GitHub) | diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index 4d556d7..b44c9e2 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -8,12 +8,12 @@ description: "Complete agentsfleet command reference." | Group | Commands | |-------|----------| | Authentication | `login`, `logout`, `auth status` | -| Agents (top-level) | `install --from`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` | -| Agents (in-place update) | `agent update --from` | +| Fleets (top-level) | `install --from`, `install --template`, `templates`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` | +| Fleets (in-place update) | `fleet update --from` | | Credentials | `credential add`, `credential show`, `credential list`, `credential delete` | | Workspaces | `workspace add`, `workspace list`, `workspace use`, `workspace show`, `workspace credentials`, `workspace delete` | | Memory | `memory list`, `memory search` | -| External agents | `agent-key add`, `agent-key list`, `agent-key delete` | +| Fleet keys (external access) | `fleet-key add`, `fleet-key list`, `fleet-key delete` | | Integration grants | `grant list`, `grant delete` | | Billing | `billing show` | | Tenant provider | `tenant provider show`, `tenant provider add`, `tenant provider delete` | @@ -87,33 +87,61 @@ The probe result is one of `valid` (200 from the billing endpoint), `unauthorize --- -## Agents +## Fleets ### `agentsfleet install --from ` -Reads `SKILL.md` and `TRIGGER.md` from ``, validates them, and uploads to the active workspace. The two markdown files are the configuration; the `agentsfleet-install-platform-ops` host-agent skill is what generates them under `.agentsfleet//` in your repo. The `--from` flag is required — there are no bare-name template aliases. +Reads `SKILL.md` and `TRIGGER.md` from ``, validates them, and uploads to the active workspace. The two markdown files are the configuration; the `agentsfleet-install-platform-ops` host-agent skill is what generates them under `.agentsfleet//` in your repo. The `--from` flag is required — there are no bare-name template aliases. ```bash agentsfleet install --from ~/.config/agentsfleet/samples/platform-ops ``` -The `samples/` directory ships with `agentsfleet` and contains the flagship `platform-ops` sample. The host-agent install skill (`/agentsfleet-install-platform-ops`) drives this command under the hood. See [Quickstart](/quickstart) and [Templates](/agents/templates). +The `samples/` directory ships with `agentsfleet` and contains the flagship `platform-ops` sample. The host-agent install skill (`/agentsfleet-install-platform-ops`) drives this command under the hood. See [Quickstart](/quickstart) and [Templates](/fleets/templates). -### `agentsfleet agent update --from ` +### `agentsfleet install --template ` -Re-parse `SKILL.md` and `TRIGGER.md` from a local bundle and `PATCH` them onto an existing agent — the in-place counterpart to `install`. Use it to roll a configuration change onto an already-registered agent without re-creating it. +Install a fleet from the first-party template catalogue (browse it with `agentsfleet templates`) instead of a local directory. agentsfleet fetches the template's pinned source, validates it, prints a requirements preview (credentials, tools, network hosts), then creates the fleet. ```bash -agentsfleet agent update 01900000-0000-7000-8000-000000000001 --from ~/.config/agentsfleet/samples/platform-ops +agentsfleet install --template github-pr-reviewer +agentsfleet install --template github-pr-reviewer --name pr-reviewer-frontend +``` + +`--from` and `--template` are mutually exclusive — exactly one source per install. If the template ships no `TRIGGER.md`, a default API wake is generated and the result notes it. + +| Flag | Default | Purpose | +|------|---------|---------| +| `--from ` | *(one source required)* | Install from a local directory containing `SKILL.md` + `TRIGGER.md`. | +| `--template ` | *(one source required)* | Install from a catalogue template by id (see `agentsfleet templates`). | +| `--name ` | *(SKILL.md `name:`)* | Override the fleet name so one bundle or template can back several fleets in a workspace. Without it, a second install of the same source collides with `UZ-AGT-006`. | + +### `agentsfleet templates` + +List the first-party template catalogue — the same gallery the dashboard shows. Reads `GET /v1/fleets/bundles`; metadata only, no workspace required. + +```bash +agentsfleet templates +agentsfleet templates --json +``` + +Prints a table of template id, name, and required credentials. Pass `--json` for the full metadata (declared tools, network hosts). Install one with `agentsfleet install --template `. See [Templates](/fleets/templates). + +### `agentsfleet fleet update --from ` + +Re-parse `SKILL.md` and `TRIGGER.md` from a local bundle and `PATCH` them onto an existing fleet — the in-place counterpart to `install`. Use it to roll a configuration change onto an already-registered fleet without re-creating it. + +```bash +agentsfleet fleet update 01900000-0000-7000-8000-000000000001 --from ~/.config/agentsfleet/samples/platform-ops ``` | Flag | Default | Purpose | |------|---------|---------| -| `--from ` | *(required)* | Local bundle whose `SKILL.md` + `TRIGGER.md` are re-parsed and patched onto the agent. | +| `--from ` | *(required)* | Local bundle whose `SKILL.md` + `TRIGGER.md` are re-parsed and patched onto the fleet. | ### `agentsfleet list` -List agents in the active workspace. Keyset-paginated over `(created_at, id)` — the dashboard `/agents` page uses the same contract. +List fleets in the active workspace. Keyset-paginated over `(created_at, id)` — the dashboard `/fleets` page uses the same contract. ```bash agentsfleet list --limit 20 @@ -130,22 +158,22 @@ Human-readable output prints a table and, when more pages remain, a "Next" hint ### `agentsfleet status` -List every agent in the current workspace with state, events processed, and budget consumed. +List every fleet in the current workspace with state, events processed, and budget consumed. ```bash agentsfleet status ``` -### Agent lifecycle: `stop` / `resume` / `kill` / `delete` +### Fleet lifecycle: `stop` / `resume` / `kill` / `delete` -Four verbs control an agent's lifecycle, in increasing order of irreversibility: +Four verbs control a fleet's lifecycle, in increasing order of irreversibility: | Verb | What it does | Reversible? | |---|---|---| -| `stop ` | Halt the running session. New events stop dispatching; in-flight run finishes cleanly. | Yes — `agentsfleet resume`. | -| `resume ` | Resume from `stopped` or auto-paused state. | — | -| `kill ` | Mark terminal. The agent won't process events again, but its row, history, and webhook URL persist. | No, but the agent can be `delete`d after. | -| `delete ` | Hard-delete. Removes the agent row and its webhook URL. **Must `kill` first.** | No. | +| `stop ` | Halt the running session. New events stop dispatching; in-flight run finishes cleanly. | Yes — `agentsfleet resume`. | +| `resume ` | Resume from `stopped` or auto-paused state. | — | +| `kill ` | Mark terminal. The fleet won't process events again, but its row, history, and webhook URL persist. | No, but the fleet can be `delete`d after. | +| `delete ` | Hard-delete. Removes the fleet row and its webhook URL. **Must `kill` first.** | No. | ```bash agentsfleet stop 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 # pause; resumable @@ -156,9 +184,9 @@ agentsfleet delete 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 # hard-delete; webhook State is checkpointed at every transition — nothing on the activity stream is lost until the final `delete`. -### `agentsfleet logs ` +### `agentsfleet logs ` -Print the agent's recent activity stream — newest-first, paginated. +Print the fleet's recent activity stream — newest-first, paginated. ```bash agentsfleet logs 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 @@ -172,11 +200,11 @@ agentsfleet logs 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --json | `--cursor ` | *(none)* | Pagination cursor returned as `next_cursor` in a previous response. | | `--json` | off | Emit the raw `{ items, next_cursor }` envelope. | -The agent ID may also be passed via `--agent ` for scripting symmetry with `events`. +The fleet ID may also be passed via `--fleet ` for scripting symmetry with `events`. -### `agentsfleet events ` — filtered history +### `agentsfleet events ` — filtered history -Richer filter surface than `logs`. Use this when you need to slice by actor or time window — for example, when [troubleshooting](/agents/troubleshooting) a specific webhook source. +Richer filter surface than `logs`. Use this when you need to slice by actor or time window — for example, when [troubleshooting](/fleets/troubleshooting) a specific webhook source. ```bash agentsfleet events 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --actor 'webhook:*' --since 2h @@ -194,7 +222,7 @@ agentsfleet events 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --json | jq 'select(.err There is no `--follow`/streaming-tail flag today. To watch live, poll `events --since 30s` from a script. -### `agentsfleet steer [message]` +### `agentsfleet steer [message]` Post a steer message — a manual trigger that uses the same reasoning loop as a webhook event. Useful for ad-hoc investigation or before a webhook is wired up. @@ -210,7 +238,7 @@ printf "check the latest deploy event\ncheck memory usage\n" | agentsfleet steer | `--tty` | *(auto on TTY)* | Force the interactive REPL even when stdin is piped — each line is a separate turn; exits at end-of-file. | | `--json` | off | Emit the steer result as JSON. | -When you invoke `agentsfleet steer ` from a terminal (TTY) and omit the message, `agentsfleet` opens a read-eval-print loop (REPL). Each submitted line posts one steer message, streams the reply, then returns to the prompt. Press `Ctrl-D` to exit cleanly, or `Ctrl-C` to cancel the active stream and exit. +When you invoke `agentsfleet steer ` from a terminal (TTY) and omit the message, `agentsfleet` opens a read-eval-print loop (REPL). Each submitted line posts one steer message, streams the reply, then returns to the prompt. Press `Ctrl-D` to exit cleanly, or `Ctrl-C` to cancel the active stream and exit. Explicit messages stay single-shot, even from a terminal. Piped input also stays single-shot by default so automation and agents can continue invoking the command once per turn. Add `--tty` to force the REPL over piped input; `agentsfleet` exits when the pipe reaches end-of-file. @@ -222,7 +250,7 @@ The reply streams back live; the result also persists to the activity stream for ### `agentsfleet credential add --data=@-` -Store a JSON-shaped secret in the current workspace vault. The agent references it by name from `TRIGGER.md`. +Store a JSON-shaped secret in the current workspace vault. The fleet references it by name from `TRIGGER.md`. Always pipe JSON on stdin via `--data=@-`. Never pass it inline as `--data='{...}'` — that puts the secret in shell history and process argv: @@ -234,7 +262,7 @@ JSON Default behaviour is skip-if-exists. Use `--force` to overwrite for rotation. -See [Workspace credentials](/agents/credentials) for the full vault model. +See [Workspace credentials](/fleets/credentials) for the full vault model. ### `agentsfleet credential show ` @@ -242,7 +270,7 @@ Print metadata (created, last-rotated). **Values are never returned.** ### `agentsfleet credential delete ` -Remove a credential from the workspace vault. Any agent still referencing it will fail with `UZ-AGT-003` (credential missing) on the next event until you re-add it (or update `TRIGGER.md`). See [Error codes](/api-reference/error-codes). +Remove a credential from the workspace vault. Any fleet still referencing it will fail with `UZ-AGT-003` (credential missing) on the next event until you re-add it (or update `TRIGGER.md`). See [Error codes](/api-reference/error-codes). ### `agentsfleet credential list` @@ -297,7 +325,7 @@ Prints the workspace's `workspace_id`, `name`, `created_at`, and active marker. ### `agentsfleet workspace delete ` -Delete a workspace and everything in it. Stops accepting new events immediately, lets in-flight runs finish, retains run history for 30 days. Cannot be undone — recreating a workspace produces a fresh `workspace_id` and fresh `agent_id`s, so any upstream webhooks pointing at the old workspace's agents need to be re-wired. +Delete a workspace and everything in it. Stops accepting new events immediately, lets in-flight runs finish, retains run history for 30 days. Cannot be undone — recreating a workspace produces a fresh `workspace_id` and fresh `fleet_id`s, so any upstream webhooks pointing at the old workspace's fleets need to be re-wired. ```bash agentsfleet workspace delete 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 @@ -307,89 +335,89 @@ agentsfleet workspace delete 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 ## Memory -A read-only window into an agent's durable memory. There is no write verb — the tenant memory plane is read-only by architecture; agents write their own memory during runs. +A read-only window into a fleet's durable memory. There is no write verb — the tenant memory plane is read-only by architecture; fleets write their own memory during runs. ### `agentsfleet memory list` List memory entries newest-first. ```bash -agentsfleet memory list --agent 01900000-0000-7000-8000-000000000001 +agentsfleet memory list --fleet 01900000-0000-7000-8000-000000000001 ``` | Flag | Default | Purpose | |------|---------|---------| -| `--agent ` | *(active)* | Agent whose memory to read. | +| `--fleet ` | *(active)* | Fleet whose memory to read. | | `--category ` | *(all)* | Filter to a single memory category. | | `--limit ` | server default | Max entries to return (clamped to the server cap). | | `--workspace ` | *(active)* | Override the active workspace for this call. | ### `agentsfleet memory search ` -Substring-search keys and content across an agent's memory. +Substring-search keys and content across a fleet's memory. ```bash -agentsfleet memory search "deploy" --agent 01900000-0000-7000-8000-000000000001 +agentsfleet memory search "deploy" --fleet 01900000-0000-7000-8000-000000000001 ``` | Flag | Default | Purpose | |------|---------|---------| -| `--agent ` | *(active)* | Agent whose memory to search. | +| `--fleet ` | *(active)* | Fleet whose memory to search. | | `--limit ` | server default | Max entries to return (clamped to the server cap). | | `--workspace ` | *(active)* | Override the active workspace for this call. | --- -## External agents +## Fleet keys (external access) -External agents are API-key–authenticated callers (LangGraph, CrewAI, Composio, your own code) that drive a specific agent programmatically. +A **fleet key** is an API key that lets an external caller (LangGraph, CrewAI, Composio, your own code) drive a specific fleet programmatically. -### `agentsfleet agent-key add` +### `agentsfleet fleet-key add` -Mint an API key bound to one agent. +Mint an API key bound to one fleet. ```bash -agentsfleet agent-key add --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 --agent 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --name my-agent +agentsfleet fleet-key add --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 --fleet 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --name my-fleet ``` The raw key (`agt_a…`) is returned **once**; store it in your secret manager. -### `agentsfleet agent-key list` +### `agentsfleet fleet-key list` -List every external agent key in a workspace. +List every fleet key in a workspace. ```bash -agentsfleet agent-key list --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 +agentsfleet fleet-key list --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 ``` -### `agentsfleet agent-key delete ` +### `agentsfleet fleet-key delete ` -Revoke an external agent key. +Revoke a fleet key. ```bash -agentsfleet agent-key delete --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 0198a7b4-6e1a-7c93-b052-8f3d2a1e7c46 +agentsfleet fleet-key delete --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 0198a7b4-6e1a-7c93-b052-8f3d2a1e7c46 ``` --- ## Integration grants -Integration grants are per-agent permissions to reach a third-party service (Slack workspace, GitHub repo) that the agent requested interactively. +Integration grants are per-fleet permissions to reach a third-party service (Slack workspace, GitHub repo) that the fleet requested interactively. -### `agentsfleet grant list --agent ` +### `agentsfleet grant list --fleet ` -List pending and approved grants for an agent. +List pending and approved grants for a fleet. ```bash -agentsfleet grant list --agent 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 +agentsfleet grant list --fleet 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 ``` -### `agentsfleet grant delete --agent ` +### `agentsfleet grant delete --fleet ` -Revoke a granted integration. Further attempts by the agent to reach that integration fail with `UZ-GRANT-003`. +Revoke a granted integration. Further attempts by the fleet to reach that integration fail with `UZ-GRANT-003`. ```bash -agentsfleet grant delete --agent 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 0198a7b4-2b5c-7d18-8f63-4e9a1c7d3b20 +agentsfleet grant delete --fleet 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 0198a7b4-2b5c-7d18-8f63-4e9a1c7d3b20 ``` --- @@ -413,7 +441,7 @@ agentsfleet billing show --json | `--cursor ` | *(none)* | Pagination cursor from a previous response. | | `--json` | off | Emit raw JSON for scripting. | -For per-agent spend breakdowns, use `agentsfleet logs --json` and aggregate the `tokens` / `wall_ms` fields client-side. Top-ups and payment-method updates happen at [app.agentsfleet.net/billing](https://app.agentsfleet.net/billing). +For per-fleet spend breakdowns, use `agentsfleet logs --json` and aggregate the `tokens` / `wall_ms` fields client-side. Top-ups and payment-method updates happen at [app.agentsfleet.net/billing](https://app.agentsfleet.net/billing). --- diff --git a/cli/flags.mdx b/cli/flags.mdx index 48bdfe9..06121d9 100644 --- a/cli/flags.mdx +++ b/cli/flags.mdx @@ -29,7 +29,7 @@ When `--json` is enabled, error responses include structured error codes for pro { "error": { "code": "UZ-AGT-008", - "message": "Invalid agent config: TRIGGER.md config_json fails schema validation." + "message": "Invalid fleet config: TRIGGER.md config_json fails schema validation." } } ``` diff --git a/cli/install.mdx b/cli/install.mdx index 5712611..5b2aaee 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -25,7 +25,7 @@ description: "Install the agentsfleet CLI." -## Agent Skills +## Fleet Skills The `agentsfleet-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). Add the skills with one command: @@ -33,7 +33,7 @@ The `agentsfleet-install-platform-ops` skill is the guided install UX driven fro npx skills add agentsfleet/skills ``` -This symlinks the `/agentsfleet-*` slash commands from the public [`agentsfleet/skills`](https://github.com/agentsfleet/skills) repo into every supported host's skill directory it detects on your machine — invoke `/agentsfleet-install-platform-ops` in your agent and you're set. Pass `--host=` to target a single host instead of every detected one. +This symlinks the `/agentsfleet-*` slash commands from the public [`agentsfleet/skills`](https://github.com/agentsfleet/skills) repo into every supported host's skill directory it detects on your machine — invoke `/agentsfleet-install-platform-ops` in your agent and you’re set. Pass `--host=` to target a single host instead of every detected one. **No global install?** `curl -fsSL https://agentsfleet.dev | bash` installs `agentsfleet` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://agentsfleet.dev` without `| bash` to read it first. @@ -61,6 +61,6 @@ agentsfleet doctor |---|---| | `server_reachable` | `GET /healthz` against the configured API URL returns `{ "status": "ok" }` within 5s. | | `workspace_selected` | The local config has a `current_workspace_id`. Auto-populated by `agentsfleet login` from your signup-provisioned default workspace; can also be set or replaced by `agentsfleet workspace add` / `workspace use`. | -| `workspace_binding_valid` | The resolved auth token can read the selected workspace's agents — i.e. it is bound to the right tenant. Reports a failed check (rather than aborting) when no token is present. | +| `workspace_binding_valid` | The resolved auth token can read the selected workspace's fleets — i.e. it is bound to the right tenant. Reports a failed check (rather than aborting) when no token is present. | Pass `--json` for the structured `{ ok, api_url, checks: [...] }` envelope. Run it before any install — host-agent skills depend on this preflight. For the tenant's inference posture and free-trial window, use [`agentsfleet tenant provider show`](/cli/agentsfleet#tenant-provider). diff --git a/concepts.mdx b/concepts.mdx index a6642f9..1b14126 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -16,13 +16,13 @@ agentsfleet has four primary objects. Everything else is infrastructure. Your top-level billing and identity boundary. Created automatically on first Clerk sign-in. Carries your default Stripe customer — hosted execution is [free until July 31, 2026](https://agentsfleet.net/pricing). - A container for agents and credentials. One tenant can have many workspaces (team, project, environment). Billing and identity live at the tenant — a workspace is purely an organizational boundary. + A container for fleets and credentials. One tenant can have many workspaces (team, project, environment). Billing and identity live at the tenant — a workspace is purely an organizational boundary. - - A persistent, durable agent process scoped to one operational outcome. One agent has one `SKILL.md` + `TRIGGER.md`, a set of triggers (webhook, cron, steer), and a set of workspace credentials it uses but never sees raw bytes for. Lives inside a workspace; crashes and restarts are transparent — the platform survives them. + + A persistent, durable fleet process scoped to one operational outcome. One fleet has one `SKILL.md` + `TRIGGER.md`, a set of triggers (webhook, cron, steer), and a set of workspace credentials it uses but never sees raw bytes for. Lives inside a workspace; crashes and restarts are transparent — the platform survives them. - A named primitive the agent's agent can invoke — `http_request`, `memory_store`, `cron_add`. Tools are declared in `TRIGGER.md` and **enforced** by the runner sandbox; the agent literally cannot call a tool that isn't on the list. The companion file `SKILL.md` is **advisory** — natural-language prose the model reads as its system prompt to decide *when* to reach for which tool and what counts as "done." Enforcement comes from `TRIGGER.md`; behavior comes from `SKILL.md`. + A named primitive the fleet can invoke — `http_request`, `memory_store`, `cron_add`. Tools are declared in `TRIGGER.md` and **enforced** by the runner sandbox; the fleet literally cannot call a tool that isn't on the list. The companion file `SKILL.md` is **advisory** — natural-language prose the model reads as its system prompt to decide *when* to reach for which tool and what counts as "done." Enforcement comes from `TRIGGER.md`; behavior comes from `SKILL.md`. @@ -33,7 +33,7 @@ Tenant (billing + identity, provider: anthropic) │ ├── Workspace: "platform-ops" │ │ -│ ├── Agent: platform-ops (0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71) +│ ├── Fleet: platform-ops (0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71) │ │ ├── Tools: http_request, memory_store, cron_add │ │ └── Triggers: webhook (GitHub Actions), cron, steer │ │ @@ -41,7 +41,7 @@ Tenant (billing + identity, provider: anthropic) │ └── Workspace: "support" │ - └── Agent: ticket-triage (0198a7b3-1a4d-7b62-a3f9-5c8e2d1b7a04) + └── Fleet: ticket-triage (0198a7b3-1a4d-7b62-a3f9-5c8e2d1b7a04) ├── Tools: http_request, memory_store └── Triggers: webhook (Zendesk), steer ``` @@ -50,7 +50,7 @@ Tenant (billing + identity, provider: anthropic) Hosted execution — every event receipt and run — is **free until July 31, 2026**. No credit card to start. -**You bring your provider and model.** Pick the provider (Anthropic, OpenAI, Fireworks, Together, Groq, Moonshot), attach the key, and pay them directly — agentsfleet marks up zero on inference. The runner resolves your credential at the tool bridge, so the agent never sees the raw key. +**You bring your provider and model.** Pick the provider (Anthropic, OpenAI, Fireworks, Together, Groq, Moonshot), attach the key, and pay them directly — agentsfleet marks up zero on inference. The runner resolves your credential at the tool bridge, so the fleet never sees the raw key. For the metered rates that apply after the trial, see [pricing on agentsfleet.net](https://agentsfleet.net/pricing). @@ -67,39 +67,39 @@ flowchart LR Tool --> Done[run exits
diagnosis posts
state checkpointed] ``` -A trigger lands on the event stream. A run opens. The agent calls tools allow-listed by `TRIGGER.md`; each tool result lands in the model's context. The agent never sees raw secret bytes — placeholders substitute at the sandbox boundary. The run exits when the agent is done or hits a [context boundary](/concepts/context-lifecycle); state checkpoints, the next trigger picks up. +A trigger lands on the event stream. A run opens. The fleet calls tools allow-listed by `TRIGGER.md`; each tool result lands in the model's context. The fleet never sees raw secret bytes — placeholders substitute at the sandbox boundary. The run exits when the fleet is done or hits a [context boundary](/concepts/context-lifecycle); state checkpoints, the next trigger picks up. ## Core terminology - One end-to-end execution of the agent on one trigger: webhook arrives → agent reasons → tool calls → result. Most agents finish a run in a few seconds. See [How long does a run take?](/concepts/context-lifecycle). + One end-to-end execution of the fleet on one trigger: webhook arrives → fleet reasons → tool calls → result. Most fleets finish a run in a few seconds. See [How long does a run take?](/concepts/context-lifecycle). - What wakes an agent. Three sources, all feeding the same reasoning loop: + What wakes a fleet. Three sources, all feeding the same reasoning loop: - - **Webhook** — an external system (GitHub, Slack, your monitoring) POSTs to `https://api.agentsfleet.net/v1/webhooks/{agent_id}/{source}` (one URL per declared trigger source). - - **Cron** — the agent schedules its own future runs via the `cron_add` tool. - - **Steer** — a human invokes `agentsfleet steer "..."` for a manual run. + - **Webhook** — an external system (GitHub, Slack, your monitoring) POSTs to `https://api.agentsfleet.net/v1/webhooks/{fleet_id}/{source}` (one URL per declared trigger source). + - **Cron** — the fleet schedules its own future runs via the `cron_add` tool. + - **Steer** — a human invokes `agentsfleet steer "..."` for a manual run. `SKILL.md` decides what to do based on the event payload. - The named verbs an agent can invoke, declared in `TRIGGER.md`: + The named verbs a fleet can invoke, declared in `TRIGGER.md`: - `http_request` — outbound HTTP. Slack posts, GitHub calls, your provider — all go through this. - `memory_store` / `memory_recall` / `memory_list` / `memory_forget` — durable cross-event learning. See [Memory](/memory). - `cron_add` / `cron_list` / `cron_remove` — schedule future runs. - The agent can only call tools that are explicitly listed. A jailbroken agent cannot reach outside the list. + The fleet can only call tools that are explicitly listed. A jailbroken fleet cannot reach outside the list. - The boundary between your secrets and the model. Credentials are stored encrypted in the workspace vault; the model itself only sees `${secrets.NAME.FIELD}` placeholders. When the agent invokes a tool, the **tool bridge** substitutes the real secret value outside the sandbox, makes the outbound call, and returns the response — never the secret. A prompt-injection attack recovers only the placeholder string. See [Workspace credentials](/agents/credentials). + The boundary between your secrets and the model. Credentials are stored encrypted in the workspace vault; the model itself only sees `${secrets.NAME.FIELD}` placeholders. When the fleet invokes a tool, the **tool bridge** substitutes the real secret value outside the sandbox, makes the outbound call, and returns the response — never the secret. A prompt-injection attack recovers only the placeholder string. See [Workspace credentials](/fleets/credentials). - Dollar ceilings on hosted execution (the platform compute that runs your agent — separate from your model provider's bill) declared in `TRIGGER.md`. `daily_dollars` caps spend over a rolling 24-hour window; `monthly_dollars` caps the calendar month. Hitting either ceiling stops new runs from opening. During the launch free trial (through July 31, 2026) hosted-execution runs are billed at **$0**, so a budget ceiling won't stop an agent for trial usage — these caps apply to the metered rate after the trial (see [pricing](https://agentsfleet.net/pricing)). Inference is on your model provider's bill, not on your agentsfleet invoice — your provider's own caps apply there. + Dollar ceilings on hosted execution (the platform compute that runs your fleet — separate from your model provider's bill) declared in `TRIGGER.md`. `daily_dollars` caps spend over a rolling 24-hour window; `monthly_dollars` caps the calendar month. Hitting either ceiling stops new runs from opening. During the launch free trial (through July 31, 2026) hosted-execution runs are billed at **$0**, so a budget ceiling won't stop a fleet for trial usage — these caps apply to the metered rate after the trial (see [pricing](https://agentsfleet.net/pricing)). Inference is on your model provider's bill, not on your agentsfleet invoice — your provider's own caps apply there. diff --git a/concepts/context-lifecycle.mdx b/concepts/context-lifecycle.mdx index 32cacfd..e81903e 100644 --- a/concepts/context-lifecycle.mdx +++ b/concepts/context-lifecycle.mdx @@ -3,23 +3,23 @@ title: "How long does a run take?" description: "When a run opens, when it stops, and the three knobs you'd ever tune." --- -A single trigger — a webhook, a cron fire, a `steer` message — opens one **run**. The agent reasons, calls tools, and the run closes when it's done or when it would otherwise overflow the model's context window. +A single trigger — a webhook, a cron fire, a `steer` message — opens one **run**. The fleet reasons, calls tools, and the run closes when it's done or when it would otherwise overflow the model's context window. -Most agents finish a run in seconds to a couple of minutes and never need any of the controls on this page. Read on if you have a long incident that issues dozens of tool calls and want to understand what stops it. +Most fleets finish a run in seconds to a couple of minutes and never need any of the controls on this page. Read on if you have a long incident that issues dozens of tool calls and want to understand what stops it. ## The three things that end a run | What | When it fires | What happens | |---|---|---| -| **Run finished** | Agent decides it's done | Run closes cleanly. Diagnosis posted, state checkpointed. | -| **Context full** | Prompt approaches the model's context cap | Agent ends the run with a checkpoint, the runtime opens a fresh run on the same chain, the new run `memory_recall`s where it left off. | +| **Run finished** | Fleet decides it's done | Run closes cleanly. Diagnosis posted, state checkpointed. | +| **Context full** | Prompt approaches the model's context cap | Fleet ends the run with a checkpoint, the runtime opens a fresh run on the same chain, the new run `memory_recall`s where it left off. | | **Budget breach** | Daily or monthly dollar cap hit | Run terminates, `budget_breach` recorded. Future runs in the next billing window are unaffected. | ## Continuation chains — when one run isn't enough -If the agent can't finish in one run (a forty-tool-call incident on a 200K-token model, for example), it ends the current run with `exit_ok: false` and a `checkpoint_id`. The runtime re-enqueues the same event as a continuation; the next run opens with a fresh prompt and pulls the prior findings via `memory_recall(checkpoint_id)`. +If the fleet can't finish in one run (a forty-tool-call incident on a 200K-token model, for example), it ends the current run with `exit_ok: false` and a `checkpoint_id`. The runtime re-enqueues the same event as a continuation; the next run opens with a fresh prompt and pulls the prior findings via `memory_recall(checkpoint_id)`. -A chain caps at **10 continuations**. The 11th attempt is refused, the originating event is labelled `chunk_chain_escalate_human`, and an operator picks it up. The agent itself stays alive — only that one chain forfeits. +A chain caps at **10 continuations**. The 11th attempt is refused, the originating event is labelled `chunk_chain_escalate_human`, and an operator picks it up. The fleet itself stays alive — only that one chain forfeits. ## Knobs you can tune @@ -27,28 +27,28 @@ Set these under `x-agentsfleet.context` in `TRIGGER.md`. Defaults work for almos | Knob | Default | When to touch it | |---|---|---| -| `tool_window` | 20 | Raise if your agent routinely runs 30+ tool calls and you want fewer continuations. Lower if you want it to compact its findings sooner. | -| `memory_checkpoint_every` | 5 | Cadence at which the agent is prompted to write a memory snapshot during a long run. Rarely worth changing. | +| `tool_window` | 20 | Raise if your fleet routinely runs 30+ tool calls and you want fewer continuations. Lower if you want it to compact its findings sooner. | +| `memory_checkpoint_every` | 5 | Cadence at which the fleet is prompted to write a memory snapshot during a long run. Rarely worth changing. | | `context_cap_tokens` | model-dependent | Set explicitly if your model has no published context cap or differs from the default. | If you've never seen a `chunk_chain_escalate_human` failure label, you don't need to change any of these. ## Common questions -**My agent ran for two minutes — is that normal?** +**My fleet ran for two minutes — is that normal?** Yes. Runs can be seconds (a single webhook → Slack post) to a few minutes (a multi-step diagnosis). What matters is that the run closes cleanly, not how long it took. **Will it run forever?** -No. Three independent ceilings stop it: the run's own context cap (the agent voluntarily ends and continues), the continuation cap (10 chunks max), and the budget cap (`daily_dollars` / `monthly_dollars` in `TRIGGER.md`). +No. Three independent ceilings stop it: the run's own context cap (the fleet voluntarily ends and continues), the continuation cap (10 chunks max), and the budget cap (`daily_dollars` / `monthly_dollars` in `TRIGGER.md`). **Do I need to tune anything?** -Almost certainly not. The defaults are tuned for the flagship `platform-ops` agent and translate well to most workloads. Tune your `SKILL.md` prose first — it's where the actual reasoning lives. +Almost certainly not. The defaults are tuned for the flagship `platform-ops` fleet and translate well to most workloads. Tune your `SKILL.md` prose first — it's where the actual reasoning lives. ## See also -- [Memory](/memory) — the API the agent uses to checkpoint findings during a long run. +- [Memory](/memory) — the API the fleet uses to checkpoint findings during a long run. - [Budgets](/billing/budgets) — `daily_dollars` and `monthly_dollars` ceilings. -- [Authoring an agent](/agents/authoring) — the full `TRIGGER.md` reference. +- [Authoring a fleet](/fleets/authoring) — the full `TRIGGER.md` reference. diff --git a/docs.json b/docs.json index 67fb673..5b72c5c 100644 --- a/docs.json +++ b/docs.json @@ -30,6 +30,9 @@ } }, "favicon": "/favicon.svg", + "redirects": [ + { "source": "/agents/:slug", "destination": "/fleets/:slug" } + ], "navigation": { "tabs": [ { @@ -46,17 +49,17 @@ ] }, { - "group": "Agents", + "group": "Fleets", "pages": [ - "agents/overview", - "agents/install", - "agents/running", - "agents/credentials", - "agents/webhooks", - "agents/authoring", - "agents/tools", - "agents/templates", - "agents/troubleshooting" + "fleets/overview", + "fleets/install", + "fleets/running", + "fleets/credentials", + "fleets/webhooks", + "fleets/authoring", + "fleets/tools", + "fleets/templates", + "fleets/troubleshooting" ] }, { @@ -156,9 +159,9 @@ "group": "Fleet", "pages": [ "POST /v1/runners", - "GET /v1/fleet/runners", - "PATCH /v1/fleet/runners/{id}", - "GET /v1/fleet/runners/{id}/events" + "GET /v1/fleets/runners", + "PATCH /v1/fleets/runners/{id}", + "GET /v1/fleets/runners/{id}/events" ] }, { @@ -175,11 +178,11 @@ ] }, { - "group": "Agent keys", + "group": "Fleet keys", "pages": [ - "GET /v1/workspaces/{workspace_id}/agent-keys", - "POST /v1/workspaces/{workspace_id}/agent-keys", - "DELETE /v1/workspaces/{workspace_id}/agent-keys/{agent_key_id}" + "GET /v1/workspaces/{workspace_id}/fleet-keys", + "POST /v1/workspaces/{workspace_id}/fleet-keys", + "DELETE /v1/workspaces/{workspace_id}/fleet-keys/{fleet_key_id}" ] }, { @@ -200,49 +203,57 @@ ] }, { - "group": "Agents", + "group": "Fleets", "pages": [ - "GET /v1/workspaces/{workspace_id}/agents", - "POST /v1/workspaces/{workspace_id}/agents", - "PATCH /v1/workspaces/{workspace_id}/agents/{agent_id}", - "DELETE /v1/workspaces/{workspace_id}/agents/{agent_id}" + "GET /v1/workspaces/{workspace_id}/fleets", + "POST /v1/workspaces/{workspace_id}/fleets", + "PATCH /v1/workspaces/{workspace_id}/fleets/{fleet_id}", + "DELETE /v1/workspaces/{workspace_id}/fleets/{fleet_id}" ] }, { - "group": "Agent messages", + "group": "Fleet bundles", "pages": [ - "POST /v1/workspaces/{workspace_id}/agents/{agent_id}/messages" + "GET /v1/fleets/bundles", + "POST /v1/workspaces/{workspace_id}/fleets/bundles/snapshots", + "GET /v1/workspaces/{workspace_id}/fleets/bundles/snapshots/{bundle_id}" ] }, { - "group": "Agent memories", + "group": "Fleet messages", "pages": [ - "GET /v1/workspaces/{workspace_id}/agents/{agent_id}/memories" + "POST /v1/workspaces/{workspace_id}/fleets/{fleet_id}/messages" ] }, { - "group": "Agent events", + "group": "Fleet memories", "pages": [ - "GET /v1/workspaces/{workspace_id}/agents/{agent_id}/events", - "GET /v1/workspaces/{workspace_id}/agents/{agent_id}/events/stream" + "GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/memories" + ] + }, + { + "group": "Fleet events", + "pages": [ + "GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/events", + "GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/events/stream" ] }, { "group": "Integration grants", "pages": [ - "GET /v1/workspaces/{workspace_id}/agents/{agent_id}/integration-grants", - "POST /v1/workspaces/{workspace_id}/agents/{agent_id}/integration-requests", - "DELETE /v1/workspaces/{workspace_id}/agents/{agent_id}/integration-grants/{grant_id}" + "GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-grants", + "POST /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-requests", + "DELETE /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-grants/{grant_id}" ] }, { "group": "Webhooks", "pages": [ - "POST /v1/webhooks/svix/{agent_id}", - "POST /v1/webhooks/{agent_id}", - "POST /v1/webhooks/{agent_id}/approval", - "POST /v1/webhooks/{agent_id}/github", - "POST /v1/webhooks/{agent_id}/grant-approval" + "POST /v1/webhooks/svix/{fleet_id}", + "POST /v1/webhooks/{fleet_id}", + "POST /v1/webhooks/{fleet_id}/approval", + "POST /v1/webhooks/{fleet_id}/github", + "POST /v1/webhooks/{fleet_id}/grant-approval" ] }, { diff --git a/agents/authoring.mdx b/fleets/authoring.mdx similarity index 77% rename from agents/authoring.mdx rename to fleets/authoring.mdx index 420b999..6a4e187 100644 --- a/agents/authoring.mdx +++ b/fleets/authoring.mdx @@ -1,29 +1,29 @@ --- -title: "Authoring an agent" -description: "The `SKILL.md` and `TRIGGER.md` file pair — how an agent is defined end-to-end." +title: "Authoring a fleet" +description: "The `SKILL.md` and `TRIGGER.md` file pair — how a fleet is defined end-to-end." --- ## Overview -An agent is two files: a **`SKILL.md`** that tells the agent who it is and what to do, and a **`TRIGGER.md`** that tells the platform how the agent connects to the world. Nothing else is needed — no Dockerfile, no deployment YAML, no server code. +A fleet is two files: a **`SKILL.md`** that tells the fleet who it is and what to do, and a **`TRIGGER.md`** that tells the platform how the fleet connects to the world. Nothing else is needed — no Dockerfile, no deployment YAML, no server code. ``` -my-agent/ -├── SKILL.md # agent instructions (natural language) +my-fleet/ +├── SKILL.md # fleet instructions (natural language) └── TRIGGER.md # machine-readable config + deployment metadata ``` `agentsfleet install