Skip to content

feat(a2a): add unified queryable team directory - #295

Open
kjgbot wants to merge 4 commits into
mainfrom
factory/294-agentworkforce-relaycast-a93f993c
Open

feat(a2a): add unified queryable team directory#295
kjgbot wants to merge 4 commits into
mainfrom
factory/294-agentworkforce-relaycast-a93f993c

Conversation

@kjgbot

@kjgbot kjgbot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Closes #294

Summary

  • publish @relaycast/a2a as the documented shared agent-card contract
  • merge native Relay agents and registered A2A agents behind /v1/a2a/directory
  • support skill, tag, and free-text discovery while preserving one-hop addressing
  • add SDK support, unit coverage, and a self-hosting real-gateway E2E discover-to-engage round trip

Validation

  • npx turbo test --output-logs=errors-only
  • npx turbo lint --output-logs=errors-only
  • npx turbo build --output-logs=errors-only
  • npm run e2e -- --ci (109 passed, 0 failed)
  • npm pack --workspace @relaycast/a2a --dry-run --json

This PR is ready for human review once the fresh-head checks complete.

@gemini-code-assist

Copy link
Copy Markdown

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

@coderabbitai

coderabbitai Bot commented Jul 21, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@kjgbot, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 025e1778-2785-45ce-9feb-08a920d44c06

📥 Commits

Reviewing files that changed from the base of the PR and between a3a2737 and 4e5cef7.

📒 Files selected for processing (5)
  • .agentworkforce/trajectories/completed/2026-07/traj_etjrrjqq3s0w.trace.json
  • .agentworkforce/trajectories/completed/2026-07/traj_etjrrjqq3s0w/summary.md
  • .agentworkforce/trajectories/completed/2026-07/traj_etjrrjqq3s0w/trajectory.json
  • packages/engine/src/engine/__tests__/a2a.test.ts
  • packages/engine/src/engine/a2a.ts
📝 Walkthrough

Walkthrough

Changes

A2A directory delivery

