Agent capabilities
An agent capability is a bounded build step. It has a versioned prompt, a tool allowlist, a validator, and a retry budget. The agent proposes; the validator decides. A failed validator stops the step and keeps the evidence. It does not retry with a new assumption.
The committed registry is brushline.capabilities.v1. The six core capabilities are:
Capability |
Prompt |
Tools |
Validator |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Every capability has a prompt version, a description, a non-empty tool allowlist, a registered validator, and a retry budget from 0 to 2. A capability with no validator is rejected by the registry validator and stops before a provider call.
Tools
The tool registry describes what each allowlisted tool does and whether it mutates. The current tools are read-only metadata, compiler, state, scenario, and demo steps. None reads a private row. A private tool cannot be allowlisted.
A tool call in a provider response must be allowlisted and must end with status ok. An unknown
tool, a blocked tool, or an errored tool stops the capability with AGENT-TOOL.
Harness flow
run_capability follows a fixed order:
Build the request with a canonical input hash and the capability prompt.
Reject a private-data marker in the prompt before calling the provider.
Call the provider. A provider exception may retry up to the capability budget.
Reject an unknown, blocked, or errored tool call.
Reject a private-data marker in the outcome.
Reject an agent-authored
authoritative,coefficient,geometry, orvalidation_resultfield.Run the capability validator.
Record a sanitized outcome.
A validator failure is final. It does not consume the provider retry budget. A provider exception can retry, but the record contains only the exception type, never the exception message.
Prompt and input
build_agent_request hashes a canonical JSON form of the input. The request carries the prompt id,
prompt version, input hash, and tool allowlist. The default prompt tells the provider not to compute or
assert an authoritative number, coefficient, geometry, or validation result, and not to include
private rows or confidential values.
A caller can supply a prompt override for a test, but the harness still scans it. A private-data marker in the prompt stops the run before the provider is called.
Outcome record
CapabilityOutcome is the sanitized evidence record. It has:
capability id and prompt id;
input SHA-256 and outcome SHA-256;
validator id and the shared validator report;
sanitized tool calls;
final state (
succeeded,stopped, orfailed);attempts, retry budget, stop reason, and creation time.
The record does not contain the prompt, a raw private row, or the unhashed outcome. A private marker in a tool summary fails the record validator.
from datetime import UTC, datetime
from brushline.integrations.capabilities import (
AgentResponse,
FakeAgentProvider,
default_capability_registry,
run_capability,
validate_capability_outcome,
)
capability = default_capability_registry().capabilities[0]
provider = FakeAgentProvider(
{
"select_aoi": [
AgentResponse(
outcome={
"aoi_path": "aoi.geojson",
"feature_count": 1,
"source_sha256": "a" * 64,
}
)
]
}
)
result = run_capability(
capability,
{"aoi": "aoi.geojson"},
provider,
created_utc=datetime(2026, 11, 14, tzinfo=UTC),
)
assert result.final_state == "succeeded"
assert validate_capability_outcome(result).is_valid
Validators
The built-in validators are intentionally narrow:
aoi_outcomechecks the AOI path, a positive feature count, and the source hash.fetch_plan_outcomeparses the P2.5 plan and runsvalidate_fetch_plan.state_outcomeparses the P2.3 state contract and runsvalidate_state_contract.dataset_outcomeparses the dataset manifest and requires a dataset path.scenario_outcomechecks the scenario and targets schema versions and the target list.demo_outcomeparses the demo manifest and runsvalidate_demo_manifest.
The agent does not produce the authoritative number, coefficient, geometry, or validation result. The validator sees the outcome and decides. A capability cannot silently skip a failing validator.
Named errors
Prefix |
Meaning |
|---|---|
|
Registry problems: missing capability, prompt, tool, validator, private tool, retry budget, or empty registry. |
|
A private-data marker was found in a prompt, outcome, tool summary, or record. |
|
An outcome contains a forbidden authoritative field. |
|
A tool is not allowlisted, has an unknown status, or did not finish |
|
The provider failed after the bounded retry budget. |
|
The capability has no registered validator, or the outcome validator failed. |
|
The sanitized record has a bad state, hash, attempt count, evidence, or time. |
What this page does not promise
It does not add a live model-provider integration. The tests use a fake provider.
It does not approve a connector, fetch data, or bypass an owner gate.
It does not make an agent-produced geometry, coefficient, number, or validation result authoritative.
It does not turn a private row into prompt text, a tool summary, or an outcome record.