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

> Learn to create effective steering-examples.json for financial services. Master routing requests between agents to boost handoff rates and ensure successful agent interactions. Read our guide now.

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

---

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

```python

# 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`](https://github.com/anthropics/financial-services/blob/main/steering-examples.json) defines valid events (e.g., [`managed-agent-cookbooks/valuation-reviewer/steering-examples.json`](https://github.com/anthropics/financial-services/blob/main/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:**

```json
{
  "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`](https://github.com/anthropics/financial-services/blob/main/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:**

```json
{
  "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:

```json
{
  "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:

```json
[
  {
    "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:

```json
{
  "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`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to lint all manifest files including [`steering-examples.json`](https://github.com/anthropics/financial-services/blob/main/steering-examples.json). For integration testing, execute [`scripts/orchestrate.py`](https://github.com/anthropics/financial-services/blob/main/scripts/orchestrate.py) locally with mock payloads to confirm that your event strings trigger the intended targets without schema violations.

## Summary

- **[`steering-examples.json`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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.