Layer / File(s) Summary
Directory contract and published package
openapi.yaml, packages/a2a/*, CHANGELOG.md, packages/engine/CHANGELOG.md
Documents the shared A2A contract, adds directory schemas and endpoint documentation, and configures public package publishing.
Directory engine and authenticated route
packages/engine/src/engine/a2a.ts, packages/engine/src/routes/a2a.ts, packages/engine/src/engine/__tests__/a2a.test.ts
Merges native and registered agents, resolves certifications, applies skill/tag/text filters, serves the authenticated endpoint, and tests removed-agent exclusion and empty results.
TypeScript SDK directory access
packages/sdk-typescript/src/*, packages/sdk-typescript/CHANGELOG.md
Adds directory types and RelayCast.listA2aDirectory with query serialization tests.
E2E discovery and engagement flow
scripts/e2e.ts, README.md, .agentworkforce/trajectories/completed/2026-07/...
Boots an isolated gateway, validates directory filtering and discovered-agent messaging, updates event handling and teardown, and records the completed trajectory.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant A2aRoute
  participant A2aEngine
  participant AgentSources
  Client->>A2aRoute: GET /v1/a2a/directory with filters
  A2aRoute->>A2aEngine: listA2aDirectory(query)
  A2aEngine->>AgentSources: Load native agents, registered agents, certifications
  AgentSources-->>A2aEngine: Directory source data
  A2aEngine-->>A2aRoute: Filtered entries
  A2aRoute-->>Client: Directory response
  Client->>A2aRoute: POST /a2a/rpc message/send
  A2aRoute-->>Client: JSON-RPC response
Loading

Possibly related issues

  • Factory issue 139 — Covers skill/tag-filtered A2A directory discovery and engagement using returned entries.

Possibly related PRs

Suggested labels: size:XL

Suggested reviewers: willwashburn, khaliqgant

Poem

A rabbit found agents in rows,
With skills and tags and paths to those.
One hop, a message safely sent,
Through fields the directory meant.
The gateway boots, the tests all cheer—
“A2A friends are gathered here!”

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The .agentworkforce/trajectories/* summary and JSON artifacts are unrelated to the directory and contract work. Remove the trajectory artifacts from the PR unless they are required by repository policy or directly referenced in the issue.
Docstring Coverage ⚠️ Warning Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title succinctly describes the main change: a unified, queryable A2A team directory.
Description check ✅ Passed The description matches the PR scope by summarizing the shared contract, directory endpoint, SDK, tests, and E2E flow.
Linked Issues check ✅ Passed The changes satisfy #294 by adding the shared @relaycast/a2a contract, unified directory/filtering, SDK/docs, tests, and the booted-gateway E2E.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch factory/294-agentworkforce-relaycast-a93f993c

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
packages/engine/src/engine/__tests__/a2a.test.ts (1)

567-611: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Consider covering the certification fallback heuristic.

All directory tests exercise the certificationByUrl.get(...) path (a real certifications row exists for ext-infra-watch). The health-based fallback in listA2aDirectory (agent.last_health && agent.health_failures === 0 ? 'level_1' : 'level_0') has no dedicated test here — worth adding a proxy without a certification row to lock in that behavior.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/engine/src/engine/__tests__/a2a.test.ts` around lines 567 - 611, The
A2A directory tests do not cover certification fallback when no certification
row exists. Extend the setup used by listA2aDirectory/getDirectory with a
registered proxy lacking a certifications entry, then add assertions verifying
it receives level_1 when last_health is present and health_failures is zero (or
level_0 otherwise), while preserving the existing certified-agent coverage.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/engine/src/engine/a2a.ts`:
- Around line 492-543: Filter the workspaceAgents query in the
directory-building flow to select only agent-typed identities, excluding human
and system rows before searchableEntries are constructed. Update the query
associated with workspaceAgents, while preserving the existing registered-relay
and removed-proxy exclusions for valid agents.

---

Nitpick comments:
In `@packages/engine/src/engine/__tests__/a2a.test.ts`:
- Around line 567-611: The A2A directory tests do not cover certification
fallback when no certification row exists. Extend the setup used by
listA2aDirectory/getDirectory with a registered proxy lacking a certifications
entry, then add assertions verifying it receives level_1 when last_health is
present and health_failures is zero (or level_0 otherwise), while preserving the
existing certified-agent coverage.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86c5ccad-8a68-4e2b-ba33-586e86a2a28b

📥 Commits

Reviewing files that changed from the base of the PR and between 6ef105d and a3a2737.

📒 Files selected for processing (16)
  • .agentworkforce/trajectories/completed/2026-07/traj_q5iazxzqfyop/summary.md
  • .agentworkforce/trajectories/completed/2026-07/traj_q5iazxzqfyop/trajectory.json
  • CHANGELOG.md
  • README.md
  • openapi.yaml
  • packages/a2a/README.md
  • packages/a2a/package.json
  • packages/engine/CHANGELOG.md
  • packages/engine/src/engine/__tests__/a2a.test.ts
  • packages/engine/src/engine/a2a.ts
  • packages/engine/src/routes/a2a.ts
  • packages/sdk-typescript/CHANGELOG.md
  • packages/sdk-typescript/src/__tests__/relay.test.ts
  • packages/sdk-typescript/src/relay.ts
  • packages/sdk-typescript/src/types.ts
  • scripts/e2e.ts

Comment thread packages/engine/src/engine/a2a.ts

Copy link
Copy Markdown
Member

Also addressed the review’s certification-fallback coverage note in 0dade133: the directory fixture now includes a healthy registered A2A agent with no certification row and asserts the documented health fallback returns level_1, while retaining explicit-certification coverage. Validation: focused A2A tests 29/29; full test/lint/build green; live E2E 109/109.

Copy link
Copy Markdown
Member

Factory handoff

Ready for human review on 4e5cef7a.

  • CI: Lint/Build/Test and Rust SDK green; CodeRabbit successful; preview cleanup intentionally skipped.
  • Review: the human/system directory leak was fixed in 0dade133, answered in-thread, and resolved; certification fallback coverage was added too.
  • E2E: npm run e2e -- --ci boots an isolated real gateway and passes 109/109, including native + A2A discovery, filters/no-match, and discovered-agent message/send round trip.
  • Merge state: clean and mergeable against current main.

I have not merged this PR. Happy to discuss status, trade-offs, or any open question during human review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A2A team directory: unified, queryable agent discovery + publish @relaycast/a2a as the shared card contract

2 participants