Skip to content

Commit a38e996

Browse files
chicoxyzzychicoxyzzy
committed
docs: add ADK and A2A alignment proposal
1 parent d68deb6 commit a38e996

2 files changed

Lines changed: 359 additions & 0 deletions

File tree

‎docs/design/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ before implementing Agent Profiles V1, skill registry support, or workspace
6868
| --------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
6969
| [Hecate Chat and model capabilities](accepted/hecate-chat-model-capabilities.md) | Accepted | Hecate Chat, tools on/off segments, observed capability metadata, profiles, future detection. |
7070
| [External Agent integrations](accepted/external-agent-integrations.md) | Accepted | Codex, Claude Code, Cursor Agent, Grok Build, ACP controls, approvals, readiness, diagnostics, diff review. |
71+
| [ADK and A2A alignment](proposals/adk-a2a-alignment.md) | Proposal | ADK concepts as design input, A2A as a future protocol adapter for Hecate and remote agents. |
7172
| [External Agent approval loop v1](implemented/external-agent-approval-loop-v1.md) | Implemented | Prompt-first approvals, durable grants, startup reconcile, UI review, telemetry. |
7273

7374
### Runtime Contracts
@@ -107,6 +108,7 @@ before implementing Agent Profiles V1, skill registry support, or workspace
107108
| [Workflow runbooks v0](proposals/workflow-runbooks-v0.md) | Proposal | Workflow runbooks |
108109
| [Hecate Chat and model capabilities](accepted/hecate-chat-model-capabilities.md) | Accepted | Agent and chat runtime |
109110
| [External Agent integrations](accepted/external-agent-integrations.md) | Accepted | Agent and chat runtime |
111+
| [ADK and A2A alignment](proposals/adk-a2a-alignment.md) | Proposal | Agent and chat runtime |
110112
| [External Agent approval loop v1](implemented/external-agent-approval-loop-v1.md) | Implemented record | Agent and chat runtime |
111113
| [Agent event protocol v1](candidates/event-protocol-v1.md) | Candidate | Runtime contracts |
112114
| [Artifact storage v1](candidates/artifact-storage-v1.md) | Candidate | Runtime contracts |

‎docs/design/proposals/adk-a2a-alignment.md‎

