PRD: Agentic Peer Discovery Recipe

gistfile1.txt

# PRD: Agentic Peer Discovery Recipe

## Summary

Build a local-first agentic network pattern where agents can discover nearby peer capabilities, validate them over MCP, cache verified state, and route tasks without hardcoded peer URLs.

This is a recipe for teams that want composable agent systems before they want a platform.

## Product Thesis

Agent networks should start like local ecosystems, not cloud marketplaces.

The first useful version does not need global identity, distributed scheduling, or internet-scale service discovery. It needs a reliable loop:

1. A peer advertises that it exists.
2. A coordinator discovers it as a candidate.
3. The coordinator validates the peer through the real protocol.
4. The coordinator caches verified capabilities.
5. A router selects an approved, healthy peer for a task.
6. A monitor explains what the network believes is true.

## Target Users

- Agent developers building multi-agent workflows.
- Platform engineers evaluating MCP-based internal tools.
- AI product teams that need modular agents without central orchestration.
- Research teams prototyping local or lab-contained agent swarms.
- Enterprise teams that want discoverability without exposing agents publicly.

## Core Use Case

A customer-service agent receives a refund question. It needs research, but it should not embed researcher logic or hardcode a researcher URL.

Instead, it discovers a nearby research agent, verifies that the peer exposes a `research_topic` tool, calls it with fake or internal data, and writes a customer-facing answer.

## Product Principles

- Discovery is not trust.
- Metadata is a hint; live MCP capabilities are the source of truth.
- Route to verified capabilities, not peer names.
- Local caches are operational state and need repair semantics.
- Liveness must be explicit and visible.
- Human review belongs in the trust loop.
- Monitoring should report facts it can actually observe.
- Static fallback is a feature, not a failure.

## Functional Requirements

### 1. Peer Advertisement

Peers advertise an MCP Streamable HTTP endpoint over mDNS/DNS-SD.

Minimum service shape:

```text
service_type: _mcp-agent._tcp.local.
instance_name: <agent_id>
host: <ip-or-hostname>
port: <mcp-port>
path: /mcp
txt:
  agent_id: researcher-01
  role: research
  skills: research,policy_lookup
  auth: optional|token|required
  version: 0.1.0
```

TXT metadata must never contain secrets.

### 2. Candidate Discovery

The coordinator discovers candidate peers from:

- mDNS/DNS-SD
- static YAML config
- future providers such as Tailscale, DNS SRV/TXT, Kubernetes, or a cloud registry

All discovery providers return the same candidate shape. Discovery source must not bypass validation or approval.

### 3. MCP Validation

For each candidate, the coordinator validates:

- MCP session can initialize.
- `agent_hello` or equivalent identity tool works.
- `resource://agent/manifest` can be read when available.
- `tools/list` returns callable tools.
- `resources/list` and `resources/templates/list` return usable context.
- `prompts/list` returns declared prompt interfaces.

The live server response overrides discovery metadata when they disagree.

### 4. Capability Cache

Validated peers are stored in a local registry.

Minimum cached state:

- `agent_id`
- `url`
- `source`
- `role`
- `skills`
- `auth_mode`
- `healthy`
- `approved`
- `review_required`
- `last_seen_at`
- `last_validated_at`
- verified tools, resources, templates, and prompts
- manifest hash or capability snapshot hash

If rediscovery changes a peer URL, reset health and authentication state until validation succeeds again.

### 5. Trust Policy

Support three initial modes:

- `auto_discovered`: validated peers are routable.
- `approved_only`: validated peers are cached but blocked until approved.
- `auto_discovered_with_denylist`: validated peers are routable unless denied.

If an approved peer changes verified capabilities, mark it `review_required` and block routing until accepted.

### 6. Routing

The router selects peers by capability, not by hardcoded agent ID.

Routing inputs:

- required skill
- tool name
- resource URI or template
- prompt name
- approval state
- health state
- freshness
- optional source priority

First version can be deterministic and simple. Prefer exact capability match over scoring cleverness.

### 7. Liveness

mDNS peers beacon by reappearing in discovery. Default beacon assumption: 60 seconds.

