Integration tracking: Handler (alDuncanson/Handler) youagent interop guide

[brainsparker]

Target repo: https://github.com/alDuncanson/Handler

Anchor chosen: youagent. Handler is an A2A protocol client (TUI, CLI, MCP server). youagent agents expose a standard A2A server (card discovery, health, JSON-RPC 2.0 message/send, tasks/get, tasks/cancel), so youagent is a natural independent server for Handler users to test interoperability against. Handler removed its built-in embedded agent in alDuncanson/Handler#92, so its quickstart now assumes you bring your own A2A server, which makes this guide directly useful.

Why this repo: 46 stars (preferred 20-200 band), active (multiple merged PRs this week), CI, pytest, ruff, ty, published on PyPI (a2a-handler), Mintlify docs site with an existing guides structure, clear CONTRIBUTING.md, single engaged maintainer.

Candidate evaluation summary (shortlist of 3):

1. alDuncanson/Handler (46 stars, Python) with youagent: SELECTED. Strong activity, genuine fit (A2A client needs real third-party A2A servers), very clean docs-guide path, high testability.
2. echoVic/blade-code (175 stars, TypeScript CLI coding agent, MCP + skills) with you.md: strong fit, but pre-flight failed: the you-md package is not published on npm (registry returns Not found). Revisit after a publish.
3. Birfy/agentdescent (134 stars, Python self-evolving agent framework) with PromptLens: rejected; it already has a strong built-in eval/reward pipeline, so PromptLens would duplicate a core equivalent.

Integration type: documentation/example. New Mintlify guide docs/guides/youagent.mdx (Test Handler against a youagent agent) plus one nav entry in docs/docs.json under the Agent and MCP workflows group. No code, dependency, or default-behavior changes.

Env vars and setup: none required. The youagent example A2A server (examples/a2a-server.ts) runs without credentials; Node 20+ only.

Usage example:

npx tsx examples/a2a-server.ts   # in a youagent checkout, after npm install and npm run build
handler card get --url http://localhost:3141
handler message send --url http://localhost:3141 --text "hello"
handler server add youagent --url http://localhost:3141

Validation performed (2026-08-19):

• Pre-flight: youagent v0.1.0 on npm; npx youagent --version runs clean on Node 24.
• python3 -m json.tool docs/docs.json passes with the nav addition.
• Live loop, server side: cloned youagent, npm install, npm run build, npx tsx examples/a2a-server.ts, then verified GET /.well-known/agent.json (card served), GET /health (status ok), and POST / message/send over JSON-RPC 2.0 (task returned with state completed).
• Not run: Handler CLI commands against the server (validation environment lacks Python 3.11+/uv) and mint docs render. Both disclosed in the PR.

Fallback/error behavior: documentation only; if the youagent server is not running, Handler behaves as with any unreachable server URL.

Links:

• Implementation branch: https://github.com/brainsparker/Handler/tree/feat/youagent-a2a-interop-guide
• Outbound PR: docs: add guide for testing Handler against a youagent A2A server alDuncanson/Handler#119

Status: PR open, awaiting maintainer review.

[brainsparker]

Consolidating results from a second validation pass (thread: interactive continuation of the 2026-08-15 run). Same target repo and anchor were selected independently, so this issue stays the single tracking issue for alDuncanson/Handler.

Correction: youagent latest on npm is v0.0.2 (published 2026-08-13), not v0.1.0 as stated above. Verified against registry.npmjs.org directly. you-md remains unpublished on npm (404), so the you.md anchor stays excluded from pre-flight.

Full-loop validation (2026-08-19, Node 24 + uv-managed Python 3.11):

• npm install youagent (v0.0.2) into a scratch project, minimal serve.mjs using createAgentCard + A2AServer + registerYouAgentHandlers on port 3141.
• GET /.well-known/agent.json, GET /health, and raw JSON-RPC message/send all pass.
• Handler CLI against the live server: card get (pass), card validate (valid: true), message send in pretty and --output json modes (pass), server add + named-server send (pass).

Two interop fixes required for the guide (both found by running the actual Handler client):

1. Handler's client (the a2a SDK) requires card protocolVersion 0.3 or newer. youagent v0.0.2 stamps cards with 0.2.1, which makes every Handler mutation call fail with 'no compatible transports found'. The guide's server script sets card.protocolVersion = "0.3.0" before serving as a workaround.
2. Spec 0.3+ clients send message parts keyed by 'kind' while youagent reads 'type'. The guide's onMessage handler accepts both.

Both are also good upstream fixes for youagent itself (bump the default protocolVersion, accept kind alongside type in the A2A server). Filing those as separate youagent issues is recommended but out of scope for the Handler PR.

Implementation state: branch feat/youagent-a2a-example, rebased on Handler main at 4a9e0db, 2 files changed (+128/-1): docs/guides/youagent.mdx (new Mintlify guide with the validated serve.mjs) and docs/docs.json (one nav entry). Docs only, opt-in, no default-behavior change.

Blocker (both runs): the GitHub integration cannot fork external repositories (403 Resource not accessible by integration on POST /repos/alDuncanson/Handler/forks). Remediation: fork alDuncanson/Handler to the brainsparker account manually (one click at https://github.com/alDuncanson/Handler/fork). Once brainsparker/Handler exists, the integration can push the branch and open the PR. PR link will be added here after that.

[brainsparker]

Final status for this integration.

Outbound PR: alDuncanson/Handler#119 (branch feat/youagent-a2a-interop-guide on the brainsparker/Handler fork)

Follow-up commit pushed (c87bd1a): reworked the guide after running the actual Handler CLI through it. The original draft failed at handler message send with 'no compatible transports found' because youagent 0.0.2 stamps cards with protocolVersion 0.2.1 and Handler's client stack (the a2a SDK) requires 0.3+. The guide now installs youagent from npm, serves via a small serve.mjs that sets card.protocolVersion = "0.3.0", and echoes messages back accepting parts keyed by either kind (spec 0.3+) or type (youagent's own client).

Validation (2026-08-19, against the exact script now in the guide): handler card get, card validate (valid true, protocol 0.3.0), message send in pretty and JSON output modes, server add plus named-server send, curl checks of the card, health, and raw JSON-RPC endpoints, and docs.json JSON parse. Not run: mint render.

Upstream follow-ups for youagent (recommended, separate from the Handler PR):

1. Bump the default card protocolVersion from 0.2.1 to a 0.3+ value so spec-current A2A clients can negotiate a transport without a manual override.
2. Accept message parts keyed by kind alongside type in A2AServer so spec 0.3+ clients' text parts are readable by handlers.

Known tooling limitation for future runs: the GitHub integration cannot comment on or edit PRs in external repositories (403), even ones it authored. Only the fork branch (and therefore the PR diff) can be updated. PR conversation replies need to be posted manually, so future triage runs should surface drafted reply text in the run summary when maintainer feedback arrives on this PR.

Status: awaiting maintainer review.