callable_agents.manifest vs agent.yaml in Managed-Agent Cookbooks: Understanding the Two-Tier Architecture

The root agent.yaml defines the orchestrator agent and declares delegable sub-agents via the callable_agents list, while each callable_agents.manifest reference points to a standalone YAML file that defines a leaf worker with no further delegation capabilities.

The anthropics/financial-services repository implements a strict two-tier architecture for managed-agent cookbooks, separating orchestration logic from specialized worker tasks. This design pattern requires clear distinctions between the main agent definition and its delegated sub-agent manifests to enforce the single-level delegation model used by the validation and runtime systems.

Understanding the Root agent.yaml

The agent.yaml file serves as the entry point for any managed-agent cookbook. Located at the top level of a cookbook directory (e.g., managed-agent-cookbooks/valuation-reviewer/agent.yaml), this file defines the orchestrator agent that receives initial requests and coordinates workflow execution.

Orchestrator Definition and Delegation List

The root configuration contains global settings including the agent name, model, system prompt configuration, and available tools. Crucially, it includes the callable_agents key—a top-level list that declares which sub-agents the orchestrator can invoke:

# managed-agent-cookbooks/valuation-reviewer/agent.yaml

name: valuation-reviewer
model: claude-opus-4-7
system:
  file: ./prompts/system.md
callable_agents:
  - { manifest: ./subagents/package-reader.yaml }
  - { manifest: ./subagents/valuation-runner.yaml }
  - { manifest: ./subagents/publisher.yaml }

Each entry in callable_agents specifies a relative path via the manifest key to a sub-agent definition file. According to the source code at valuation-reviewer/agent.yaml lines 25-28, these paths resolve relative to the agent.yaml file location.

Understanding callable_agents.manifest Files

Files referenced by the manifest key are complete, standalone agent definitions that configure specialized leaf workers. These files typically reside in the subagents/ directory and contain their own name, model, system instructions, and tool configurations specific to their delegated task.

Leaf Sub-Agent Specifications

Unlike the root agent.yaml, sub-agent manifests cannot declare further delegation. The research preview only supports single-level delegation, requiring leaf manifests to specify an empty callable_agents array:

# managed-agent-cookbooks/valuation-reviewer/subagents/publisher.yaml

name: valuation-publisher
model: claude-opus-4-7
system:
  text: |
    Write the final valuation report to a file.
tools:
  - type: agent_toolset_20260401
    configs:
      - { name: write, enabled: true }
callable_agents: []      # Leaf node—no further delegation permitted

output_schema:
  type: object
  required: [file_path]
  properties:
    file_path: {type: string}

As implemented in valuation-reviewer/subagents/publisher.yaml line 16, the empty callable_agents: [] explicitly marks this agent as a terminal worker in the delegation chain.

Critical Differences Between the Two File Types

• Purpose and Role: The root agent.yaml defines the orchestrator that manages workflow dispatch and maintains the delegation registry. A manifest file defines a specialized worker that executes discrete tasks without orchestration responsibilities.

• File Location: Root files exist at the cookbook top-level (<cookbook>/agent.yaml), while manifest files reside in subdirectories (<cookbook>/subagents/*.yaml) referenced by the manifest path.

• callable_agents Content: The root file contains a populated list of manifest references enabling delegation. Sub-agent manifests must contain an empty array [] to indicate they are leaf nodes.

• Validation Targets: The scripts/check.py validation tool verifies that root callable_agents.manifest paths resolve to existing files. For sub-agent manifests, validation ensures callable_agents is empty and that individual agent fields are properly configured.

Validation with scripts/check.py

The repository includes scripts/check.py to enforce the two-tier architecture constraints. The script specifically validates that every manifest entry in the root agent.yaml points to an existing file:

# scripts/check.py (validation excerpt)

for c in data.get("callable_agents") or []:
    if not (yml.parent / c["manifest"]).exists():
        err(f"ref: {rel(yml)}: callable_agents.manifest -> {c['manifest']} (not found)")

This validation runs during CI to prevent runtime failures caused by missing sub-agent definitions. If a referenced manifest file is missing, the error message explicitly identifies the broken reference path.

Code Examples

Root Orchestrator Configuration

This excerpt from agent.yaml shows the delegation structure for a valuation workflow:

name: valuation-reviewer
model: claude-opus-4-7
callable_agents:
  - { manifest: ./subagents/package-reader.yaml }
  - { manifest: ./subagents/valuation-runner.yaml }
  - { manifest: ./subagents/publisher.yaml }

Leaf Worker Manifest

This sub-agent specializes in file output operations and explicitly disables delegation:

name: valuation-publisher
model: claude-opus-4-7
system:
  text: |
    Write the final valuation report to a file.
tools:
  - type: agent_toolset_20260401
    configs:
      - { name: write, enabled: true }
callable_agents: []

Validation Error Handling

When scripts/check.py encounters an invalid manifest reference, it produces specific error output indicating the missing file path, preventing deployment of incomplete cookbook configurations.

Summary

• The root agent.yaml acts as the orchestrator entry point containing a callable_agents list that references sub-agent manifests by relative path.
• Sub-agent manifest files are complete agent definitions stored in subagents/ that perform specialized tasks but cannot delegate further.
• The single-level delegation constraint requires leaf manifests to declare callable_agents: [].
• Validation via scripts/check.py ensures all manifest references resolve to existing files and that sub-agents do not attempt nested delegation.
• This two-tier architecture separates workflow coordination from task execution in financial services managed-agent cookbooks.

Frequently Asked Questions

Can a sub-agent manifest declare its own callable_agents?

No. As implemented in the anthropics/financial-services repository, the managed-agent cookbook architecture enforces a single-level delegation depth. Sub-agent manifests must specify callable_agents: [] to indicate they are terminal leaf nodes. Attempting to populate this array in a sub-agent would violate the validation constraints defined in scripts/check.py.

What happens if a manifest path in agent.yaml references a non-existent file?

The scripts/check.py validation script will fail with a specific error message indicating the broken reference path. The error format follows: callable_agents.manifest -> {path} (not found). This validation occurs during the CI pipeline to ensure all sub-agent definitions are properly linked before runtime deployment.

Is the sub-agent manifest format identical to the main agent.yaml?

The formats are structurally similar—both define name, model, system prompts, and tool configurations. However, the critical difference lies in the callable_agents field. The root agent.yaml uses this field to list delegation targets, while sub-agent manifests must explicitly set callable_agents: [] to comply with the leaf-node requirement.

Where should sub-agent manifest files be located?

While the system accepts any valid relative path, the convention in managed-agent-cookbooks places sub-agent manifests in a subagents/ directory at the same level as the root agent.yaml. For example, ./subagents/publisher.yaml resolves to managed-agent-cookbooks/valuation-reviewer/subagents/publisher.yaml. This organizational pattern keeps orchestration logic separate from worker configurations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}