Default offline timeout: 120 seconds.

Static peers do not imply liveness. They are configured candidates that still need validation.

### 8. Monitoring

Provide two monitor modes:

- Text log mode for scripts and terminals.
- TUI mode for human inspection.

Show:

- discovered peers
- status: healthy, unhealthy, offline, review_required, denied
- source
- URL
- last seen timestamp
- last validated timestamp
- verified capabilities
- recent tool-call events when instrumented

Do not claim passive traffic capture unless traffic is actually proxied or instrumented.

## Non-Functional Requirements

- Runnable locally in two terminals.
- Works with fake deterministic data.
- Does not require a cloud account.
- Does not require external network access.
- Uses public interfaces in tests.
- Keeps secrets out of discovery metadata and local logs.
- Provides static config fallback when mDNS is unavailable.
- Uses small, readable modules with clear seams around networking, storage, and MCP.

## Example User Journey

1. Developer starts a research agent.
2. Research agent publishes `_mcp-agent._tcp.local.`.
3. Developer starts a customer-service agent.
4. Customer-service agent discovers candidates.
5. Coordinator validates the researcher over MCP.
6. Coordinator caches the researcher's verified `research_topic` tool.
7. Customer-service graph routes refund-policy research to the peer.
8. Monitor shows the peer as healthy, last seen, and routable.
9. Research agent stops.
10. Monitor marks the peer offline after the timeout.

## BDD Acceptance Scenarios

```gherkin
Feature: Agentic peer discovery

  Scenario: Coordinator routes to a discovered research peer
    Given a research agent is advertising over mDNS
    When the customer-service agent needs policy research
    Then it discovers the research agent as a candidate
    And validates the peer over MCP
    And routes the research task to the verified research tool

  Scenario: Discovery does not imply trust
    Given approval mode is approved_only
    When an unknown peer is discovered and validated
    Then the peer is cached
    But the peer is not routable until approved

  Scenario: A stale mDNS peer goes offline
    Given a discovered mDNS peer was last seen more than 120 seconds ago
    When the monitor refreshes
    Then the peer is shown as offline

  Scenario: Capability drift requires review
    Given an approved peer exposes one verified tool snapshot
    When the peer later exposes a changed tool list
    Then the peer is marked review_required
    And routing to that peer is blocked until accepted
```

## Prototype Architecture

```text
agent process
  MCP server
  mDNS publisher
  manifest provider

coordinator process
  discovery providers
  MCP validator
  local registry
  capability router
  monitor
  MCP client
```

## Recipe

1. Start with one useful peer role, not a mesh. Example: researcher.
2. Give the peer one obvious tool. Example: `research_topic`.
3. Advertise the peer locally with mDNS.
4. Add static config as a fallback.
5. Validate live MCP capabilities before routing.
6. Store verified capabilities in SQLite.
7. Route by skill and tool name.
8. Add approval and deny states.
9. Add liveness from `last_seen_at`.
10. Add a monitor that explains what the system believes.
11. Add capability drift review.
12. Only then add more discovery providers.

## Out-Of-Scope For The First Version

- Internet-wide agent discovery.
- Automatic execution from unknown peers.
- Passive packet capture.
- Central marketplace semantics.
- Distributed task scheduling.
- End-to-end encrypted transport design.
- Global identity or reputation.

## Open Questions

- Should traffic monitoring be proxy-based, client-instrumented, or both?
- What is the minimum useful peer manifest standard?
- Should peer identity be local-name based, key based, or operator assigned?
- How should routing score freshness, approval, latency, and source priority?
- What is the best contract test kit for third-party peer authors?

## Success Metrics

- A new developer can run two agents locally in under 10 minutes.
- The coordinator can route a task without a hardcoded peer URL.
- The monitor clearly shows which peers are healthy, stale, or blocked.
- Capability drift is visible before it affects routing.
- The system remains useful when mDNS fails by falling back to static config.

## The Bet

The winning primitive is not a giant autonomous agent.

It is a small, inspectable capability that can announce itself, prove what it can do, and be safely routed to by other agents nearby.