AgentAnycast

AgentAnycast Node

为 AgentAnycast 的 P2P Agent 网络提供支持的核心守护进程。

AgentAnycast Node（agentanycastd）是一个在每台机器上运行的边车守护进程，提供 P2P 网络、端到端加密和 A2A 协议路由。语言 SDK（Python、TypeScript）通过 gRPC 与其通信。

完全去中心化。 在本地网络中，Agent 可通过 mDNS 自动发现彼此，无需任何配置。跨网络通信时，只需一条命令即可部署自己的中继。

功能特性

类别	能力
网络	libp2p（TCP、QUIC、WebTransport）、NATS 传输、mDNS 自动发现、NAT 穿透（AutoNAT + DCUtR + Circuit Relay v2）
安全	端到端 NaCl box 加密（X25519 + XSalsa20-Poly1305）、W3C DID 身份（did:key、did:web、did:dns）、基于技能的 ACL、按对等节点限速
A2A 协议	任务状态机、3 种寻址模式（直接 / 任播 / HTTP 桥接）、流式工件、离线消息队列
互操作	HTTP Bridge（P2P ↔ HTTP A2A）、ANP Bridge（Agent Network Protocol）、MCP 服务（stdio + Streamable HTTP）
企业级	审计日志（JSON Lines）、Prometheus 指标、OpenTelemetry 跟踪（W3C Trace Context、OTLP）
AI 工具	面向 13+ 个 AI 平台的 MCP 服务、可将任意 MCP 服务封装为 P2P Agent 的 MCP 远程代理

快速开始

独立运行——本地网络（无需配置）

go build -o agentanycastd ./cmd/agentanycastd
./agentanycastd
# Agents on the same LAN discover each other automatically via mDNS

搭配 Python SDK 使用

pip install agentanycast

from agentanycast import Node

async with Node(skills=["translate"]) as node:
    # The daemon starts automatically — no manual setup needed
    result = await node.send_task("summarize", "Hello world")

MCP 模式——用作 AI 工具

# stdio mode (Claude Desktop, Cursor, VS Code, Gemini CLI)
./agentanycastd -mcp

# Streamable HTTP mode (ChatGPT, remote clients)
./agentanycastd -mcp-listen :3000

跨网络——部署自己的中继

# On any VPS with a public IP
git clone https://github.com/AgentAnycast/agentanycast-relay && cd agentanycast-relay
docker-compose up -d

# Note the RELAY_ADDR from the logs, then:
./agentanycastd -bootstrap-peers "/ip4/<RELAY_IP>/tcp/4001/p2p/12D3KooW..."

配置

优先级： CLI 标志 > 环境变量 > 配置文件 > 默认值

CLI 标志

标志	说明
-key	身份密钥文件的路径
-grpc-listen	gRPC 监听地址（unix:// 或 tcp://）
-log-level	日志级别（debug、info、warn、error）
-bootstrap-peers	以逗号分隔的引导 multiaddr
-bridge-listen	HTTP bridge 监听地址（例如，:8080）
-enable-webtransport	启用 WebTransport（基于 QUIC，兼容浏览器）
-mcp	通过 stdio 作为 MCP 服务运行
-mcp-listen	MCP Streamable HTTP 监听地址（例如，:3000）
-mcp-proxy	将 MCP 服务命令封装为可通过 P2P 访问的 Agent
-anp-listen	ANP bridge 监听地址（例如，:8090）
-nats-broker	NATS broker URL（例如，nats://broker.example.com:4222）
-otlp-endpoint	分布式跟踪的 OTLP 收集器端点
-metrics-listen	Prometheus 指标监听地址（例如，:9090）
-config	TOML 配置文件的路径
-version	打印版本并退出

环境变量

变量	默认值
AGENTANYCAST_KEY_PATH	~/.agentanycast/key
AGENTANYCAST_GRPC_LISTEN	unix://~/.agentanycast/daemon.sock
AGENTANYCAST_LOG_LEVEL	info
AGENTANYCAST_STORE_PATH	~/.agentanycast/data
AGENTANYCAST_BOOTSTRAP_PEERS	（无）
AGENTANYCAST_ENABLE_MDNS	true
AGENTANYCAST_REGISTRY_ADDRS	（无）
AGENTANYCAST_MCP_LISTEN	（无）

配置文件

默认位置：~/.agentanycast/config.toml

key_path = "~/.agentanycast/key"
grpc_listen = "unix://~/.agentanycast/daemon.sock"
log_level = "info"
log_format = "json"
store_path = "~/.agentanycast/data"
enable_mdns = true
enable_quic = true
enable_webtransport = false
enable_relay_client = true
enable_hole_punching = true
offline_queue_ttl = "24h"
bootstrap_peers = ["/ip4/203.0.113.50/tcp/4001/p2p/12D3KooW..."]

