π«π· Version franΓ§aise
A2A protocol β conformance matrix
Honest position of Orkeon's A2A implementation (marked [Experimental],
diagnostic ORKEXP001) against the A2A specification v1.0 (Linux
Foundation / a2aproject). Summary: the implementation belongs to the 0.x
era of the protocol β a compact REST surface plus SSE streaming β and covers
the core send/stream/status/cancel loop; the v1.0 binding formalism (JSON-RPC,
gRPC, HTTP+JSON mappings of the canonical proto schema), push notifications
and the richer task lifecycle are not implemented. This page is the reference
for what interoperates and what does not.
Abstract operations (spec Β§core)
| v1.0 operation | Orkeon endpoint | Status | Notes |
|---|---|---|---|
| Send Message | POST /a2a/tasks/send |
π‘ Partial | 0.x-era shape (A2ATaskRequest: id/skillId/input/inputMode/metadata), not the v1.0 Message/Part data model. The skillId is the id of a skill on the agent card; the agent runs and the response carries its output β see Task execution. |
| Send Streaming Message | POST /a2a/tasks/sendSubscribe (SSE) |
π‘ Partial | Working β one Working update per progress line the router reports, the line in message β final update β [DONE]; no TaskStatusUpdateEvent/TaskArtifactUpdateEvent typed events, no keep-alive. |
| Get Task | GET /a2a/tasks/{id} |
π‘ Partial | Real when task persistence is enabled (AddOrkeonA2ATaskPersistence() over a checkpointing IStateStore): 200 with the recorded state, 404 for unknown ids. Without the opt-in: explicit 501 (never fabricated state). |
| List Tasks | β | π΄ Absent | |
| Cancel Task | DELETE /a2a/tasks/{id} |
π‘ Partial | A task the agent is still working on is interrupted: its execution token is cancelled and the submitting request answers Cancelled. With persistence, a record left Working by a stopped server flips to Cancelled; a finished task answers 409 and keeps its state. Unknown ids (or, without persistence, any task not running) answer 404. |
| Subscribe to (existing) Task | β | π΄ Absent | Streaming exists only at submission time. |
| Push Notification Configs (create/get/list/delete) | β | π΄ Absent | No webhook delivery. |
| Get Extended Agent Card | β | π΄ Absent | Single public card only. |
Data model
| v1.0 concept | Orkeon | Status |
|---|---|---|
Task states (9: incl. SUBMITTED, INPUT_REQUIRED, AUTH_REQUIRED, REJECTED) |
5 states (Pending, Working, Completed, Failed, Cancelled) |
π‘ Terminal states map 1-1; the interrupted states have no equivalent. |
Message / Part (text, file, data parts) |
input string + inputMode MIME hint |
π‘ Text-first; no multi-part payloads. |
| Artifacts | output string |
π‘ Single textual output. |
| AgentCard | GET /.well-known/agent.json |
π‘ Served with name/description/skills; v1.0 fields (capabilities, securitySchemes, securityRequirements, supportedInterfaces, signatures) absent. |
AgentCard discovery path (/.well-known/agent-card.json) |
/.well-known/agent.json |
π΄ The v1.0 well-known path is not served; a client following the convention gets a 404 before any binding question arises. |
A2A-Version service parameter |
β | π΄ Not read; there is no version negotiation. |
Bindings
v1.0 defines three canonical bindings (JSON-RPC 2.0, gRPC, HTTP+JSON) mapped from the proto schema. Orkeon speaks its own 0.x-era REST dialect β none of the three canonical bindings β so v1.0-strict clients will not interoperate without an adapter. Aligning on the HTTP+JSON binding is the natural first step when this surface is promoted.
Security
| Requirement | Orkeon | Status |
|---|---|---|
| Client identity verification | mTLS (fail-closed: RequireMutualTls refuses to start without a trust anchor; CA chain or pinned thumbprints; 403 on failure) + AllowedAuthSchemes (401): a Bearer token validated by an IAuthenticationProvider (Azure AD, OIDC, or the host's), an ApiKey compared in constant time with the secrets named by ApiKeySecretNames; a scheme declared without a validator refuses to start |
π’ Both credentials are validated, not just matched. A2AClient sends its own (ClientAuthScheme + ClientCredentialSecretName, below). |
| Agent card access | GET /.well-known/agent.json |
π’ Public by design: the security checks apply to the task endpoints only. |
securitySchemes declaration in the AgentCard |
β | π΄ Schemes are enforced but not advertised. |
| Certificate revocation | Not checked | π‘ Decision: prefer short-lived certificates over CRL/OCSP. The A2A mTLS trust model targets private CAs, where CRL/OCSP endpoints rarely exist and OCSP adds an availability dependency; a 24β72 h certificate lifetime bounds the exposure window with no new runtime dependency, and rotation already fits the existing options (a new client instance picks up the new PFX). CRL support stays out of scope until a deployment proves the need. |
| Push-notification webhook auth | β | π΄ No webhooks. |
Task execution
The router decides what the card publishes: GET /.well-known/agent.json lists
the skills of the registered IA2ATaskRouter (GetSkillsAsync), so the key a peer
reads is the key the router compares. A2ATaskRouter, the router the opt-in
registers, runs the agent the request names. It lists one skill per available
agent (id β id, role β name, goal β description, text/plain in and out),
and the request's skillId must equal one of those ids exactly β the role is
not a key, and writer never selects Ghostwriter. The agent then works on an ad hoc task whose
description is the request's input (its metadata become the task variables),
through the host's IAgentExecutionService, resolved in the request's own DI
scope:
- the agent succeeds β
Completed,outputis what it produced; - it fails or throws β
Failed,erroris its error; - the request's token fires (
DELETE /a2a/tasks/{id}, or the server stopping) βCancelled; - no agent publishes that id, the input is empty, or the host registered no
execution service (
AddOrkeonApplication()does) βFailed, saying which.
Progress. RouteTaskAsync(request, progress, ct) receives the progress a
sendSubscribe follows β null for send. Each line the router reports reaches
the peer, in order, as a Working update carrying it as its message
(partialOutput stays the output). The stream has one writer: the lines queue,
and the queue closes when the router answers, so a line reported after that is
dropped rather than sent after the final state; a peer that leaves mid-task reads
no more progress, and the task still runs to its end and is recorded.
A2ATaskRouter reports nothing β one agent turn has no step to report;
orkeon-host's router reports the lines a chat thread reads.
Nothing answers Completed without the agent having run. A host that routes
differently registers its own IA2ATaskRouter before calling AddOrkeonA2A: the
default router is registered only when none is, and with it the agent directory
it finds agents in (the process-wide IAgentRegistrationStore, see
Opt-in subsystems) β a host with its own router keeps
its own IAgentRepository. orkeon-host does exactly
that: one skill per crew it exposes, a task being a run of that crew β see
Service host. Requests are
served concurrently, so a DELETE reaches a task the agent is still working on.
Activation
orkeon-host turns A2A on for the crews Orkeon:Host:A2A exposes β Enabled,
Host, Port and Crews, its own section; one skill per exposed crew, a task
being a run of that crew under its mounts and concurrency bound β see
Service host. orkeon run
and the REPL do not: a single run has nothing to listen for.
An embedding host opts in with AddOrkeonA2A(configuration) (sections A2A and
A2A:Security) or AddOrkeonA2A(configure, configureSecurity), plus
AddOrkeonA2ATaskPersistence() for durable task records. With EnableServer,
the extension also registers a hosted service: a generic host starts the server
with itself and stops it on shutdown, with no start-up code of its own; a start
failure (a declared scheme without a validator, mutual TLS without a trust
anchor) fails the host's start. See Opt-in subsystems.
A2A key |
Default | Effect |
|---|---|---|
EnableServer |
false |
Registers IA2AServer (an HttpListener on Host:Port) and the hosted service that runs it. |
Host, Port |
http://localhost, 5002 |
The listener prefix. |
AgentName, AgentDescription, AgentVersion, Organization, ContactUrl |
Orkeon, Orkeon A2A Agent, empty, β, β |
The agent card. An empty AgentVersion is the version of the running release. |
TimeoutSeconds |
30 |
Client request timeout. |
orkeon-host takes its listener from Orkeon:Host:A2A and refuses
A2A:EnableServer, A2A:Host and A2A:Port at start; it reads the rest of the
section β the card's identity, and A2A:Security β as above.
A2A:Security carries ClientCertificatePath/ClientCertificatePassword (the
client's own certificate), TrustedCertificateAuthorities,
TrustedClientCertificateThumbprints, RequireMutualTls, AllowedAuthSchemes and
ApiKeySecretNames, plus the bearer validators A2A:Security:AzureAD and
A2A:Security:Oidc (registered by AddOrkeonA2A(configuration) when filled in).
Client side, ClientAuthScheme (Bearer or ApiKey) and
ClientCredentialSecretName make A2AClient send Authorization: <scheme> <secret>
on every task call, the secret read through ISecretProvider each time; a call
whose credential cannot be read fails before anything is sent. Card discovery
(IA2AAgentDiscovery) stays anonymous.
IA2AClient and IA2AAgentDiscovery serve a C# host that calls a peer; no
shipped agent tool calls one.
Where this leaves consumers
- Orkeon β Orkeon across processes/hosts: the wire works end to end β card,
send (the agent runs), stream, status, cancel (in-flight work stops), mTLS and
bearer/API-key credentials on both sides β with durable task status under the
persistence opt-in. A C# host enables it for its agents,
orkeon-hostfor the crews it exposes (without task records: itsGETanswers501). - Orkeon β third-party v1.0 agents: not yet β wait for (or contribute to) the HTTP+JSON binding alignment.
Every gap above is deliberate scope, not an oversight: the surface is marked
[Experimental] (ORKEXP001) precisely so it can be reshaped toward v1.0
without a breaking-change debt. See also
Experimental APIs and
Limits and constraints.