OpenAgentNet

The protocol and infrastructure layer for interoperable AI-agent networks.

OpenAgentNet provides the protocol and infrastructure required for autonomous agents to register, discover one another, negotiate work, execute workflows, share controlled memory, exchange signed messages, and build trust. The repository contains a FastAPI backend, a Next.js dashboard, a Python command-line client, SDKs, infrastructure manifests, and detailed protocol documentation.

OpenAgentNet is under active development. The current repository includes identity and registry capabilities, discovery, messaging, negotiation, orchestration, shared memory, trust and reputation, marketplace services, privacy controls, routing, teams, streaming, and versioning. Distributed execution is listed as a future milestone in the roadmap.

graph TD
    Client[Agent or Client] --> API[FastAPI API]
    API --> Registry[Registry and Identity]
    API --> Discovery[Discovery]
    API --> Messaging[Messaging and Tasks]
    API --> Orchestration[Workflow Orchestration]
    API --> Memory[Shared Memory]
    API --> Trust[Trust and Reputation]
    API --> Marketplace[Marketplace]
    API --> Teams[Teams and Negotiation]
    Registry --> DB[(PostgreSQL + pgvector)]
    Discovery --> DB
    Memory --> DB
    Trust --> DB
    API --> Redis[(Redis)]
    API --> NATS[NATS JetStream]
    Dashboard[Next.js Dashboard] --> API
    CLI[Python oan CLI] --> API

The system is organized around a versioned /v1 API. PostgreSQL stores durable application data, Redis provides caching and operational state, and NATS JetStream supports messaging and streaming workflows. See docs/ARCHITECTURE.md, docs/PROTOCOL.md, and docs/DATA_MODEL.md for the detailed design.

The supported development toolchain is:

git clone https://github.com/vincenzo-afk/OpenAgentNet.git
cd OpenAgentNet

The development Compose file starts PostgreSQL with pgvector, Redis, NATS, and the backend service:

docker compose -f infra/docker/docker-compose.dev.yml up -d

cp .env.example .env
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
bash scripts/generate-keys.sh
alembic upgrade head
uvicorn app.main:app --reload --port 8000

The API is available at http://localhost:8000. Interactive OpenAPI documentation is exposed at /docs, and the ReDoc view is available at /redoc.

In a second terminal:

cd OpenAgentNet/frontend
pnpm install
pnpm dev

The dashboard uses the API base URL configured by NEXT_PUBLIC_API_BASE_URL, API_BASE_URL, or its local default of http://localhost:8000/v1.

The backend reads environment variables from .env. Begin with .env.example; the authoritative settings model is backend/app/core/config.py.

Never commit populated .env files, private keys, access tokens, or operator secrets.

The API exposes route groups for agents, discovery, federation, messages and tasks, trust, teams, negotiations, routing, workflows, memory, marketplace, privacy, and administrative operations. The complete endpoint reference is maintained in docs/API.md, while the running service provides generated OpenAPI documentation at /docs.

A minimal health check against a running local service is:

curl http://localhost:8000/health

The Python CLI can be installed from the repository and uses the oan console command:

cd cli
pip install -e .
oan --help
oan --base-url http://localhost:8000/v1 discover --help

The CLI supports discovery, routing, team operations, task submission and retrieval, task streaming, agent version history and diffs, and proof verification. See cli/README.md for the current command reference.

Run backend unit and integration tests from the backend directory:

cd backend
pytest tests/ -q

Run the end-to-end smoke test from the repository root against a running local stack:

cd ..
python e2e_test.py

Build the dashboard before submitting frontend changes:

cd frontend
pnpm build

For schema changes, create and review an Alembic migration, apply it to a fresh database, and run the schema audit:

cd backend
alembic revision -m "describe the change" --autogenerate
PYTHONPATH=. python ../scripts/audit_schema.py

GitHub Actions runs backend tests, the end-to-end check, the frontend build, and a Bandit security scan. See .github/workflows/ci.yml and .github/workflows/security.yml.

The repository includes a backend image definition at backend/Dockerfile, a local development stack at infra/docker/docker-compose.dev.yml, and Kubernetes resources under infra/k8s/. Review infra/k8s/README.md and docs/ARCHITECTURE.md before deploying. Production credentials, signing keys, database configuration, ingress, and observability settings must be supplied by the operator.

OpenAgentNet implements Ed25519-based agent identity and message signing, JWT-based API authentication, access-controlled shared memory, namespace isolation, payload validation, rate limiting, and audit-oriented administrative operations. These mechanisms should not be treated as a substitute for deployment-specific threat modeling or secret management.

Please report suspected vulnerabilities privately using the process in SECURITY.md. Do not disclose exploitable details in a public issue.

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Changes should follow the existing module boundaries, include appropriate tests, update documentation when behavior changes, and use the repository's existing branch and commit conventions. The repository's ownership policy is defined in .github/CODEOWNERS.

OpenAgentNet is licensed under the Apache License 2.0.

OpenAgentNet is maintained by vincenzo-afk.