[bridge]
enabled = false
listen = ":8080"
# tls_cert = "/path/to/cert.pem"
# tls_key = "/path/to/key.pem"
# cors_origins = ["*"]

[anycast]
routing_strategy = "random"
cache_ttl = "30s"
auto_register = true
# registry_addr = "relay.example.com:50052"
# registry_addrs = ["relay1:50052", "relay2:50052"]  # federation
enable_dht = false
dht_mode = "auto"   # "auto", "server", or "client"

[metrics]
enabled = false
listen = ":9090"

[mcp]
enabled = false
listen = ":3000"

[anp]
enabled = false
listen = ":8090"

# NATS Transport
[transport.nats]
enabled = true
broker = "nats://broker.example.com:4222"
subject_prefix = "agent."

# Enterprise Policy
[policy]
acl_rules = [
  { source = "*", skill = "*", allow = true },
]

[policy.rate_limits]
default_rps = 100

audit_log_path = "/var/log/agentanycast-audit.jsonl"

# OpenTelemetry
[otel]
enabled = false
otlp_endpoint = "localhost:4317"

[identity]
# did_web = "did:web:example.com:agents:myagent"
# did_dns_domain = "example.com"

架构

┌──────────────────────────────────────────────────────────────────────┐
│                           agentanycastd                              │
│                                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐     │
│  │  Engine   │  │  Router  │  │ Offline  │  │ Anycast Router   │     │
│  │(task FSM) │  │(A2A msg) │  │  Queue   │  │(skill discovery) │     │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────────────┘     │
│       │              │             │              │                   │
│  ┌────┴──────────────┴─────────────┴──────────────┴──────────────┐   │
│  │         Envelope Layer (E2E NaCl box encryption)              │   │
│  ├───────────────────────────────────────────────────────────────┤   │
│  │                    Transport Adapters                         │   │
│  │  libp2p (mDNS · TCP · QUIC · WebTransport · DHT)             │   │
│  │  NATS · HTTP Bridge · Circuit Relay v2 · DCUtR                │   │
│  └──────────────────────┬───────────────────────────────────────┘   │
│                         │                                            │
│  ┌──────────────────────┴──────────────────────────────────────┐     │
│  │                gRPC Server (16 RPCs for SDKs)               │     │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │
│  │ HTTP Bridge│ │ MCP Server │ │ANP Bridge│ │  OTel  │ │MCP Proxy │ │
│  │ (A2A↔P2P) │ │(stdio/HTTP)│ │(ANP↔A2A) │ │(trace) │ │(wrap cmd)│ │
│  └────────────┘ └────────────┘ └──────────┘ └────────┘ └──────────┘ │
│                                                                      │
│  ┌────────┐ ┌──────┐ ┌─────────┐ ┌──────────────────┐               │
│  │Metrics │ │BoltDB│ │  ACL /  │ │   Audit Logger   │               │
│  │(Prom.) │ │(stor)│ │RateLimit│ │   (JSON Lines)   │               │
│  └────────┘ └──────┘ └─────────┘ └──────────────────┘               │
└──────────────────────────────────────────────────────────────────────┘

内部包

包	职责
internal/a2a/	A2A 协议引擎——任务状态机、信封路由、离线队列、流式传输
internal/node/	libp2p 主机——对等节点连接、mDNS、DHT、TCP/QUIC/WebTransport
internal/crypto/	Ed25519 密钥、DID 转换（did:key、did:web、did:dns）、可验证凭证
internal/nat/	AutoNAT、DCUtR 打洞、Circuit Relay v2 客户端
internal/store/	BoltDB 持久化——任务、Agent 卡片、离线队列
internal/config/	TOML 配置、环境变量、CLI 标志
internal/envelope/	协议无关的消息路由、端到端 NaCl box 加密
internal/transport/	可插拔传输适配器——libp2p、NATS、HTTP 桥接
internal/bridge/	HTTP 桥接——在 HTTP JSON-RPC 与 P2P A2A 信封之间转换
internal/anycast/	任播路由器——基于技能的寻址、多注册表联邦、DHT 发现
internal/mcp/	MCP 服务——将 P2P 能力作为 MCP 工具提供（stdio + Streamable HTTP）
internal/mcpproxy/	MCP 远程代理——将外部 MCP 命令封装为 P2P Agent
internal/anp/	ANP 桥接——在 ANP HTTP 与 A2A P2P 之间转换（JSON-RPC 2.0 + JSON-LD）
internal/policy/	企业策略——基于技能的 ACL、按对等节点进行速率限制、审计日志
internal/metrics/	Prometheus 指标——连接、任务、路由、桥接、流式传输、MCP
internal/otel/	OpenTelemetry——分布式追踪、W3C Trace Context、OTLP 导出器
pkg/grpcserver/	gRPC 服务端——面向 SDK 的 16 个 RPC 方法

