Scout
DocsBlogToolsContact

What your agent reads / a2a/agents.md

Scout + A2A: agent setup contract

This is the file an agent fetches, shown with a little styling. Agents read the raw Markdown; nothing here is added or left out.

agents.md integration.json A2A guide

Canonical page: https://openscout.app/a2a
Machine-readable spec: https://openscout.app/a2a/integration.json
Documentation reviewed: 2026-09-26. This is not a live health assertion.

Connect agent systems through Scout’s A2A pilot primitives: agent-card discovery, JSON-RPC task requests, and flight-backed task results.

Status

Local pilot · A2A 1.0 core methods (cancel is queued-only) · no streaming, push, or auth

A2A is a protocol integration, not a Scout marketplace package. Discover the broker’s agent card and follow the capabilities it advertises.

Transport

Agent cards + JSON-RPC over broker HTTP

Agent card → JSON-RPC → Scout flight

Directions

  • A2A calls Scout: a2a (pilot): Per-agent JSON-RPC endpoint on your broker
  • Scout launches A2A: not supported. Scout does not call out to remote A2A agents.

Required inputs and prerequisites

  • A running Scout broker on a trusted local network and its actual configured HTTP base URL.
  • An A2A client compatible with Scout’s advertised methods and transport.
  • Operator-approved connectivity. Do not expose local pilot HTTP directly to the public internet.

Setup procedure

1. Discover the broker card

Set SCOUT_BASE_URL to the Broker URL line printed by scout doctor --detail. Fetch the agent card; never guess a port or reuse the hosted MCP URL. openscout.app is not an A2A agent, so https://openscout.app/.well-known/agent-card.json is intentionally absent: the card lives on your broker.

scout doctor --detail | grep "Broker URL"
curl --fail "$SCOUT_BASE_URL/.well-known/agent-card.json"

2. Choose a registered agent

Read metadata.scoutAgentIds from the broker card and select the operator-approved target. Preserve its original ID; skills[].id is normalized and is not a routing handle. If the list is empty, stop and register a target before sending work. Fetch /v1/a2a/agents/{URL-encoded-agent-id}/agent-card.json and use its JSONRPC supportedInterfaces URL (or url field).

3. Send one small text task

POST this JSON to the selected per-agent RPC endpoint. Replace messageId with a unique ID. This is Scout’s current pilot wire format; inspect errors before using result.task.id. A broker-wide request without explicit target routing will fail.

{
  "jsonrpc": "2.0",
  "id": "send-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "REPLACE_WITH_UNIQUE_MESSAGE_ID",
      "parts": [
        {
          "text": "Review the latest changes and report findings. Do not edit files."
        }
      ]
    },
    "configuration": {
      "blocking": false
    }
  }
}

4. Follow the same task

Retain result.task.id from SendMessage. POST GetTask to the same RPC endpoint with that ID; its task is returned directly in result. Inspect result.status.state and text artifacts. TASK_STATE_INPUT_REQUIRED needs input; distinguish it from TASK_STATE_COMPLETED, TASK_STATE_FAILED, and TASK_STATE_CANCELED. A timeout is not permission to dispatch again.

{
  "jsonrpc": "2.0",
  "id": "get-1",
  "method": "GetTask",
  "params": {
    "id": "RETURNED_TASK_ID"
  }
}

Start here

Check the prerequisites and access gates, then get one documented route working before asking for work.

First useful task: Read the agent card, send one small task using the advertised endpoint, and retrieve that task’s state and result.

Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.

Keep the returned task ID and retrieve its state and result. An accepted task is not a completed answer.

Where will the reply appear?

Retrieve the task’s state and artifacts through GetTask using the returned task ID.

What if the answer hasn’t arrived?

Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing.

How do I follow up?

Use only the context or continuation fields supported by the advertised A2A interface. Check the contract before assuming an existing task accepts another message.

Can Scout run this integration, or only receive asks from it?

These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session.

Acceptance gate

Read the card, submit one authorized text task, then retrieve that same task by ID. Confirm its state and text result. This checks the pilot path; it does not establish full A2A conformance.

Failure handling

SendMessage requires a target agent ID

Select a real ID from the broker card’s metadata.scoutAgentIds and use that agent’s advertised RPC endpoint. Do not use a normalized skill ID or invent a target. Empty discovery means target setup is required.

Streaming or push method unsupported

Use task polling through GetTask. SendStreamingMessage, SubscribeToTask, and push-notification configuration are documented gaps.

Running task cannot be cancelled

CancelTask only cancels queued tasks. A running task returns "already running and cannot be cancelled by the broker yet". Inspect the task state and ask the operator before attempting a runtime-specific stop; do not report cancellation unless confirmed.

Card or endpoint unavailable

Check the Broker URL from scout doctor --detail and the installed version. The hosted MCP gateway is not an A2A endpoint, and openscout.app does not serve an agent card.

Boundaries

  • Not A2A 1.0 conformant: all four required methods respond, but CancelTask fails the required semantics for running tasks. The conformance test kit (a2a-tck) has not been run.
  • Streaming (SendStreamingMessage, SubscribeToTask) and push-notification configuration return -32005 and are advertised as false on the card.
  • No security scheme is declared on the card and signed agent cards are not supported. This is a high-trust local pilot; do not expose it beyond loopback or a trusted network.
  • Rich artifacts remain incomplete; tasks carry text parts.

Conformance: A2A 1.0 (JSON-RPC binding)

Not conformant: required CancelTask semantics fail for running tasks. a2a-tck not run.

MethodSpecScout
SendMessagerequiredYes. Text parts; needs an explicit target agent.
GetTaskrequiredYes.
ListTasksrequiredYes.
CancelTaskrequiredQueued tasks only. Running tasks return an error.
SendStreamingMessage / SubscribeToTaskoptional (capabilities.streaming)No. Returns -32005; card says streaming: false.
Push notification configoptional (capabilities.pushNotifications)No. Returns -32005; card says pushNotifications: false.
GetExtendedAgentCardoptionalYes.
Signed agent cardsoptionalNo.
Security schemesdeclared on the cardNone. High-trust local only.

Agent operating contract

  • Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.
  • Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.
  • Use the advertised A2A JSONRPC endpoint with a registered target. SendMessage creates work; retain result.task.id and pass it as GetTask params.id. Inspect result.status.state and artifacts. This endpoint does not expose MCP tools.
  • Use the transport-specific instructions above. For an existing request, reply through its supplied context rather than creating another task.
  • Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.
  • Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.
  • Observe the existing request through the configured transport. A receipt proves acceptance, not execution or successful completion.
  • Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.
  • Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.
  • Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.

Completion report

Report: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.

Sources and next reads