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

> Understand the difference between callable_agents.manifest and main agent.yaml in managed-agent-cookbooks. Learn about the two-tier architecture for agents and delegation.

- Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services)
- Tags: deep-dive
- Published: 2026-05-07

---

**The root [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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:

```yaml

# 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](https://github.com/anthropics/financial-services/blob/main/managed-agent-cookbooks/valuation-reviewer/agent.yaml#L25-L28), these paths resolve relative to the [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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:

```yaml

# 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](https://github.com/anthropics/financial-services/blob/main/managed-agent-cookbooks/valuation-reviewer/subagents/publisher.yaml#L16), 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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to enforce the two-tier architecture constraints. The script specifically validates that every `manifest` entry in the root [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/agent.yaml) points to an existing file:

```python

# 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`](https://github.com/anthropics/financial-services/blob/main/agent.yaml) shows the delegation structure for a valuation workflow:

```yaml
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:

```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: []

```

### Validation Error Handling

When [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py).

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

The [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/agent.yaml). For example, [`./subagents/publisher.yaml`](https://github.com/anthropics/financial-services/blob/main/./subagents/publisher.yaml) resolves to [`managed-agent-cookbooks/valuation-reviewer/subagents/publisher.yaml`](https://github.com/anthropics/financial-services/blob/main/managed-agent-cookbooks/valuation-reviewer/subagents/publisher.yaml). This organizational pattern keeps orchestration logic separate from worker configurations.