agentcli blueprint

Lint and validate blueprint YAML files against the platform’s Pydantic schemas. Auto-detects whether the file is an agent, strategy, or workflow blueprint and runs the appropriate validation.

Synopsis

agentcli blueprint <subcommand> [OPTIONS] YAML_PATH

Subcommands

Subcommand	Description
`lint`	Validate a blueprint YAML file and display a coverage report
`validate`	Alias for `lint`

agentcli blueprint lint

agentcli blueprint lint YAML_PATH

Validates the file against the appropriate Pydantic model (AgentBlueprint, StrategyBlueprint, or WorkflowBlueprint), then runs cross-block validation to catch configuration inconsistencies. Exits with code 1 on failure, 0 on success.

Arguments

Argument	Description
`YAML_PATH`	Path to the blueprint YAML file to validate

Output

For agent blueprints, lint prints a block coverage tree showing which subsystems are configured:

my-agent.yaml (agent blueprint)
+-- Name: my-agent
+-- Version: 1.0.0
+-- Model
|   +-- provider: bedrock
|   +-- model_id: eu.anthropic.claude-sonnet-4-6
+-- Block Coverage
    +-- runtime
    +-- gateway
    +-- identity  —
    +-- memory
    +-- tools  —
    +-- observability
    +-- evaluation  —
    +-- policy  —
    +-- multi_agent  —

PASS — Blueprint is valid.

A check mark indicates the block is configured; a dash indicates it is absent (not an error).

Cross-Block Warnings

After schema validation, lint checks for configuration inconsistencies:

Warning	Cause
`Policy rules declared but no gateway configured`	`policy.rules` defined but no `gateway` block
`Memory strategies require runtime.type: agentcore`	Memory strategies set but runtime type is not `agentcore`
`Coordinator role declared but no multi_agent.nodes defined`	Coordinator pattern declared without nodes
`Online evaluation configured but no observability block`	`evaluation.online` enabled without observability (evaluation reads OTEL traces)

Examples

Validate an agent blueprint

agentcli blueprint lint agents/my-agent.yaml

Validate a strategy blueprint

agentcli blueprint lint strategies/extraction-strategy.yaml

Strategy blueprints are auto-detected by the presence of required_signals, entry_conditions, or exit_conditions fields.

Validate a workflow blueprint

agentcli blueprint lint workflows/document-pipeline.yaml

Workflow blueprints are auto-detected by the presence of a states field.

Use in CI

agentcli blueprint lint agents/my-agent.yaml && echo "Blueprint OK"
# Exit code 1 on validation failure — safe to use in CI pipelines

Validate all blueprints in a directory

for f in agents/*.yaml; do agentcli blueprint lint "$f"; done

Blueprint Types and Required Fields

Agent Blueprint

Required fields: id, name, version, model (with model_id, temperature, and max_tokens), and prompt_ref. All other blocks (runtime, gateway, memory, etc.) have defaults and are optional.

id: my-agent
name: My Agent
version: 1.0.0
prompt_ref: my-agent-system          # required; Prompt Registry key
model:
  provider: bedrock                  # optional — defaults to bedrock
  model_id: ${MODEL_ID}             # required; supports ${VAR:-default} expansion
  temperature: 0.3                   # required
  max_tokens: 4096                   # required

Strategy Blueprint

Required fields: id, name, version. All other fields (required_agents, required_signals, entry_conditions, exit_conditions, etc.) are optional. Detected by the presence of required_signals, entry_conditions, or exit_conditions.

Workflow Blueprint

Required fields: id, name, version. The states field defaults to an empty list and is optional in the schema — though a workflow without states is a no-op. Detected by the presence of a states field.