RockBot as A2A peer: agent card advertisement and inbound task handling

[rockfordlhotka]

Current state

RockBot currently calls AddA2ACaller() only, making it a pure caller in the A2A model:

• It subscribes to discovery.announce to discover peer agents
• It publishes AgentTaskRequest to invoke external agents
• It receives results back on agent.response.RockBot

It does not advertise itself on the discovery bus, and has no subscription on agent.task.RockBot. An external agent trying to send RockBot a task request would publish to agent.task.RockBot but no queue is bound to that topic — the message is dropped.

Goal

Make RockBot a full A2A peer so that:

1. Other agents can discover RockBot — it publishes an AgentCard on discovery.announce at startup (and periodically via the re-announce loop)
2. Other agents can initiate tasks with RockBot — it subscribes to agent.task.RockBot and handles incoming AgentTaskRequest messages

The hard design question: what does an inbound task mean for a conversational agent?

Unlike SampleAgent (stateless, task-in / result-out), RockBot is conversational — it has an active user session, working memory, and an ongoing dialogue. When an external agent sends an AgentTaskRequest, there are several ways to handle it:

Option A: Inject into the active user session

Treat the inbound task like a synthetic user message — add it to the current conversation and run the LLM loop. The response goes back to the calling agent via ReplyTo and is also relayed to the human user.

• Pros: RockBot can use all its tools, memory, and context to respond; the user stays in the loop
• Cons: Interleaves agent-to-agent work into the user conversation; can be disruptive if the user is mid-task

Option B: Handle in an isolated context (new session)

Create a fresh session ID for the inbound task, run the LLM loop in that context, reply to the calling agent. The human user never sees it.

• Pros: Clean separation; doesn't interrupt the user session
• Cons: RockBot loses access to its long-term memory and user context for the task

Option C: Queue and handle between user turns

Hold inbound agent tasks and process them when the user is idle (similar to how scheduled tasks work today).

• Pros: Doesn't interrupt user flow
• Cons: Adds latency; complex to implement

Option D: Separate skill-based dispatch

Define specific skills in the AgentCard that RockBot advertises. Incoming requests for known skills (e.g. memory-lookup, user-notify) are handled by dedicated lightweight handlers rather than the full LLM loop.

• Pros: Predictable, fast, no LLM cost for simple operations
• Cons: Limited to pre-defined skills; doesn't leverage RockBot's full capabilities

Implementation sketch (once design is decided)

// Program.cs — add alongside AddA2ACaller()
agent.AddA2A(opts =>
{
    opts.Card = new AgentCard
    {
        AgentName = "RockBot",
        Description = "Primary conversational agent.",
        Skills = [ /* TBD based on chosen design */ ]
    };
});
agent.Services.AddScoped<IAgentTaskHandler, RockBotTaskHandler>();

Questions to resolve

• Which option (A–D) fits the intended UX?
• Should the user be notified when another agent contacts RockBot?
• Should inbound agent tasks be reflected in the conversation history?
• What skills should RockBot advertise — general-purpose, or a curated list?

[rockfordlhotka]

