Skip to content

feat(examples): add collaborative task e-commerce example (orders/inventory/shipping) - #579

Open
Tehsmash wants to merge 5 commits into
feat/a2acli-collaboratefrom
feat/collaborate-example
Open

Tehsmash wants to merge 5 commits into
feat/a2acli-collaboratefrom
feat/collaborate-example

Conversation

@Tehsmash

Copy link
Copy Markdown
Collaborator

Summary

New e-commerce collaborative task example with three specialist agents.

Modelled on the Go reference at a2aproject/experimental-cpb-slimrpc@3a82760.

Agents

Agent Port Domain
collaborate-orders 9001 Order status, fulfillment
collaborate-inventory 9002 Stock levels, restock timelines
collaborate-shipping 9003 Tracking status, delivery estimates

All agents use hardcoded data and keyword matching — no LLM required. Each responds only to queries about its own domain.

Example session

# Start each agent in a separate terminal
cargo run --bin collaborate-orders    --package examples
cargo run --bin collaborate-inventory --package examples
cargo run --bin collaborate-shipping  --package examples

# Query all three
a2acli collaborate \
  --agent http://localhost:9001 \
  --agent http://localhost:9002 \
  --agent http://localhost:9003 \
  "Customer ORD-1001 has not received their order — what is going on?"

Expected output:

[orders]    ORD-1001: shipped on 2024-11-15, tracking TRK-9001.
[shipping]  TRK-9001: delayed — weather event in Memphis.
[inventory] P-500 Wireless Headphones: oversold by 2 units.

Key components

  • fan_in.rs — FanInHandler<H> wraps any RequestHandler. When send_message arrives with a task_id that has an active inbox, the message is routed to the executor's inbox channel instead of starting a new execution.
  • agent.rs — CollabExecutor registers its inbox on start, reads relay messages from it, and both required extension URIs are declared in the AgentCard.
  • server.rs — shared startup: creates InboxRegistry, passes it to both executor and handler.

Depends on #578. Closes #573. Part of #569.

@Tehsmash
Tehsmash requested a review from a team as a code owner November 20, 2026 12:08
@Tehsmash
Tehsmash force-pushed the feat/collaborate-example branch from 076f23c to f5610c4 Compare November 20, 2026 13:33
@Tehsmash
Tehsmash force-pushed the feat/a2acli-collaborate branch 2 times, most recently from ba6256d to c325d00 Compare November 20, 2026 16:16
E-commerce scenario with three specialist agents (orders, inventory,
shipping), mirroring the Go reference at:
a2aproject/experimental-cpb-slimrpc@3a82760

Agents have hardcoded domain data (no LLM) and respond only to queries
that touch their domain via keyword matching:
- orders:    ORD-1001 status, tracking numbers
- inventory: P-500 Wireless Headphones stock levels
- shipping:  TRK-9001 tracking and delay information

New files:
- examples/src/collaborate/fan_in.rs — FanInHandler RequestHandler
  middleware that routes relay messages into the active executor's inbox
  channel instead of starting new executions
- examples/src/collaborate/agent.rs — CollabExecutor with both required
  extension URIs declared in AgentCard capabilities
- examples/src/collaborate/server.rs — shared server startup logic
- examples/src/collaborate/{orders,inventory,shipping}.rs — binary entry
  points (ports 9001, 9002, 9003)

Usage:
  # Terminal 1-3: start each agent
  cargo run --bin collaborate-orders    --package examples
  cargo run --bin collaborate-inventory --package examples
  cargo run --bin collaborate-shipping  --package examples

  # Terminal 4: query all three
  a2acli collaborate \
    --agent http://localhost:9001 \
    --agent http://localhost:9002 \
    --agent http://localhost:9003 \
    "Customer ORD-1001 has not received their order"

Closes #573. Part of #569.

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
- Remove unused `a2a-collab` dependency from examples/Cargo.toml
  (the examples implement server-side FanIn; they do not use the
  relay helpers from a2a-collab)
- Fix clippy::while_let_loop in collaborate/agent.rs
- Fix clippy::collapsible_if in collaborate/agent.rs and fan_in.rs
- Fix rustfmt violations across examples, a2a-collab, a2a, a2acli
- Fix broken external link in a2acli/README.md
  (a2a-cli/specification/SPEC.md was removed; link to repo root)

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
…b client API

Adds examples/src/collaborate/client.rs — a standalone binary that shows
programmatic use of the a2a-collab crate client-side:

- require_collaborative_extensions() pre-flight-checks each AgentCard
- Opens one streaming connection per agent
- Merges all streams with futures::stream::select_all
- Relays every StreamResponse to peer agents via translate_peer_response()
- Echo suppression: never routes an event back to its originator
- Sets return_immediately=true on all relay send_message calls

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
…ssion

Replace the manual relay loop with CollaborativeSession::new(agents).start().
The example now only handles rendering — all relay orchestration lives in
a2a-collab as intended.

Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
@Tehsmash
Tehsmash force-pushed the feat/collaborate-example branch from f5610c4 to 89bd666 Compare November 20, 2026 16:19

This branch has not been deployed

No deployments
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.

1 participant