agents.yaml reference

Declare which production agents depend on which watches, which drift policy applies, and where runtime blocks propagate — version-controlled beside your agent code.

Status: Manifest format is stable for console and API bindings. Hosted ingest from Git and CI lint action ship in CP-2.1 — use console bindings today.

File location

Commit at repository root:

.driftguard/agents.yaml

One file per repo is typical. Organizations with multiple services may use one manifest per deployable agent repo; the console merges bindings by org.

Full example

version: 1
org: acme-corp

agents:
  - id: billing-refund-v3
    name: Billing refund assistant
    environment: production
    policy: production-guard
    watches:
      - stripe-refunds-mcp
      - internal-openapi-users
    runtime_webhook: https://api.acme.test/agents/billing-refund-v3/contract

policies:
  production-guard:
    on_breaking: kill_in_flight
    on_warning: notify
    require_ack_to_unblock: true
    auto_resolve_incident: true

Top-level fields

Field	Required	Description
`version`	Yes	Manifest schema version. Use `1`.
`org`	No	Organization slug hint for multi-org users. Console bindings are authoritative.
`agents`	Yes	Array of agent binding declarations.
`policies`	No	Inline policy overrides. Prefer named presets from drift policy presets.

Agent entry fields

Field	Required	Description
`id`	Yes	Stable agent identifier — used by `GET /api/agents/:id/status` and preflight `agentId`.
`name`	No	Human label in console fleet and alerts.
`environment`	Yes	`production`, `staging`, or `development` — affects remediation severity mapping.
`policy`	Yes	Policy preset name or inline policy key from `policies` block.
`watches`	Yes	Watch slugs or IDs this agent depends on. Must resolve to registered watches.
`runtime_webhook`	No	HTTPS URL for signed `agent.contract.blocked` events when policy blocks in-flight runs.
`repoRef`	No	Repository reference (`org/repo@branch`) for remediation approval rules.

CI validation

Shipped in OSS drift-agents-lint (CP-2.1) — offline schema checks, no API key:

Required fields and enum validation for version, agents[], policies
Policy preset names or inline policy definitions
runtime_webhook must be HTTPS (SSRF policy alignment)
Watch entries require type + url (see example manifest)

- uses: Drift-Guard/driftguard/.github/actions/drift-agents-lint@v0.3.3
  with:
    manifest: .driftguard/agents.yaml

Local equivalent: driftguard lint-agents .driftguard/agents.yaml. Hosted watch slug resolution in CI remains roadmap — mirror bindings in ConsoleFleetBindings until ingest lands.

Console sync

Bindings created in console write the same fields to hosted agent_bindings. Treat agents.yaml as the source of truth in Git; console is the operational view until ingest lands.