agent.yaml Reference
Developer Reference
This page covers internal implementation details. It is not included in the User Guide.
agent.yaml is the single source of truth authored by domain teams. The ADK reads it, validates it, splits it, and places each section into the correct Context Engine collection. The Platform Framework never reads this file directly.
Spec ↔ implementation drift
This page documents the v4 architecture spec (v4-architecture-docs/agents.yaml.md). The shipped ADK in v4-adk does not yet implement every spec field — see v4-adk/GAPS.md for the current list (notable: tool_ids on the skill manifest model, tenant_id on the agent manifest, the readonly tool-class allowlist for iam_read / audit_read). For a working example as it currently registers, read v4-adk/iam-security-agent/agent.yaml.
The ADK placement map below also references CE endpoints (e.g. /resolve/playbook, /resolve/template, /resolve/guardrails, /resolve/context, /resolve/domain_knowledge) that are not yet implemented in the running CE API. Per context_engine_api.py, only /resolve/skill, /resolve/agent, /resolve/tools, /resolve/tool_class, /resolve/context_builders are live. See Context Engine API for the implementation status.
author once → agent.yaml
split once → ADK
store once → Context Engine
serve always → Platform FrameworkADK placement map
| Section | ADK places into | CE API that serves it |
|---|---|---|
| Identity + Classification | Agent Registry | /resolve/agent |
| Capabilities | Agent Registry (dense vector embeddings) | /resolve/agent — Phase 2C miss only |
| Skills | Skill collection per skill.yaml | Phase 2C search + /resolve/skill |
| Playbooks | Playbook collection per playbook.yaml | /resolve/playbook |
| Context | Context Builder collection per context_builder.yaml | /resolve/context |
| Tool Access (readonly) | Tool collection + ADK Graph | /resolve/context |
| Tool Access (write) | Tool collection + ADK Graph | /resolve/playbook |
| Domain Knowledge (lens) | Domain Lens collection | /resolve/domain_knowledge |
| Domain Knowledge (graph) | Domain Expert Graph | /resolve/domain_knowledge |
| Artifacts | Agent Registry + ADK Graph | /resolve/skill |
| Policy | Guardrail collection | /resolve/guardrails |
| Composition | ADK Graph + Composition Registry | /resolve/agent |
| Versioning | Agent Registry | /resolve/agent |
Full annotated example — Security Exposure Agent
yaml
# ── Section 1: Identity ────────────────────────────────────────────────────────
schema_version: 1
agent_id: domain.security.exposure # globally unique — format: domain.{domain}.{name}
name: exposure # kebab-case internal name
display_name: Security Exposure Agent # user-facing name
agent_type: domain # platform | domain
# platform: reserved for Escher core team
status: active # active | deprecated
owner:
team: security-intelligence
contact: security-intelligence@company
purpose: >
Detect and rank network exposure, public storage access, and ingress risks
across AWS and Azure.
description: >
Security agent covering public ingress analysis, open storage detection,
and exposure risk ranking across AWS security groups, S3 buckets, Azure NSGs,
and Azure Blob containers. Produces ranked findings with remediation guidance.
tenant_id: null # agents are always global — never tenant-scoped
# ── Section 2: Classification ──────────────────────────────────────────────────
classification:
domain: security # must exist in Domain Registry at registration
product_scope: horizontal # horizontal (all customers) | vertical (specific)
tier_support: [basic, advanced] # basic | advanced
# advanced adds DomainLens + ExpertGraph
# ── Section 3: Capabilities ────────────────────────────────────────────────────
# Natural language statements — ADK embeds as dense vectors into Agent Registry.
# Used by /resolve/agent for Code Agent grounding (Phase 2C miss path only).
# More specific = better routing accuracy.
capabilities:
- detect public ingress and network exposure risks across AWS and Azure
- detect public storage access including open S3 buckets and Azure Blob containers
- rank and prioritize exposure findings by severity and blast radius
- suggest remediation paths for network exposure findings
# ── Section 4: Skills ──────────────────────────────────────────────────────────
# Skills are read-only. ADK validation fails if any skill references a write tool.
skills:
exported_skill_ids: # available to Phase 2C routing + /resolve/skill
- security.detect_public_ingress
- security.detect_public_storage_access
- security.rank_basic_exposure_findings
hidden_skill_ids: [] # registered but only callable via direct Mode 2 call
# ── Section 5: Playbooks ───────────────────────────────────────────────────────
# Write-capable procedures. Always require human approval before execution.
playbooks:
can_trigger: true # can this agent initiate playbook execution?
can_generate_candidate: true # can Code Agent generate a playbook dynamically?
owned_playbook_ids:
- security.remediate_public_exposure
- security.lock_public_storage
# G-06 — read-before-write context block
# Data the playbook needs before executing write tools
context:
context_descriptions:
- "security group ingress rules before write execution"
- "public exposure inventory — resources targeted for remediation"
supported_context_types:
- public_exposure_inventory
- security_group_config
declared_context_builders:
- security.public_exposure_context
target_language: python # python | bash | terraform
# ── Section 6: Context ─────────────────────────────────────────────────────────
# What data this agent's skills need. Context builders drive CE /resolve/context.
context:
context_descriptions:
- "network exposure inventory — public ingress rules and open ports"
- "public storage access — S3 and Blob containers with public ACLs"
- "resource scope summary — accounts and regions in scope"
supported_context_types:
- public_exposure_inventory # scopes client estate RAG query
- public_storage_inventory
- resource_scope_summary
- account_scope # estate-injected — always available, no fetch step
- environment_scope # estate-injected — always available, no fetch step
declared_context_builders:
- security.public_exposure_context # drives /resolve/context
- security.public_storage_context
# ── Section 7: Tool access ─────────────────────────────────────────────────────
tool_access:
readonly_tools:
allowed_tool_classes:
- network_read # must exist in Tool collection at registration
- storage_read
- inventory_read
preferred_tool_tags:
- aws
- azure
- security
- network
execution_locations: [client] # client | server
# client: Tauri plugin on user's machine
# server: server-side tool execution
# ── Section 8: Artifacts ───────────────────────────────────────────────────────
artifacts:
can_read: [finding, report] # artifact types this agent can read
can_create: [finding, exposure_report] # artifact types this agent can create
can_update: [] # artifact types this agent can update
can_enrich: [triage] # artifact types this agent can annotate
# ── Section 9: Domain Knowledge ───────────────────────────────────────────────
# Advanced tier only. Omit entirely for basic-tier agents.
domain_knowledge:
lens:
- id: security.exposure_principles
description: >
Principles for ranking and reasoning about network exposure risk,
blast radius estimation, and remediation prioritization.
source_url: internal://security/exposure-principles-v2.md
graph:
- id: security.cve_control_graph
description: CVE-to-control relationship graph for exposure risk ranking
# relationships between CVEs, affected resource types, and remediation controls
# ── Section 10: Policy (Guardrails) ───────────────────────────────────────────
policy:
safety_class: advisory # skills produce findings only — no mutations
requires_human_review_for: [] # applies to skills; playbooks always require review
prohibited_actions:
- delete_resource
- modify_iam_policy
- create_security_group
# ── Section 11: Composition ────────────────────────────────────────────────────
# How this agent composes with others. Used by the Composition Registry.
composition:
persona_membership:
- hero_admin # included in the Hero Admin profile
- security_operator
depends_on_agents:
- domain.finops.cost # can correlate with cost findings
compatible_with:
- domain.compliance.audit # findings can contribute to compliance reports
# ── Section 12: Versioning ─────────────────────────────────────────────────────
versioning:
version: "1.2.0"
changelog: "Added Azure Blob public access detection, updated exposure ranking"
deprecated_skill_ids: []Validation rules
| Rule | Scope | Description |
|---|---|---|
agent_id globally unique | Identity | Duplicate IDs are rejected at registration |
agent_type: platform reserved | Identity | Only Escher core team may register platform agents |
tenant_id: null always | Identity | Agents are always global — never tenant-scoped |
| Domain exists in Domain Registry | Classification | domain value must be pre-registered |
| Skills are read-only | Skills | ADK fails if any skill references a write_tool_class |
can_request_execution: false | Skills | All skills must declare this in action_semantics |
| Each skill_id has a skill.yaml | Skills | Missing skill file = validation failure |
| Each playbook_id has a playbook.yaml | Playbooks | Missing playbook file = validation failure |
| Tool classes exist at registration | Tools | All allowed_tool_classes must be in Tool collection |
| Context builders exist at registration | Context | All declared_context_builders must be in CB collection |
skill.yaml — required fields
Each skill referenced in exported_skill_ids or hidden_skill_ids needs a skill.yaml:
yaml
schema_version: 1
skill_id: security.detect_public_ingress # must match agent.yaml reference
display_name: Detect Public Ingress
status: active # active | deprecated
purpose: > # platform-facing — used in skill embedding
Detect unrestricted public ingress rules across AWS security groups and Azure NSGs.
description: > # user-facing — example prompts and resource types
Scans security groups and NSGs for ingress rules permitting 0.0.0.0/0 or ::/0
on any port. Returns a ranked list of affected resources with port, protocol,
and account context. Works on AWS (EC2 security groups) and Azure (NSGs).
capabilities: # natural language — used in skill embedding
- detect unrestricted inbound access on security groups
- identify open ports accessible from the internet
- rank exposure findings by affected resource count and port sensitivity
context_descriptions: # natural language — what data this skill needs
- "security group ingress rules across enabled AWS profiles"
- "Azure NSG inbound rules across enabled subscriptions"
output_type: finding # finding | report | triage | audit_event_report | closure_summary
output_schema_ref: schemas/finding_v1.json
client_action_type: security-scan-ingress # kebab-case — dispatches Tauri action on client
# required for execution_locations: [client]
tool_ids: # explicit — each must exist in Tool collection
- aws.ec2.describe_security_groups
- azure.network.list_network_security_groups
action_semantics:
can_request_execution: false # hard requirement — skills never trigger execution
can_generate_plan_fragments: true # this skill's output can feed into a Plan
can_generate_bundle_hints: false
can_generate_playbook_candidates: true # Code Agent may propose a playbook from this finding
execution_plan:
steps:
- step_id: fetch_aws_sgs
context_type: aws_security_group_config
tool_class: network_read
depends_on: [] # starts immediately
required: true
on_failure: skip # if AWS scan fails, continue with Azure data
- step_id: fetch_azure_nsgs
context_type: azure_nsg_config
tool_class: network_read
depends_on: [] # parallel with fetch_aws_sgs
required: false
on_failure: skip
- step_id: fetch_resource_scope
context_type: resource_scope_summary
tool_class: inventory_read
depends_on: [] # parallel — estate-injected, fast
required: false
on_failure: skip
on_partial_failure: continue # run even if some steps fail
versioning:
version: "1.1.0"ADK commands quick reference
bash
# Validate the agent package (offline, no CE calls)
adk validate .
# Register all assets into the Context Engine
adk register .
# Scaffold a new agent package interactively
adk scaffold --domain security --name my-new-agent
# Check registration status
adk status --agent-id domain.security.my-new-agentNext steps
- Authoring Workflow — The Author Agent conversation flow
- ADK Reference — Full CLI reference
- Context Engine API — What the ADK calls under the hood
- Writing Playbooks — The playbook.yaml schema