anp 0.8.4

An SDK that enables agents to connect with each other, allowing them to perform identity authentication, end-to-end encrypted communication, automatic protocol negotiation based on LLMs, and efficient data exchange.

English | 中文

AgentConnect

What is AgentConnect

AgentConnect is an open-source SDK implementation of the Agent Network Protocol (ANP).

The goal of Agent Network Protocol (ANP) is to become the HTTP of the Intelligent Agent Internet Era, building an open, secure, and efficient collaborative network for billions of intelligent agents.

🔐 Add DID Authentication to Your Agent

Want to add decentralized identity authentication to your agent? Check out the DID WBA Authentication Integration Guide to quickly add DID WBA authentication to any Python HTTP service.

Current DID-WBA defaults

• Path DID creation defaults to e1_: create_did_wba_document() now creates path-based DIDs using an Ed25519 Multikey binding key by default.
• HTTP Message Signatures are the default request auth format: DIDWbaAuthHeader now emits Signature-Input / Signature (and Content-Digest when needed) by default.
• Legacy compatibility mode remains supported: use auth_mode="legacy_didwba" when interoperating with older clients that still rely on the previous Authorization-header flow.
• Access tokens are returned via Authentication-Info: the server also emits a compatibility Authorization: Bearer ... response header during the migration window.
• Resolver behavior is stricter now:
  • resolve_did_wba_document() always validates DID/document key binding for e1_ and k1_
  • for e1_, proof is part of the binding check and must be a valid DataIntegrityProof using eddsa-jcs-2022
  • for k1_, proof remains optional unless verify_proof=True; in strict mode, the proof verification method must also be the binding key

---

🚀 Quick Start - Build an ANP Agent in 30 Seconds

OpenANP is the simplest way to build ANP agents. Here's a complete server in just a few lines:

Server (3 Steps)

from fastapi import FastAPI
from anp.openanp import AgentConfig, anp_agent, interface

@anp_agent(AgentConfig(
    name="My Agent",
    did="did:wba:example.com:agent",
    prefix="/agent",
))
class MyAgent:
    @interface
    async def hello(self, name: str) -> str:
        return f"Hello, {name}!"

app = FastAPI()
app.include_router(MyAgent.router())

Run: uvicorn app:app --port 8000

Client (3 Lines)

from anp.openanp import RemoteAgent

agent = await RemoteAgent.discover("http://localhost:8000/agent/ad.json", auth)
result = await agent.hello(name="World")  # "Hello, World!"

Generated Endpoints

Endpoint	Description
GET /agent/ad.json	Agent Description document
GET /agent/interface.json	OpenRPC interface document
POST /agent/rpc	JSON-RPC 2.0 endpoint

📖 Full examples: OpenANP Examples

---

Two Ways to Use ANP SDK

🔧 Option 1: OpenANP (Recommended - Building Agents)

The most elegant and minimal SDK for building ANP agents:

from anp.openanp import anp_agent, interface, RemoteAgent

# Server: Build your agent
@anp_agent(AgentConfig(name="Hotel", did="did:wba:...", prefix="/hotel"))
class HotelAgent:
    @interface
    async def search(self, query: str) -> dict:
        return {"results": [...]}

# Client: Call remote agents
agent = await RemoteAgent.discover("https://hotel.example.com/ad.json", auth)
result = await agent.search(query="Tokyo")

Features:

• Decorator-based: @anp_agent + @interface = complete agent
• Auto-generated: ad.json, interface.json, JSON-RPC endpoint
• Context Injection: Automatic session and DID management
• LLM Integration: Built-in OpenAI Tools format export

📖 Full Documentation: OpenANP README

---

🔍 Option 2: ANP Crawler (Document Fetching)

Crawler-style SDK for fetching and parsing ANP documents (like a web crawler for ANP):

from anp.anp_crawler import ANPCrawler

# Initialize crawler with DID authentication
crawler = ANPCrawler(
    did_document_path="path/to/did.json",
    private_key_path="path/to/key.pem"
)

# Crawl agent description and get OpenAI Tools format
content, tools = await crawler.fetch_text("https://example.com/ad.json")

# Execute discovered tools
result = await crawler.execute_tool_call("search_poi", {"query": "Beijing"})

# Or call JSON-RPC directly
result = await crawler.execute_json_rpc(
    endpoint="https://example.com/rpc",
    method="search",
    params={"query": "hotel"}
)

Features:

• Crawler Style: Fetch and parse ANP documents like a web crawler
• OpenAI Tools Format: Converts interfaces for LLM integration
• Direct JSON-RPC: Call methods without interface discovery
• No LLM Required: Deterministic data collection

📖 Full Documentation: ANP Crawler README

---

RemoteAgent vs ANPCrawler

