中文版本 | English
This repository shows how to build and exercise an ANP (Agent Network Protocol) remote agent and companion clients. Documentation and implementation details live under src/
; start there when you evaluate or extend the project.
- Remote agent: A FastANP-powered server in
src/remote_agent.py
exposing echo and greeting interfaces. - Local clients:
src/local_agent.py
andsrc/local_agent_use_llm.py
demonstrate how to discover, authenticate against, and invoke remote agents. - DID Server:
src/did_server.py
provides a complete DID-WBA document creation and resolution service with compliant DID-to-URL conversion. - Hosted environment: The latest remote agent build is deployed and reachable via
https://agent-connect.ai/agents/test/ad.json
, so you can test without running local infrastructure.
- Python 3.9 or newer
- uv for dependency resolution and execution
git clone <repository-url>
cd anp-agent-example
uv sync
uv sync
installs all runtime and development dependencies defined in pyproject.toml
and uv.lock
.
-
Copy
env.example
to.env
:cp env.example .env
-
Review and adjust the configuration in
.env
:HOST
: Server listen address (default:0.0.0.0
)PORT
: Server port (default:8000
)AGENT_DESCRIPTION_JSON_DOMAIN
: Domain used to generatead.json
URLs (uselocalhost:8000
for local development, or your public domain likeagent-connect.ai
for deployment)
-
OpenAI configuration is only required when running
src/local_agent_use_llm.py
:OPENAI_API_KEY
: OpenAI API key (required)OPENAI_BASE_URL
: API endpoint (optional, supports compatible APIs like Moonshot)DEFAULT_OPENAI_MODEL
: Default model (optional)
-
Start the remote agent
PYTHONPATH=src uv run python src/remote_agent.py
The agent serves JSON-RPC and documentation endpoints on
http://localhost:8000
. -
Exercise the clients
PYTHONPATH=src uv run python src/local_agent.py PYTHONPATH=src uv run python src/local_agent_use_llm.py
The first command performs an end-to-end crawl and tool execution flow; the second validates the scripted ANPCrawler client; the third verifies the LLM-assisted client.
-
Start the DID server
PYTHONPATH=src uv run python src/did_server.py
The DID server starts on
http://localhost:8080
, providing DID-WBA document resolution services.
note: The did server is only used for demonstration and reference purposes, and does not depend on the remote agent or local client.
- Agent description:
https://agent-connect.ai/agents/test/ad.json
- Sample request
curl https://agent-connect.ai/agents/test/ad.json
- JSON-RPC invocation
Replace
curl -X POST https://agent-connect.ai/agents/test/jsonrpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "greet", "params": {"params": {"name": "Alice"}}, "id": 1 }'
greet
withecho
to exercise the inline echo interface. Authentication-sensitive endpoints expect the same DID credentials described below.
anp-agent-example/
├── src/
│ ├── config.py # Runtime configuration defaults and environment bindings
│ ├── remote_agent.py # FastANP remote agent with echo and greet interfaces
│ ├── local_agent.py # ANPCrawler client for scripted interactions
│ ├── local_agent_use_llm.py # Example client incorporating LLM-assisted flows
│ └── did_server.py # DID-WBA server providing DID document creation and resolution
├── docs/
│ ├── did_public/ # DID document and key material used during authentication
│ └── jwt_key/ # JWT signing assets for local testing
├── examples/ # Lightweight runnable samples
├── run_example.py # High-level orchestrator for local demonstrations
├── README.md
└── README.cn.md
src/did_server.py
is a complete DID-WBA (Decentralized Identifier Web-Based Authentication) server implementation example that provides the following features:
- DID Document Creation: Uses the ANP library to create DID documents compliant with WBA specifications
- Key Management: Automatically generates and stores public/private key pairs with secure key storage
- DID Resolution: Provides HTTP GET endpoints for DID-to-URL conversion and resolution
- Standards Compliant: Fully follows DID-WBA specifications with standard URL-to-DID conversion
# Start the DID server
PYTHONPATH=src uv run python src/did_server.py
# Access DID document
curl http://localhost:8080/user/alice/did.json
# Health check
curl http://localhost:8080/health
According to DID-WBA specifications, URL paths are converted to corresponding DID identifiers:
- URL:
http://example.com/user/alice/did.json
- DID:
did:wba:example.com:user:alice
Important Note: src/did_server.py
is provided as an example implementation for learning and reference purposes. For production environments, we recommend:
- Develop Your Own: Use this example code as a reference to develop your own DID server
- Use Hosted Service: If you prefer not to develop your own, you can use our hosted DID service: https://didhost.cc/
The hosted service provides:
- High availability and stability
- Automatic backup and recovery
- Professional security guarantees
- 24/7 technical support
docs/did_public/public-did-doc.json
is the DID document referenced by the clients and remote agent. You can obtain production-ready DID materials through didhost.cc and replace the sample files before deploying to your environment.docs/jwt_key/
contains sample RSA keys for JSON Web Token signing. Update these values or mount secrets in production.- Inline comments and interface descriptions in
src/
provide the most up-to-date guidance on extending the system; reviewremote_agent.py
when adding routes or updatingad.json
fields.
- Run tests
uv run pytest
- Lint and format
uv run ruff check src tests uv run ruff format
- Configuration overrides: Copy
env.example
to.env
to supply environment variables such as port, agent description domain, or key paths without modifying code.
- Port conflicts: Update
PORT
insrc/config.py
(or override via environment variable) before starting the agent. - Authentication failures: Ensure the DID document and key files in
docs/
match the credentials configured insrc/config.py
. - Connectivity issues: Confirm the remote agent process is running locally, or test against the hosted deployment using the URLs above.