automagent validate

Validate an agent.yaml against the schema and run safety checks

Usage

$ automagent validate [file]

If no file is specified, the command looks for ./agent.yaml in the current directory.

The validation pipeline

Validation runs four checks in sequence. If any check produces an error, the command exits with code 1. Warnings do not cause a non-zero exit.

Step 1: Schema validation

The YAML file is parsed and validated against the Automagent v1 JSON Schema using Ajv. This catches:

Missing required fields (name, description, model)
Invalid field types (e.g., model is a number instead of a string or object)
Pattern violations (e.g., name contains uppercase letters or spaces)
YAML syntax errors (with line numbers)

✗ Schema validation failed
  - must have required property 'description'
  - /name must match pattern "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"

Step 2: Model check

Warns if the model field uses an unpinned alias instead of a versioned identifier. Unpinned aliases can change behavior unexpectedly when providers update their models.

⚠ Model "claude-sonnet" is an unpinned alias. Consider using a pinned version like "claude-sonnet-4-20250514".

This is a warning, not an error. Your file still passes validation.

Step 3: Secret detection

Scans all string values in the YAML for patterns that look like API keys or credentials:

Strings starting with sk-, key-, or AKIA
High-entropy base64-encoded strings that are likely secrets

✗ Potential secret detected in field "instructions": value matches API key pattern (sk-...)

This is an error. Secrets should never be committed in agent definitions. Use environment variables instead.

Step 4: Context file check

If your agent.yaml includes a context array with file references, the validator checks that each referenced file exists on disk.

context:
  - file: ./docs/product-guide.md
  - file: ./data/faq.csv

⚠ Context file not found: ./data/faq.csv

This is a warning. The file might exist in a different environment (e.g., CI) where the agent runs.

Exit codes

Code	Meaning
`0`	Valid. No errors found (warnings are OK).
`1`	Invalid. Schema errors, YAML parse failures, or secrets detected.

Examples

Validate the default file:

$ automagent validate
✔ Schema valid
✔ Model check passed
✔ No secrets detected
✔ Context files OK

agent.yaml is valid

Validate a specific file:

$ automagent validate agents/researcher.yaml

Validation with warnings:

$ automagent validate
✔ Schema valid
⚠ Model "gpt-4" is an unpinned alias
✔ No secrets detected
⚠ Context file not found: ./data/knowledge-base.md

agent.yaml is valid (2 warnings)

Validation with errors:

$ automagent validate
✗ Schema validation failed
  - must have required property 'model'