gRPC API

分组	方法
节点	GetNodeInfo、SetAgentCard
对等节点	ConnectPeer、ListPeers、GetPeerCard
任务客户端	SendTask（peer_id / skill_id / url）、GetTask、CancelTask、SubscribeTaskUpdates
任务服务端	SubscribeIncomingTasks、UpdateTaskStatus、CompleteTask、FailTask
流式传输	SubscribeTaskStream、SendStreamingArtifact
发现	Discover

MCP 服务

该守护进程可以作为 MCP（Model Context Protocol）服务运行，将 P2P 能力作为工具提供给 AI 助手。

工具	描述
toolGetNodeInfo	获取本地节点信息
toolListConnectedPeers	列出已连接的对等节点
toolGetAgentCard	获取本地或远程 Agent 卡片
toolDiscoverAgents	按技能发现 Agent
toolSendTask	按 ID 向对等节点发送任务
toolSendTaskBySkill	按技能发送任务（任播）
toolGetTaskStatus	获取任务状态

传输模式：

• stdio——用于本地 AI 工具集成（Claude Desktop、Cursor、VS Code、Gemini CLI、JetBrains）
• Streamable HTTP——用于远程客户端（ChatGPT）

MCP 远程代理

只需一个标志，即可将任意 MCP 服务封装为可通过 P2P 访问的 Agent：

./agentanycastd --mcp-proxy "npx -y @modelcontextprotocol/server-filesystem /home/user"

该代理会根据 MCP 服务的工具列表自动生成 Agent 卡片，向中继注册技能，并将传入的 A2A 任务桥接为 MCP 工具调用。

HTTP 桥接

提供兼容 A2A 的 HTTP 端点，以实现 P2P 与 HTTP 互操作：

• GET /.well-known/a2a-agent-card——Agent 卡片发现
• POST /——用于任务操作的 JSON-RPC 端点
• 可选支持 TLS 和 CORS

ANP 桥接

提供兼容 ANP 的 HTTP 端点，以实现 Agent Network Protocol 互操作：

• GET /agent/ad.json——Agent 描述（JSON-LD）
• GET /agent/interface.json——OpenRPC 规范
• POST /agent/rpc——JSON-RPC 2.0 端点

可观测性

Prometheus 指标

可通过可配置的 HTTP 端口使用（默认 :9090）：

指标	类型	描述
agentanycast_connected_peers	仪表	当前对等节点数
agentanycast_connections_total	计数器	按方向统计的连接事件
agentanycast_connections_by_transport	计数器	按传输方式统计的连接（tcp/quic/webtransport）
agentanycast_tasks_total	计数器	按方向和状态统计的任务
agentanycast_task_duration_seconds	直方图	任务延迟
agentanycast_route_resolutions_total	计数器	按结果统计的 Anycast 解析
agentanycast_bridge_requests_total	计数器	HTTP 桥接请求
agentanycast_stream_chunks_total	计数器	按方向统计的流式数据块
agentanycast_messages_total	计数器	按信封类型统计的 A2A 消息
agentanycast_offline_queue_size	仪表	排队中的离线消息
agentanycast_mcp_tool_calls_total	计数器	按工具和状态统计的 MCP 工具调用
agentanycast_acl_decisions_total	计数器	ACL 允许/拒绝决策
agentanycast_rate_limit_rejections_total	计数器	被限流的请求

OpenTelemetry

通过 W3C Trace Context 传播实现分布式追踪。Span 涵盖任务生命周期、传输跳转和信封加密。

./agentanycastd --otlp-endpoint localhost:4317

构建

make build              # Build agentanycastd binary -> bin/
make test               # Run all tests (unit + integration, -race)
make test-unit          # Unit tests only (-short)
make test-integration   # Integration tests only
make lint               # golangci-lint
make cross-compile      # Build for darwin/linux x amd64/arm64 + windows/amd64

免责声明

本软件按“原样”提供，不作任何形式的保证。本软件使用了密码学技术，在某些司法管辖区可能受出口管制。

许可证

FSL-1.1-ALv2 —— Functional Source License，Version 1.1，未来许可证为 Apache License，Version 2.0。每个版本自发布日期起两年后转换为 Apache 2.0。