Skip to content

README.md

Latest commit

 

History

History
161 lines (119 loc) · 8.08 KB

README.md

File metadata and controls

161 lines (119 loc) · 8.08 KB

AgentDispatch Docs

CI Local E2E Live AWS Verification

Documentation for AgentDispatch: the provider-neutral MCP control plane for spawning cloud subagents.

Start here

  • Technical design — core model, adapter boundaries, runtime protocols, and scale path.
  • AgentCore quickstart — configure AgentDispatch and run a first cloud-agent task.
  • AWS AgentCore adapter — V1 provider setup, target modes, protocols, and runtime behavior.
  • AgentCore runtime design — deeper AgentCore runtime notes and implementation decisions.
  • Future provider adapters — how GCP, Azure, Kubernetes, and local adapters fit the same MCP contract.
  • Package consumption — how the separate repos and NPM packages work together.
  • Lead agent prompt kit — copy-paste prompts for Claude Code, Codex, OpenClaw, Hermes, and MCP-capable lead agents.
  • Contributor map — where to make changes and how to choose a first contribution path.
  • Contributor issue bank — ready-to-open adapter, worker, and architecture issues for launch-day contributor conversion.
  • Examples — no-cloud demo, npm canary, prompt kit, live AWS preflight, and live dispatch paths.
  • Use cases — copyable background-task prompts for repo audits, release checks, adapter design, and worker prototypes.
  • Local demo transcript — short copyable terminal path for a launch demo without live AWS credentials.
  • Verification matrix — what local E2E proves, what live AWS proves, and what not to claim.
  • Live AWS verification — opt-in AgentCore preflight and real-dispatch proof path.
  • Launch evidence — retain local E2E, release status, npm, and live AWS proof artifacts before public claims.
  • Release runbook — release order, npm Trusted Publisher setup, provenance, and package publish gates.
  • Release status — one local command for repo cleanliness, unpushed commits, launch gates, and live AWS evidence state.
  • Launch announcement kit — copy for GitHub, X, LinkedIn, Hacker News, Reddit, and demo narration.
  • Repo launch checklist — GitHub, npm, docs, demo, and social-readiness checklist for a high-signal public launch.

Mental model

Run The Local Demo

From the multi-repo workspace:

npm --prefix agentdispatch-docs run demo:local

This creates a temporary config, runs local agentdispatch doctor, checks the MCP server, and prints the lead-agent handoff payload without touching live AWS state.

To capture a sanitized transcript and JSON report for launch notes or demo narration:

npm --prefix agentdispatch-docs run demo:record

Before a public push, release, or announcement, run the release status summary:

npm --prefix agentdispatch-docs run status:release

It reports repo cleanliness, commits ahead of origin/main, local launch gates, and whether a live AWS evidence report exists. If AGENTDISPATCH_LOCAL_E2E_REPORT, AGENTDISPATCH_NPM_STATUS_REPORT, AGENTDISPATCH_PUBLISH_DRY_RUN_REPORT, AGENTDISPATCH_SECURITY_REPORT, or AGENTDISPATCH_PUBLISHED_SMOKE_REPORT point at retained JSON reports, it also shows which launch evidence has actually been kept.

To run the complete no-cloud launch gate and retain the JSON evidence bundle in one command:

AGENTDISPATCH_LAUNCH_EVIDENCE_DIR=./agentdispatch-launch-evidence \
npm --prefix agentdispatch-docs run verify:launch

That command runs the local E2E gate, npm version drift check, publish dry-run, security audit, published package canary, and release-status capture. It does not run live AWS dispatch.

To compare local package versions with npm before publishing:

npm --prefix agentdispatch-docs run status:npm

To keep that evidence for status:release:

AGENTDISPATCH_NPM_STATUS_REPORT=./agentdispatch-npm-status-report.json \
npm --prefix agentdispatch-docs run status:npm

To verify npm publish packaging from each public package directory:

npm --prefix agentdispatch-docs run status:publish

To keep that evidence for status:release:

AGENTDISPATCH_PUBLISH_DRY_RUN_REPORT=./agentdispatch-publish-dry-run-report.json \
npm --prefix agentdispatch-docs run status:publish -- --strict

To audit high and critical npm vulnerabilities across the workspace:

npm --prefix agentdispatch-docs run status:security

To keep that evidence for status:release:

AGENTDISPATCH_SECURITY_REPORT=./agentdispatch-security-audit-report.json \
npm --prefix agentdispatch-docs run status:security -- --strict

AgentDispatch gives lead agents one stable way to hand off long-running work:

sequenceDiagram
  participant Lead as Lead agent
  participant MCP as AgentDispatch MCP
  participant Core as AgentDispatch core
  participant Adapter as Provider adapter
  participant Runtime as Cloud runtime

  Lead->>MCP: spawn_cloud_agent
  MCP->>Core: dispatch provider-neutral request
  Core->>Adapter: resolve target + provision/start task
  Adapter->>Runtime: invoke cloud subagent
  Runtime-->>Adapter: chunks/events/result
  Adapter-->>Core: provider-neutral events
  Core-->>MCP: task_id + cloud_agent metadata
  Lead->>MCP: get_task_status / get_task_logs / get_task_result
  Lead->>Runtime: optional A2A/MCP/HTTP follow-up
Loading

For lead-agent builders

OpenClaw, Hermes Agent, Claude Code, Codex, and custom orchestrators should treat AgentDispatch as the control plane:

  • Configure account profiles once.
  • Call spawn_cloud_agent when work should leave the local agent process.
  • Use task_id to poll durable status and retrieve results.
  • Use returned cloud_agent metadata to continue native subagent interaction when the runtime supports it.
  • Start from the lead agent prompt kit when wiring a new MCP client or recording a demo.

For adapter builders

New providers should fit the same MCP contract:

  • Declare provider, capabilities, task types, and target modes.
  • Validate account profile and adapter config before starting work.
  • Keep provider SDKs and provider-specific types inside the adapter package.
  • Emit provider-neutral events and artifacts.
  • Return protocol metadata for A2A, MCP, AG-UI, or HTTP when the runtime supports interaction.

Package docs

Status

V1 implements AWS AgentCore runtime. The docs intentionally describe the broader provider-neutral contract because AgentDispatch is designed to grow by adding adapters, not by changing the tools every lead agent depends on.