How to Create Effective steering-examples.json for Better Handoff Rates

The steering-examples.json file defines the canonical steering events that orchestrators use to route requests between managed agents, and adhering to the schema constraints defined in scripts/orchestrate.py—such as the 2000-character event limit and strict syntax alignment with target agents—directly increases successful handoff rates.

The steering-examples.json configuration serves as the single source of truth for entry points in the anthropics/financial-services repository. When properly configured, this file enables the orchestrator to validate and forward handoff payloads seamlessly between specialized financial agents like valuation reviewers and pitch-book generators. Understanding the exact schema requirements and architectural flow ensures your multi-agent workflows execute without validation errors or routing failures.

Understanding the Orchestration Flow

The handoff mechanism relies on a strict validation pipeline defined in scripts/orchestrate.py. When a managed agent generates a handoff request, the orchestrator extracts the payload and validates it against HANDOFF_PAYLOAD_SCHEMA before routing to the target agent.

Payload Validation Logic

The orchestrator enforces schema compliance through the following validation structure:

# scripts/orchestrate.py – payload validation

HANDOFF_PAYLOAD_SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "required": ["event"],
    "properties": {
        "event": {"type": "string", "maxLength": 2000},
        "context_ref": {"type": "string", "maxLength": 256,
                        "pattern": r"^[A-Za-z0-9 ._/:#-]+$"},
    },
}

Only agents listed in ALLOWED_TARGETS can receive handoffs, protecting the system from arbitrary invocations. The orchestrator scans model outputs for a handoff_request object, extracts the payload, and steers the target agent using the event field.

Architectural Data Flow

The complete workflow follows this sequence:

1. Definition – steering-examples.json defines valid events (e.g., managed-agent-cookbooks/valuation-reviewer/steering-examples.json)
2. Generation – The source agent outputs a handoff_request with an event string
3. Validation – The orchestrator checks the payload against HANDOFF_PAYLOAD_SCHEMA
4. Routing – Valid events trigger the target agent via the steering mechanism

Best Practices for steering-examples.json

Creating entries that maximize handoff success requires precise attention to schema constraints and target agent expectations.

Craft Concise, Descriptive Event Strings

The orchestrator forwards the exact event string to the target agent without modification. Use clear, action-oriented phrasing that downstream workers can parse immediately without additional prompting.

Effective: "Review portco valuations for fund Growth-III as of 2026-03-31"

Ineffective: "Please do the valuation review thing when you have time"

Align Syntax with Target Agent Prompts

Target agents often expect specific grammatical patterns in their system prompts, such as Build pitch book: <target> / <acquirer>, thesis: <text>. Match your event string to these patterns to ensure direct consumability.

Example for pitch-book agents:

{
  "event": "Build pitch book: target CRWD, acquirer PANW, thesis: platform consolidation in security",
  "description": "Single-target pitch with a named acquirer and explicit thesis"
}

Respect Schema Constraints

The HANDOFF_PAYLOAD_SCHEMA enforces hard limits that prevent runtime errors:

• Event length: Maximum 2000 characters to prevent model output truncation
• Context reference: Maximum 256 characters using only alphanumerics, spaces, and ._/:#-
• Required fields: Every payload must include the event property

Violating these constraints causes immediate validation failures in scripts/orchestrate.py.

Include Human-Readable Descriptions

Every entry should contain a description field explaining the business context. This improves discoverability for reviewers and enables UI tools to surface available steering options to users.

Structure:

{
  "event": "Reconcile GL vs subledger, trade date 2026-03-31, classes: EQUITY, FIXED",
  "description": "Quarter-end reconciliation between general ledger and subledger for specified asset classes"
}

Group Events by Business Domain

Organize entries logically by action type—review, reconcile, build—to mirror the agent's internal workflow. This structure aids future maintenance and makes the file navigable for contributors updating specific capabilities.

Practical Implementation Examples

Minimal Entry Template

Use this template when creating new steering events:

{
  "event": "ACTION_DESCRIPTION",
  "description": "Human-readable explanation of when this steering event is used."
}

Realistic Financial Agent Configuration

This example from the pitch-agent cookbook demonstrates domain-specific syntax:

[
  {
    "event": "Build pitch book: target CRWD, acquirer PANW, thesis: platform consolidation in security",
    "description": "Single-target pitch with a named acquirer and explicit thesis"
  },
  {
    "event": "Refresh comps and football field only for target CRWD",
    "description": "Follow-up event after the MD requests a comps refresh"
  }
]

Valid Handoff Payload Structure

When the orchestrator processes a handoff, it expects this JSON structure:

{
  "type": "handoff_request",
  "target_agent": "gl-reconciler",
  "payload": {
    "event": "Reconcile GL vs subledger, trade date 2026-03-31, classes: EQUITY, FIXED"
  }
}

The orchestrator validates this against HANDOFF_PAYLOAD_SCHEMA before invoking the gl-reconciler agent.

Validation and Testing

Before deploying changes, run scripts/check.py to lint all manifest files including steering-examples.json. For integration testing, execute scripts/orchestrate.py locally with mock payloads to confirm that your event strings trigger the intended targets without schema violations.

Summary

• steering-examples.json is the canonical source defining entry points for managed agents in the anthropics/financial-services ecosystem.
• The orchestrator validates all handoffs against HANDOFF_PAYLOAD_SCHEMA in scripts/orchestrate.py, enforcing a 2000-character limit on events and strict character patterns on context references.
• Effective events align precisely with target agent system prompts, use concise action-oriented language, and include descriptive metadata for discoverability.
• Validation tools like scripts/check.py and local orchestrator testing prevent deployment of malformed steering configurations.

Frequently Asked Questions

What is the maximum length for an event string in steering-examples.json?

The HANDOFF_PAYLOAD_SCHEMA in scripts/orchestrate.py enforces a maximum length of 2000 characters for the event field. Exceeding this limit causes immediate validation failures when the orchestrator processes the handoff request.

How does the orchestrator validate steering-examples.json entries?

During deployment, the system validates the JSON against the Agent API schema. At runtime, scripts/orchestrate.py extracts handoff_request objects and validates the payload against HANDOFF_PAYLOAD_SCHEMA, which requires an event string and optionally a context_ref matching the regex pattern ^[A-Za-z0-9 ._/:#-]+$.

Can I use special characters in the event field?

The event field accepts standard string characters, but if you include a context_ref property, it may only contain alphanumerics, spaces, dots, underscores, forward slashes, colons, hashtags, and hyphens. The schema explicitly rejects other special characters to prevent injection attacks and parsing errors.

What happens if a handoff payload fails validation?

If the payload violates the schema—such as missing the required event field, exceeding character limits, or containing forbidden characters in context_ref—the orchestrator rejects the handoff. The source agent receives an error, and the target agent is not invoked, preventing malformed requests from propagating through the system.

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