Lines changed: 357 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
# ADK And A2A Alignment
2+
3+
> **Status:** proposed.
4+
> **Current source of truth:** [Agent runtime](../../runtime/agent-runtime.md),
5+
> [External Agents](../../runtime/external-agents.md),
6+
> [MCP integration](../../runtime/mcp.md),
7+
> [Chat sessions](../../runtime/chat-sessions.md), and
8+
> [Workspace instructions, skills, and profiles](workspace-instructions-skills-and-profiles.md)
9+
> for today's runtime, adapter, tool, chat, context, and profile behavior.
10+
> **Next action:** prototype an A2A protocol-adapter spike around an Agent
11+
> Card, task/run mapping, and streaming projection before adding any ADK or
12+
> A2A SDK dependency.
13+
14+
Hecate should align more closely with the emerging ADK and A2A vocabulary, but
15+
without giving up the local-first runtime and operator-control model that make
16+
Hecate useful. The practical split:
17+
18+
- **ADK is a source of reusable concepts and optional interop targets.** Hecate
19+
should borrow the useful vocabulary around agents, sessions, state, tools,
20+
memory, artifacts, workflows, evaluation, and developer inspection. It should
21+
not replace `agent_loop` with ADK or turn ADK into the core runtime.
22+
- **A2A is a candidate protocol adapter.** Hecate should treat A2A like ACP,
23+
MCP, OpenAI-compatible HTTP, and Anthropic Messages: a way for another system
24+
to talk to or from Hecate, not a provider or replacement execution model.
25+
26+
## External Alignment
27+
28+
Facts, accessed 2026-06-08:
29+
30+
- ADK describes itself as an open-source framework for building, debugging,
31+
evaluating, and deploying agents across Python, TypeScript, Go, Java, and
32+
Kotlin. Source: <https://adk.dev/>.
33+
- ADK's core concepts include agents, tools, callbacks, sessions/state, memory,
34+
artifacts, code execution, planning, models, events, and runners. Source:
35+
<https://adk.dev/get-started/about/>.
36+
- ADK's A2A docs recommend A2A when communicating with standalone services,
37+
agents maintained by other teams, cross-language systems, or components that
38+
need a strong formal contract; local sub-agents are preferred for in-process
39+
helper behavior. Source: <https://adk.dev/a2a/intro/>.
40+
- ADK Go can expose an ADK agent through an A2A launcher and generate an Agent
41+
Card for the server. Source:
42+
<https://adk.dev/a2a/quickstart-exposing-go/>.
43+
- A2A is documented as an open standard for communication and collaboration
44+
between independent, often opaque, agents. Source:
45+
<https://a2a-protocol.org/latest/>.
46+
- A2A's core concepts include Agent Cards, Tasks, Messages, Parts, Artifacts,
47+
`contextId`, HTTP transport, JSON-RPC payloads, and standard auth through
48+
HTTP headers. Source:
49+
<https://a2a-protocol.org/latest/topics/key-concepts/>.
50+
- A2A treats MCP as complementary: MCP is agent-to-tool, while A2A is
51+
agent-to-agent collaboration. Source:
52+
<https://a2a-protocol.org/latest/topics/a2a-and-mcp/>.
53+
- A2A supports SSE for long-running tasks and push notifications for
54+
disconnected scenarios. Source:
55+
<https://a2a-protocol.org/latest/topics/streaming-and-async/>.
56+
- Official A2A SDKs exist for multiple languages, including Go. Source:
57+
<https://a2a-protocol.org/latest/sdk/>.
58+
59+
## Fit With Hecate
60+
61+
Hecate already separates the pieces that ADK and A2A tend to bundle together:
62+
63+
| Hecate concept | Current role | ADK / A2A alignment |
64+
| -------------- | ------------ | ------------------- |
65+
| Model provider | OpenAI, Anthropic, Ollama, LM Studio, and compatible backends answer LLM calls. | Keep separate. ADK and A2A agents are not model providers. |
66+
| Native runtime | `agent_loop` runs Hecate-owned tool loops with approvals, artifacts, events, cost accounting, and sandboxed tool calls. | Borrow ADK concepts for profiles, workflow graphs, and evaluation; do not replace this runtime. |
67+
| Agent adapter | ACP-backed Codex, Claude Code, Cursor Agent, Grok Build, and future opaque coding agents. | A remote A2A agent can become another External Agent target. |
68+
| Protocol adapter | ACP, MCP, OpenAI-compatible HTTP, Anthropic Messages. | A2A belongs here. |
69+
| MCP | Hecate as an MCP server and as an MCP client for external tools. | Keep MCP as the agent-to-tool/control-plane protocol. A2A should not displace MCP. |
70+
| Agent profile | Saved runtime posture: model/provider hints, tools, approvals, skills, memory/context activation, and system/profile instructions. | Align profile fields with ADK's agent/tool/session vocabulary where useful. |
71+
| Runbook | Named workflow pattern with inputs, evidence, approvals, and stop conditions. | Borrow ADK graph/workflow and evaluation ideas as Hecate-native runbooks. |
72+
73+
This keeps the accepted external-agent distinction intact: providers answer LLM
74+
calls, agent adapters drive coding-agent loops, and protocol adapters define
75+
how systems talk to Hecate.
76+
77+
## Reusable ADK Ideas
78+
79+
Hecate can adopt several ADK-shaped ideas without importing the ADK runtime.
80+
81+
### Agent Vocabulary
82+
83+
ADK's `Agent`, `Tool`, `Runner`, `Session`, `State`, `Memory`, and `Artifact`
84+
terms are useful names for ideas Hecate already has. Hecate should use this
85+
vocabulary where it clarifies public docs and UI labels, while preserving
86+
Hecate-specific storage and API shapes.
87+
88+
Suggested mapping:
89+
90+
| ADK concept | Hecate-native shape |
91+
| ----------- | ------------------- |
92+
| Agent | Hecate agent profile, Hecate-owned `agent_loop`, or External Agent adapter depending on context. |
93+
| Tool | Built-in task tool or namespaced MCP tool. |
94+
| Runner | Orchestrator plus task runner. |
95+
| Session | Chat session, task context, or External Agent native session metadata. |
96+
| State | Context packet, run state, session metadata, and runtime records. |
97+
| Memory | Operator-approved Hecate memory scoped by project/profile. |
98+
| Artifact | Hecate task artifact, chat diff artifact, or future portable artifact storage record. |
99+
| Workflow / graph | Hecate runbook steps and evidence requirements. |
100+
| Evaluation | Hecate replay/eval suites for `agent_loop`, chat, and External Agent turns. |
101+
102+
### Agent Profiles
103+
104+
Agent Profiles V1 should be easy to compare to an ADK agent definition:
105+
106+
- name, description, and intended use
107+
- model/provider or adapter hint
108+
- system/profile instruction
109+
- enabled skills
110+
- tool and MCP posture
111+
- approval policy
112+
- memory/context source policy
113+
- runtime limits
114+
- evaluation fixtures or smoke prompts
115+
116+
Profiles remain Hecate-owned. They should not become ADK config files, but a
117+
future export/import bridge can translate the portable subset.
118+
119+
### Workflow Graphs And Runbooks
120+
121+
ADK's graph and workflow-agent direction maps well to Hecate runbooks:
122+
deterministic checkpoints around adaptive model calls. Hecate should borrow
123+
these patterns as runbook metadata:
124+
125+
- sequential, parallel, and loop steps
126+
- explicit route conditions
127+
- human-input gates
128+
- expected artifacts
129+
- stop conditions
130+
- evidence requirements
131+
- replay/evaluation datasets
132+
133+
The execution substrate should remain Hecate tasks/runs at first. A new
134+
workflow engine should wait until runbook experiments prove they need more than
135+
task metadata and artifacts.
136+
137+
### Evaluation And Replay
138+
139+
ADK's built-in evaluation emphasis is worth adopting more directly. Hecate
140+
should grow eval fixtures for:
141+
142+
- agent-loop tool selection and final-answer quality
143+
- approval-pause/resume behavior
144+
- External Agent transcript normalization
145+
- A2A protocol mapping
146+
- runbook outputs and evidence completeness
147+
- context packet stability across profile or project changes
148+
149+
These should use Hecate's existing fake providers, fake adapters, task stores,
150+
and UI fixtures before adding external eval services.
151+
152+
## A2A Adoption Shape
153+
154+
A2A should enter Hecate as a protocol adapter in slices.
155+
156+
### Slice 1: Hecate Agent Card
157+
158+
Expose a Hecate Agent Card for local or authenticated clients.
159+
160+
Candidate endpoints:
161+
162+
```text
163+
GET /.well-known/agent-card.json
164+
GET /hecate/v1/a2a/agent-card
165+
```
166+
167+
The `/.well-known` endpoint should be disabled by default or minimal until the
168+
security posture is accepted. The Hecate-native endpoint can require the same
169+
runtime token used by other local control-plane APIs.
170+
171+
The card should describe Hecate-level skills such as:
172+
173+
- create a supervised Hecate task
174+
- continue a Hecate Chat session
175+
- inspect task/run status
176+
- stream task progress
177+
- list recent tasks
178+
- cancel a run
179+
- resolve an approval
180+
- inspect trace summaries
181+
182+
Avoid publishing sensitive workspace paths, provider names, custom MCP server
183+
details, or private project metadata in an unauthenticated card.
184+
185+
### Slice 2: A2A Server Adapter
186+
187+
Implement a local/authenticated A2A JSON-RPC adapter backed by existing Hecate
188+
APIs and stores.
189+
190+
Candidate method mapping:
191+
192+
| A2A method | Hecate behavior |
193+
| ---------- | --------------- |
194+
| `SendMessage` | Create or continue a Hecate task/chat turn and return either a message or a task snapshot. |
195+
| `SendStreamingMessage` | Start the same work and project existing task/chat SSE updates into A2A stream events. |
196+
| `GetTask` | Return a run/task snapshot using A2A task state and artifact shapes. |
197+
| `ListTasks` | Return recent Hecate runs/tasks scoped by context or status. |
198+
| `CancelTask` | Cancel the mapped Hecate run. |
199+
| `SubscribeToTask` | Reattach to a non-terminal run stream using Hecate's replayable event sequence. |
200+
201+
V1 should skip A2A push notifications. Webhook callbacks introduce SSRF,
202+
authentication, replay, and lifecycle concerns that Hecate does not need for
203+
local operator flows.
204+
205+
### Slice 3: Remote A2A Agents As External Agents
206+
207+
Connections can later accept a directly configured A2A Agent Card URL:
208+
209+
```text
210+
Hecate Chats
211+
-> Target: External Agent
212+
-> Protocol: A2A
213+
-> Remote Agent Card URL
214+
-> Prompt
215+
-> A2A task/message stream
216+
```
217+
218+
Rules:
219+
220+
- Direct configuration first. No broad registry or domain crawling in V1.
221+
- Fetch and display the Agent Card during readiness checks.
222+
- Store auth configuration explicitly and redact it through the existing
223+
control-plane secret model.
224+
- Treat the remote agent as opaque, the same way ACP-backed agents are opaque.
225+
- Do not forward Hecate provider credentials by default.
226+
- Do not grant workspace access unless the operator explicitly configures a
227+
workspace-sharing mechanism.
228+
- Surface remote A2A cost as `external` / `unknown` unless structured usage is
229+
reported and mapped.
230+
231+
This lets Hecate consume ADK-built agents through A2A without adopting ADK
232+
itself.
233+
234+
### Slice 4: Optional SDK Reuse
235+
236+
Before implementing A2A by hand, audit the official Go SDK and its transitive
237+
dependencies. The current Hecate Go toolchain is new enough for the public
238+
`a2a-go` requirement noted in its README, but compatibility is only one part
239+
of the decision.
240+
241+
Adopt an SDK only if it helps with:
242+
243+
- protocol type correctness
244+
- Agent Card parsing/validation
245+
- JSON-RPC and SSE edge cases
246+
- conformance tests
247+
- future gRPC support without duplicating protocol code
248+
249+
Do not adopt an SDK if it forces:
250+
251+
- a second runtime model
252+
- hosted/multi-tenant assumptions
253+
- uncontrolled auth behavior
254+
- broad dependency churn
255+
- loss of Hecate's existing event, approval, or artifact semantics
256+
257+
## Semantic Mapping
258+
259+
A2A's lifecycle should map to Hecate without pretending the two models are the
260+
same.
261+
262+
| A2A concept | Hecate mapping |
263+
| ----------- | -------------- |
264+
| Agent Card | Hecate capability document for local/authenticated clients, or remote External Agent descriptor when consumed. |
265+
| AgentSkill | Hecate actions such as create task, continue chat, inspect run, cancel run, resolve approval, inspect traces. |
266+
| `contextId` | Hecate chat session id, project-scoped conversation id, or future task context id. |
267+
| `taskId` | Prefer Hecate run id for protocol identity; include Hecate task id as metadata. |
268+
| Task | A snapshot of one unit of work. Terminal A2A tasks are immutable; Hecate retries/follow-ups should produce new A2A task ids. |
269+
| Message | Chat or task turn message. |
270+
| Part | Hecate content block or artifact part. |
271+
| Artifact | Hecate task artifact, final answer, stdout/stderr artifact, file/diff artifact, or future portable artifact record. |
272+
| `input-required` | Hecate `awaiting_approval` or explicit clarification-needed state, depending on source. |
273+
| `auth-required` | Provider, adapter, MCP, or remote-agent auth failure surfaced as a stable state/error. |
274+
| SSE stream | Existing task-run or chat-session SSE projected into A2A `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`. |
275+
276+
Status mapping sketch:
277+
278+
| Hecate status | A2A task state |
279+
| ------------- | -------------- |
280+
| `queued` | submitted / working |
281+
| `running` | working |
282+
| `awaiting_approval` | input-required |
283+
| `completed` | completed |
284+
| `cancelled` | canceled |
285+
| `failed` | failed |
286+
| approval rejected | rejected |
287+
288+
The exact enum spelling should follow the current A2A SDK/spec at
289+
implementation time.
290+
291+
## Security Posture
292+
293+
The A2A surface must keep Hecate's local operator boundary.
294+
295+
- Default bind remains loopback.
296+
- Public discovery is disabled or minimal by default.
297+
- Detailed Agent Cards require authentication.
298+
- Runtime-token and future client identity checks apply before state-changing
299+
methods.
300+
- Every A2A write maps to existing Hecate authorization, policy, sandbox, and
301+
approval paths.
302+
- Remote A2A agents do not receive provider secrets, MCP secrets, workspace
303+
paths, project memory, or private context unless explicitly configured.
304+
- Push notifications are deferred until there is a separate SSRF and webhook
305+
authentication design.
306+
- A2A protocol payloads must be logged and retained under the same redaction
307+
rules as chat/task payloads.
308+
309+
## Non-goals
310+
311+
- Replacing `agent_loop` with ADK.
312+
- Moving provider routing into ADK.
313+
- Treating remote A2A agents as model providers.
314+
- Removing ACP support for local coding-agent CLIs.
315+
- Removing MCP support for tools and editor control-plane integrations.
316+
- Publishing a public A2A registry or marketplace.
317+
- Supporting hosted multi-user A2A semantics in the first version.
318+
- Implementing A2A push notifications in the first version.
319+
320+
## Implementation Plan
321+
322+
1. **Dependency audit.** Inspect `a2a-go`, ADK Go, and their dependency trees.
323+
Decide whether Hecate should use an SDK or define a narrow internal adapter.
324+
2. **Protocol fixtures.** Add JSON fixtures for Agent Cards, `SendMessage`,
325+
streaming status updates, artifact updates, cancellation, and auth errors.
326+
3. **Agent Card endpoint.** Add a token-protected Hecate Agent Card endpoint
327+
with conservative skills and no sensitive workspace/project data.
328+
4. **Server adapter spike.** Implement `SendMessage`, `GetTask`, `CancelTask`,
329+
and `SendStreamingMessage` against existing task/chat APIs in a narrow
330+
package.
331+
5. **Stream projection.** Reuse existing task-run/chat SSE projection. Do not
332+
fork a second event source.
333+
6. **Remote A2A readiness.** Add a direct-config remote Agent Card probe in
334+
Connections without broad discovery.
335+
7. **Remote A2A External Agent.** Treat a configured remote A2A service as an
336+
External Agent target, with transcript, diagnostics, cancellation, and
337+
`external` usage semantics.
338+
8. **ADK interop smoke.** Use a tiny ADK A2A sample as a manual or optional e2e
339+
smoke to prove Hecate can consume ADK-built agents through A2A.
340+
341+
## Open Questions
342+
343+
- Should the public-looking `/.well-known/agent-card.json` endpoint exist at all
344+
before hosted/multi-user hardening, or should Hecate start only with
345+
`/hecate/v1/a2a/agent-card`?
346+
- Should A2A `taskId` be the Hecate run id, or a new protocol-specific id that
347+
references both task id and run id?
348+
- Should a Hecate Chat session and a Hecate task share one A2A `contextId`
349+
namespace?
350+
- How should Hecate represent approval grants and repeated approvals in A2A
351+
without leaking internal policy details?
352+
- Which artifacts should be exposed to A2A clients by default, and which should
353+
require explicit operator selection?
354+
- Is the official A2A Go SDK stable enough for Hecate's release cadence, or is
355+
a narrow internal JSON-RPC implementation safer for the first spike?
356+
- What minimal ADK-compatible export/import shape would help users without
357+
implying Hecate is an ADK runtime?

0 commit comments

Comments
 (0)