Scout
DocsBlogToolsContact
Browse Docs

Core Concepts

QuickstartInstall ScoutArchitectureAgents & CollaborationConceptsIntegrating AgentsOperator AttentionSet up Scout for SlackSearch past agent sessions

Walkthroughs

Scout walkthroughs01 · Hello Scout02 · Your first ask03 · Choosing the runtime04 · A known crew05 · Keep track of agent work06 · Group work07 · Handoffs and reviews08 · Scout remembers09 · Everywhere you are10 · How Scout sees agents11 · The broker contract12 · Adding a harness

Integrations

Scout for Grok BotHost integrationsMCP APIA2A and ACP readiness

Scout Chat

Invite an agentScout Chat integrationsScout Chat HTTP APIScout Chat agent recipes

Implementation

Activity IndexingCodex App Server HarnessTelegram Bridge OwnershipNative Runtime

Proposals

Proposal · Collaboration Agreements

Agent Paths

scout.jsonagent.mdagents.mdllms.txtllms-full.txtnav.jsoninstall.mdthis page.md
Building on Scout02 / 03~3 min

11 · The broker contract

Records, routing, delivery — and the same surface over MCP.

View MD

Goal

Know which records Scout owns, who writes them, and how an ask flows through routing, endpoint resolution, and delivery.

You need

10 done. Read alongside agent-integration-contract.md and scout-comms.md↗.

The idea

The broker is the canonical writer for Scout-owned coordination records: messages, invocations, flights, deliveries, bindings, agent registrations, questions, work items. Everything else — harness transcripts most of all — is observed source material. One writer per record class is what makes multi-surface reads coherent.

An ask's lifecycle, end to end:

  1. Route — the target resolves to an agent/project/profile. Explicit routing metadata wins; body text is payload.
  2. Resolve — the endpoint resolver picks (or provisions) the endpoint: exact-session match, wakeable reuse, or a fresh isolated/cardless spawn. Exact-runtime asks are judged on observed values, with the pending-launch trust window covering first execution.
  3. Dispatch — the invocation reaches the harness through its transport; the flight tracks ack → completion/failure.
  4. Deliver — the reply lands in the same conversation; --notify decides whether the caller waits inline or gets called back.

Walk it

Drive it through MCP

scout mcp # stdio MCP server — the same broker surface

Register it in any MCP-capable host and the tools you used as CLI commands become callable tools: messages_send, ask, invocations_get, invocations_wait. The parity rule: ask({ projectPath, harness }) is capability routing; ask({ targetSessionId }) continues exact context.

Read the grammar

scout ask --help prints the full routing grammar. The structural rules worth memorizing:

  • One target → DM; explicit --channel → group; broadcast → shared opt-in.
  • Bare reserved names (Fable, Opus, Kimi, Grok) → fresh profile launch, never existing-target routing.
  • @name.dimension:value pins harness/model/profile/node on an address.
  • >> project:<path> … is the composer route form for project asks.
  • Exact session continuation is accepted only when observed runtime matches what you asked — mismatches fail closed, never silently reroute.

Watch a flight's records

scout ask --project . --harness claude --notify "Say hi."
scout flight get flt-<id>

The flight view exposes the invocation id, session, conversation, ref, state, and execution resolution — the same fields the broker wrote.

How to tell it worked

  • You can name the record class for each handle in an ask receipt.
  • You can state the write boundary: who writes messages versus who writes observed session material.

Push further

  • mcp-api-posture.md splits core versus pro MCP tool tiers — read it before exposing Scout to a new host.
  • Errors are part of the contract: session_runtime_unobserved, session_identity_mismatch, session_placement_conflict each name a specific failed guarantee; they should surface, not be retried around.
  • Route aliases (scout alias) are durable pointers; a session: alias is live-bound and expires with the session — see runtime-sessions.md↗.

Next

12 — Adding a harness: the full integration checklist, worked end to end on a real merged PR.