voly/a2a/ — Agent2Agent orchestration: task decomposition, federation dispatch,
parallel subtask execution, and result merging.
| Module | Role |
|---|---|
__init__.py |
A2AOrchestrator, A2AClient, dispatch_parallel() |
decomposer.py |
TaskDecomposer — rule-based split from TaskAnalysis flags |
multiagent.py |
Public surface: run_local, LeadOrchestrator, merge_report re-exports |
multiagent_run.py |
_LocalRun + wave scheduling (run_local implementation) |
multiagent_plan.py |
Plan-gate setup / finish_step_plan |
multiagent_roles.py |
Role prepare / executor / chat helpers |
hybrid.py |
Role → chat / executor policy + make_agent_runner_executor |
context.py |
Role prompts, git-diff evidence, skills/memory blocks |
waves.py |
Dependency-wave grouping for parallel chat roles |
chat_fallback.py |
Healthy-provider fallback loop for chat roles |
assignment.py |
Tiers, outcome evaluation, VOLY_A2A_EXCLUDE_PROVIDERS |
lead.py |
Lead orchestrator (tier + skills; lead_mode auto/llm/deterministic) |
merger.py |
ResultMerger — combine subtask outputs |
report.py |
A2AReport + merge_report for local multi-agent |
episode.py |
Versioned AgentTrace / MultiAgentEpisode, role metrics, atomic local store |
environments.py |
Role-independent interaction patterns (PipelineEnv, SolverJudgeEnv, parallel solutions, debate, iterative repair) |
Every local multi-agent run is adapted into one MultiAgentEpisode and stored
at <project>/.voly/episodes/<task_id>.json. An episode is the orchestration
record; it does not replace executor EvidenceRecord or EvalReport.
Each AgentTrace contains the role messages, normalized executor attempts,
file artifacts, routing decisions, token/cost data, dependency trace ids and
role metrics. Assignment.to_event_dict() exposes only the trace id and role
metric summaries. The complete episode remains local; the Cloud analytics
allowlist still excludes prompts, outputs, repository paths and A2A payloads.
MultiAgentEnvironment separates the interaction pattern from agent roles and
uses the asynchronous contract run(task, agents) -> MultiAgentEpisode.
Built-ins are PipelineEnv, SolverJudgeEnv, ParallelSolutionsEnv,
DebateEnv, and IterativeRepairEnv. The existing dependency-wave scheduler
is currently the production adapter for PipelineEnv.
SolverJudgeEnv requires exactly a solver and judge. The judge request receives
the solver trace, diff artifacts, acceptance criteria and only the declared
read-only operations (list_files, read_file, search_text, git_diff).
Provider tool definitions and returned calls are normalized by AIGateway for
Anthropic, OpenAI and Google. When evaluation.llm_judge.mode is shadow or
required, the local A2A pipeline appends an interactive judge trace to the
episode. shadow records the verdict without changing task status; required
turns a non-pass or judge failure into a failed/partial pipeline result.
Role metric ids are stable: architecture_usefulness,
implementation_correctness, test_coverage, reviewer_precision, and
cost_adjusted_contribution. Runtime currently records only the last metric as
an explicitly labelled proxy. Quality metrics must come from deterministic
checks or an independent judge, never from the role scoring itself.
| cwd_lock.py | Cross-process executor lock on shared --cwd |
| federation.py | HTTP client for cf-workers/a2a (D1 + Queues) |
Local hybrid details (default executor roles, cascade, plan gates): see
docs/backend/pipeline.md § Multi-agent / Hybrid.
Four frontend-focused roles extend ROLE_REGISTRY (voly/a2a/roles.py). Each defines
decomposer_signals (keyword substrings) and capability_requirements for
capability-aware assignment.
| Role | Tier | Mode | Signals (sample) | Capability requirements |
|---|---|---|---|---|
ui_architect |
standard | chat | svelte, react, frontend, design system, tailwind |
frontend >= 0.70 |
visual_reviewer |
premium | chat | screenshot, figma, ui review, wcag, accessibility |
frontend >= 0.75, image_input: true |
browser_tester |
standard | executor | e2e, playwright, cypress, browser test |
frontend >= 0.70, browser_tools: true |
ux_reviewer |
cheap | chat | ux, usability, user flow, interaction design |
frontend >= 0.55 |
Bare tokens like design, visual, ui, component, and layout are intentionally
omitted — they false-positive on backend prompts (e.g. “architecture design”).
ui_architect — plans component structure, state, routing, and visual hierarchy
(chat-only; no full implementations).
visual_reviewer — reviews pixel accuracy, WCAG 2.1 AA accessibility, responsive
behavior, and design-system consistency. Requires image_input capability on the
assigned provider. inject_prior_context=True so prior subtask summaries are appended
before the review prompt.
browser_tester — executor role (default executor: cursor); writes Playwright or
Cypress end-to-end tests for user flows, visual regressions, and cross-browser checks.
Requires browser_tools: true on the matched executor.
ux_reviewer — cheap-tier chat role for usability, information architecture, and
interaction patterns. inject_prior_context=True for context from earlier waves.
TaskDecomposer._signal_driven_roles(task) scans the task string against every role's
decomposer_signals in ROLE_REGISTRY. Multi-word signals use case-insensitive
substring match; single-word signals use word-boundary (\b) match. Roles with
empty signals are skipped.
- When flag-based decomposition already produced subtasks,
_with_signal_roles()appends any matched roles not already in the list (withdepends_onset to prior indices). - When flag-based decomposition returns nothing but signals match,
_signal_subtasks()builds a subtask list from the matched roles alone (e.g. screenshot review tasks).
Vision-capable model providers for visual_reviewer are seeded in
voly/capability/seeds/kimi-cli-vision.yaml and claude-vision.yaml.
When capability.enabled is true (or VOLY_CAPABILITY_ENABLED=1), the pipeline
wires ExecutorMatcher into LeadOrchestrator with task_features from
REPO_INTELLIGENCE (or a local cwd scan) and routing_policy from config.
Hybrid executor roles keep the matcher-chosen executor
(make_agent_runner_executor honors a non-empty assignment; static
resolve_role_executor only fills when unset). Chat roles match
kind=model_provider with requires_file_tools=false and provider health
filtering. Run evidence is POSTed to {worker_url}/profiles/evidence when
worker_url is set.
LeadOrchestrator accepts optional matcher (ExecutorMatcher) and
project_context (dict with task_features from REPO_INTELLIGENCE or project scan).
For each subtask with a role, when matcher is set:
- Resolve
kind:executorif the role is inEXECUTOR_CAPABLE_ROLES, elsemodel_provider. - Call
matcher.find_executors(MatchRequest(dimension=role_to_dimension(role), kind=kind, …)). - When
result.recommendedis notNone, use its id (executor) or model/provider hint on the assignment.
When the matcher returns None or raises, assignment falls back to the existing
tier resolution (_ROLE_TIER + resolve_role_model()).
When a2a.auto_dispatch: true (default) and TaskAnalysis has 2+ capability flags
or complexity=high, Pipeline.run() calls _stage_a2a_auto().
analyze_task also sets requires_review=True whenever two or more capability
flags are already set (e.g. code-gen + tests → developer + tester + reviewer).
ROUTE → _should_dispatch_a2a() → TaskDecomposer → dispatch_parallel() → ResultMerger
Config (voly.yaml → a2a):
| Field | Default | Meaning |
|---|---|---|
enabled |
true |
Master switch |
auto_dispatch |
true |
Auto-decompose complex tasks |
min_flags_for_dispatch |
2 |
Min capability flags to trigger |
task_timeout_seconds |
600 |
Per-role hybrid executor timeout (watchdog base) |
architect_max_tokens |
4096 |
Architect plan chat budget |
executor_roles |
(built-in) | Empty → developer, bugfixer, tester, devops |
federation_url |
— | CF A2A worker URL |
run_local initializes the parent RunRecord.graph_nodes/graph_edges from
assignments and their depends_on indices. Nodes have stable agent-{idx} ids
and are upserted from pending to running, then to
completed/failed/blocked with their actual route, duration, cost, files,
and error. Parallel chat roles can therefore be running on the same canvas.
Each node also carries chain_timelog (Assignment.chain_timelog, populated
in multiagent_roles.run_executor() from the executor_runner result's
chain_timelog key — see voly/a2a/hybrid.py's make_agent_runner_executor,
which reads it off ExecutorResult.metadata). This is the SAME per-role
billing-fallback bookkeeping agent_runner.py produces for single-agent runs
(docs/backend/executors.md); it previously stopped at the executor-result
boundary and never reached Assignment/graph_node(), so an A2A role that
had to retry on a different executor was invisible on the live graph — only
the flat task-level billing chain (InspectorBillingChain) showed it, and
only when the fallback happened to also occur at the top level. Empty list
= no fallback for that role.
Hybrid AgentRunner calls set parent_task_id to the A2A task id. Their child
records remain available through direct lookup or GET /api/runs?include_children=1,
while the default active-run list contains only the parent. This prevents one
logical multi-agent run from appearing as several independent flows.
A2A subtasks run through pipeline_server.py → Pipeline.run(). Without a guard,
auto-dispatch would re-decompose every subtask into more subtasks (infinite recursion).
Skipped when any of:
delegate_to_a2a=False(always set by pipeline server for subtasks)VOLY_A2A_NESTED=1env var (set by pipeline server during subtask runs)context["a2a_parent_task_id"]present (fromtask_id/a2a_parent_task_idin POST body)
CF agent worker passes a2a_parent_task_id: task_id in /run requests.
run_local stops the whole chain the moment a sub-agent comes back
spend_limited (budget exhausted): remaining roles are marked
error="Spend limit exceeded" without another AIGateway.chat() call and the
loop breaks. Same observable outcome as walking every role, minus the wasted
calls — the budget won't recover mid-run. Tested in
tests/test_failure_paths.py and tests/test_tenant_isolation.py.
dispatch_parallel() (federation) and run_local (local) both process roles in
dependency waves:
- Wave 0 — no
depends_on(parallel where allowed) - Later waves — inject prior results via
TaskDecomposer.inject_prior_context()(files list + truncated body, labeled untrusted). Reviewer/tester also receive a git-diff evidence block from priorfiles_touched.
Example enriched description:
Review code and tests using developer context
## Prior subtask summaries (untrusted context)
### developer
Files touched:
- app/main.py
implemented restore endpoint
| Layer | Mechanism |
|---|---|
pipeline_server.py |
force_agent=agent on Pipeline.run() |
voly a2a call (local) |
Pipeline.run(force_agent=agent_name, context={cwd, project_cwd}) — not agent= |
cf-workers/agent/pipeline.ts |
passes agent to /run and /infer |
cf-workers/agent/infer.ts |
system prompt prefix: You are the {agent} agent... |
| Endpoint | Behavior |
|---|---|
POST /tasks |
Create task; queue dispatch when agent_name set |
GET /tasks/:id |
Task status |
POST /tasks/:id/complete |
Agent callback; no-op if already completed |
| Queue consumer | Skips dispatch when state ≠ submitted |
Agent worker (cf-workers/agent):
getA2ATaskState()— fetch status before re-execute- Skips
/agents/:name/runwhen task alreadycompletedorfailed completeA2ATask()— callback to federation after pipeline run
voly run "implement X, write tests, review" --a2a-delegate # explicit A2A path
# auto-dispatch triggers without flag when a2a.enabled + complex taskWeb UI: a2a_delegate on /api/run maps to delegate_to_a2a.
| Var | Used by |
|---|---|
VOLY_A2A_NESTED |
Pipeline — skip auto-dispatch for subtasks |
PIPELINE_RUNNER_URL |
CF agent worker → local pipeline server |
PIPELINE_RUNNER_TOKEN |
Auth for pipeline server |
A2A_FEDERATION_URL / A2A_FEDERATION_TOKEN |
Federation callbacks |