I am currently thinking that the way to implement this is as a separate A2A service that exposes the standard http-based A2A interface. This service will be a gateway, managing the interaction between external agents and the internal RabbitMQ-based communication channel with the actual agent. This should provide very clean separation of concerns, and makes the A2A interface totally optional (you either do or don't run this A2A service).

[rockfordlhotka]

Design Plan: Inbound A2A — Make RockBot a Full A2A Peer

Generated from design discussion — captures the agreed approach.

Core Design Principle

RockBot is a conversational personal agent, not a task-processing service. Inbound tasks must be triaged, presented to the user, and only acted upon autonomously when trust has been established through repeated interaction. The answer is a hybrid of Options C and D from the original issue, with an evolutionary trust model.

---

Layered Trust Model

Each caller progresses through four levels independently:

Level	Name	Inbound Behavior	User Involvement	AgentCard Exposure
1	Observe	Read-only access to skills/memory. Writes summary + suggested action to working memory.	User sees everything, decides what to do.	notify-user only
2	Learn	Same as L1, but system observes user responses and proposes skill drafts.	User still decides; system suggests patterns.	notify-user only
3	Propose	System has candidate skills. Asks user "should I auto-handle this next time?"	User approves/rejects skill activation per-caller.	Approved skills added to caller's view
4	Act	Approved skills execute autonomously. Results reported to user.	Post-hoc review only.	Full approved skill set advertised

---

Phase 1: Pluggable Identity Verification

Goal: Define an abstraction for any future identity scheme (JWT, OAuth, OBO tokens, agent registry) via DI. Ship with a name-based prototype.

• IAgentIdentityVerifier — receives the full MessageEnvelope (headers, source, body), returns VerifiedAgentIdentity or throws. Implementations can inspect tokens, signatures, certificates, or any combination.
• VerifiedAgentIdentity — sealed record with AgentId (stable canonical ID), DisplayName, Issuer, Claims (extensible dictionary), IsSelfAsserted flag.
• NameBasedAgentIdentityVerifier — prototype default. Trusts envelope.Source at face value, returns IsSelfAsserted = true.
• IdentityVerificationMiddleware — plugs into the existing IMiddleware pipeline. Verifies identity on A2A-related messages, stores result in context.Items["verified-identity"]. Dead-letters unverifiable messages.
• Registered via DI; users override with their own implementation.

New files: IAgentIdentityVerifier.cs, VerifiedAgentIdentity.cs, NameBasedAgentIdentityVerifier.cs, IdentityVerificationMiddleware.cs

Phase 2: Trust Model

Goal: Per-caller trust tracking with four levels, persisted across restarts.

• AgentTrustLevel enum: Observe, Learn, Propose, Act
• AgentTrustEntry record: AgentId, Level, ApprovedSkills, FirstSeen, LastInteraction, InteractionCount
• IAgentTrustStore interface: GetOrCreateAsync, UpdateAsync, ListAsync
• FileAgentTrustStore — JSON file persistence (follows AgentDirectory/known-agents.json pattern). New callers start at Observe.

New files: AgentTrustLevel.cs, AgentTrustEntry.cs, IAgentTrustStore.cs, FileAgentTrustStore.cs

Phase 3: Inbound Task Handler (RockBotTaskHandler)

Goal: Wire RockBot as an A2A receiver with trust-level-aware behavior.

• Add AddA2A() alongside existing AddA2ACaller() in Program.cs
• Configure AgentCard with initial skills: notify-user, query-availability
• RockBotTaskHandler implements IAgentTaskHandler:
  1. Extracts VerifiedAgentIdentity from middleware context
  2. Looks up caller's trust level
  3. Level 1 (Observe): Read-only LLM pass via AgentLoopRunner.RunAsync with restricted tool set (memory read, skill listing, working memory scoped to a2a-inbox/ namespace). Writes summary + suggested action to working memory. Queues user notification. Returns ack to caller.
  4. Level 4 (Act): Executes approved skills autonomously, reports results post-hoc.
  5. Levels 2-3: Same handler behavior as L1; the dream/skill-learning system uses interaction history differently (deferred to Phase 7).
• InboundA2AToolSet — assembles the restricted read-only tool list for Level 1 processing.

New files: RockBotTaskHandler.cs, InboundA2AToolSet.cs

Phase 4: Idle Detection & Notification Queue

Goal: Accumulate A2A notifications and present them at appropriate times, batched.

• IInboundNotificationQueue — EnqueueAsync, DrainAsync, PendingCount
• InboundNotificationService (hosted service) — monitors IUserActivityMonitor + ISessionTracker for idle state (~2 minute window). When idle with pending notifications:
  • Single notification: "Agent X reached out: [summary]. Suggested action: [action]."
  • Multiple: "While you were away, N agents reached out:" + numbered list
  • Published as uncorrelated AgentReply with SessionId = "a2a-inbound" — hits the unsolicited reply path in UserProxyService

New files: IInboundNotificationQueue.cs, InboundNotification.cs, InboundNotificationService.cs, InboundNotificationQueue.cs

Phase 5: Blazor UI — A2A Visual Treatment

Goal: A2A notifications are visually distinct from regular conversation.

• MessageCategory.A2AActivity already exists in the enum; collapsible bubble rendering already exists
• Update BlazorUserFrontend.CategorizeReply to route a2a-inbound session messages to A2AActivity
• Add distinct icon (network/link, not robot), distinct accent color, batch framing header, "Inbound A2A" badge
• Add A2A indicator to header alongside existing subagent/scheduled-task indicators

Phase 6: Built-in Skills

Two default skills that bypass the LLM loop entirely:

• notify-user — pass-through: writes to A2A inbox, queues notification, returns ack
• query-availability — checks IUserActivityMonitor + ISessionTracker, returns structured busy/available/away

Phase 7: Skill Learning & Trust Progression (Future)

• Dream/skill-dream system observes A2A inbox + user responses, proposes skill drafts (L2)
• Validated drafts presented to user for approval (L3)
• Approved skills execute autonomously (L4), revocable by user
• Per-caller AgentCard tailoring (initially advertise superset, enforce at runtime)
• Registry-backed identity via IAgentIdentityVerifier replacement (agentregistry integration)

---

Implementation Order

Step	Phase	Scope	Dependencies
1	Phase 1	Identity verification abstraction + name-based default	None
2	Phase 2	Trust model + file-backed store	Phase 1
3	Phase 3	RockBotTaskHandler (Level 1) + wire AddA2A()	Phases 1, 2
4	Phase 6	Built-in skills (notify-user, query-availability)	Phase 3
5	Phase 4	Idle detection + notification queue	Phase 3
6	Phase 5	Blazor UI A2A treatment	Phase 4
7	Phase 7	Skill learning + trust progression	All above

Steps 1-4 = initial PR (issue #99). Steps 5-6 = follow-up PR. Step 7 = separate track.

---

Key Design Decisions

1. Session isolation — Inbound tasks get isolated sessions with read access to long-term memory, not injected into the user's active conversation.
2. Pluggable identity — IAgentIdentityVerifier receives the full envelope; implementations can evaluate JWT, OAuth, OBO tokens, registry credentials, or any combination. Registered via DI.
3. Trust is per-caller, per-skill — Agent X at Level 4 for query-availability while Agent Y is at Level 1 for everything.
4. AgentCard: advertise superset, enforce at runtime — avoids changing the discovery protocol. Callers get clear rejection with reason if they invoke a skill they haven't been trusted for.
5. Idle-aware batched notifications — 2-minute idle window, batch multiple notifications, clear A2A framing in UI.