Feature	RemoteAgent	ANPCrawler
Style	Proxy object (like local methods)	Crawler (fetch documents)
Usage	agent.search(query="Tokyo")	crawler.execute_tool_call("search", {...})
Type Safety	Full type hints, exceptions	Dict-based returns
Best For	Agent-to-agent calls in code	LLM tool integration, data collection

# RemoteAgent: Methods feel like local calls
agent = await RemoteAgent.discover(url, auth)
result = await agent.search(query="Tokyo")  # Like calling a local method

# ANPCrawler: Crawler-style document fetching
crawler = ANPCrawler(did_path, key_path)
content, tools = await crawler.fetch_text(url)  # Fetch and parse documents
result = await crawler.execute_tool_call("search", {"query": "Tokyo"})

---

Installation

Option 1: Install via pip

pip install anp

Option 2: Source Installation (Recommended for Developers)

# Clone the repository
git clone https://github.com/agent-network-protocol/AgentConnect.git
cd AgentConnect

# Setup environment with UV
uv sync

# Install with optional dependencies
uv sync --extra api      # FastAPI/OpenAI integration
uv sync --extra dev      # Development tools

# Run examples
uv run python examples/python/did_wba_examples/create_did_document.py

---

All Core Modules

Module	Description	Documentation
OpenANP	Decorator-driven agent development (recommended)	README
ANP Crawler	Lightweight discovery & interaction SDK	README
FastANP	FastAPI plugin framework	README
AP2	Agent Payment Protocol v2	README
Authentication	DID-WBA identity authentication	Examples
Proof	W3C Data Integrity + RFC 9421 origin proof helpers	Python package
E2EE HPKE	HPKE-based end-to-end encryption (private + group chat)	Examples

---

Examples by Module

OpenANP Examples (Recommended Starting Point)

Location: examples/python/openanp_examples/

File	Description	Complexity
minimal_server.py	Minimal server (~30 lines)	⭐
minimal_client.py	Minimal client (~25 lines)	⭐
advanced_server.py	Full features (Context, Session, Information)	⭐⭐⭐
advanced_client.py	Full client (discovery, LLM integration)	⭐⭐⭐

# Terminal 1: Start server
uvicorn examples.python.openanp_examples.minimal_server:app --port 8000

# Terminal 2: Run client
uv run python examples/python/openanp_examples/minimal_client.py

ANP Crawler Examples

Location: examples/python/anp_crawler_examples/

# Quick start
uv run python examples/python/anp_crawler_examples/simple_amap_example.py

# Complete demonstration
uv run python examples/python/anp_crawler_examples/amap_crawler_example.py

DID-WBA Authentication Examples

Location: examples/python/did_wba_examples/

# Create DID document
uv run python examples/python/did_wba_examples/create_did_document.py

# Authentication demonstration
uv run python examples/python/did_wba_examples/authenticate_and_verify.py

FastANP Examples

Location: examples/python/fastanp_examples/

# Simple agent
uv run python examples/python/fastanp_examples/simple_agent.py

# Hotel booking agent (full example)
uv run python examples/python/fastanp_examples/hotel_booking_agent.py

AP2 Payment Protocol Examples

Location: examples/python/ap2_examples/

# Complete AP2 flow (merchant + shopper)
uv run python examples/python/ap2_examples/ap2_complete_flow.py

E2EE HPKE Encryption Examples

Location: examples/python/e2e_encryption_hpke_examples/

File	Description	Complexity
basic_private_chat.py	One-step init + bidirectional encrypted messaging + rekey	⭐
group_chat_example.py	Three-party group chat with Sender Key + epoch advance	⭐⭐⭐
key_manager_example.py	Multi-session lifecycle management with HpkeKeyManager	⭐⭐⭐
error_handling_example.py	Error scenarios (expired sessions, wrong keys, replay)	⭐⭐⭐

# Basic private chat demo
uv run python examples/python/e2e_encryption_hpke_examples/basic_private_chat.py

# Group chat with Sender Key
uv run python examples/python/e2e_encryption_hpke_examples/group_chat_example.py

# Key manager and session lifecycle
uv run python examples/python/e2e_encryption_hpke_examples/key_manager_example.py

# Error handling and edge cases
uv run python examples/python/e2e_encryption_hpke_examples/error_handling_example.py

---

Tools

ANP Network Explorer

Explore the agent network using natural language: ANP Network Explorer

DID Document Generator

uv run python tools/did_generater/generate_did_doc.py <did> [--agent-description-url URL]

---

Contact Us

• Author: GaoWei Chang
• Email: [e-mail]
• Website: https://agent-network-protocol.com/
• Discord: https://discord.gg/sFjBKTY7sB
• GitHub: https://github.com/agent-network-protocol/AgentNetworkProtocol
• WeChat: flow10240

License

This project is open-sourced under the MIT License. See LICENSE file for details.

---

Copyright (c) 2024 GaoWei Chang