Home

AgentWeave SDK

Python SDK for building secure, cross-cloud AI agents with cryptographic identity and automatic authorization

---

What is AgentWeave?

AgentWeave is a Python SDK that enables developers to build production-ready AI agents with zero-trust security baked in from the start. Every agent built with AgentWeave automatically receives a cryptographic identity via SPIFFE/SPIRE, has all communication encrypted through mutual TLS, enforces policy-based authorization through OPA, and communicates with other agents using the standards-based A2A (Agent-to-Agent) protocol. AgentWeave handles the entire security stack so developers can focus on building agent capabilities rather than wrestling with authentication, encryption, and authorization infrastructure.

Core Principle

"The secure path is the only path."

AgentWeave is designed so that security cannot be bypassed. There is no insecure mode, no --skip-auth flag, no way to disable mTLS. Every agent has identity, every message is encrypted, and every request is authorized. Security is not a feature you opt into -- it is the foundation everything else is built on.

Key Features

Feature	Technology	Description
Cryptographic Identity	SPIFFE/SPIRE	Every agent receives an X.509 SVID with automatic certificate rotation. No hardcoded secrets, no API keys to manage.
Mutual TLS	TLS 1.3 (default)	All agent-to-agent communication is encrypted and mutually authenticated. Both sides prove their identity.
Policy Enforcement	Open Policy Agent (OPA)	Every incoming request is evaluated against authorization policies written in Rego. Default deny in production.
A2A Protocol	JSON-RPC 2.0	Standards-based agent-to-agent communication with capability discovery, task management, and streaming support.
Framework Agnostic	--	Works with LangGraph, CrewAI, AutoGen, or any Python-based agent framework. AgentWeave handles security; your framework handles logic.
Cross-Cloud	Optional Tailscale mesh	Deploy agents on AWS, GCP, Azure, on-prem, or any mix. Communicate securely across cloud boundaries.

Architecture Overview

┌─────────────────────────────────────────────────┐
│           Your Agent Code                       │
│         (@capability decorators)                │
├─────────────────────────────────────────────────┤
│              AgentWeave SDK                     │
│                                                 │
│  ┌─────────────┐  ┌──────────────────────────┐  │
│  │  Identity    │  │  Authorization           │  │
│  │  Layer       │  │  Layer                   │  │
│  │ (SPIFFE/     │  │ (OPA Rego policies,      │  │
│  │  SPIRE)      │  │  default deny)           │  │
│  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                       │                │
│  ┌──────┴───────────────────────┴─────────────┐  │
│  │  Communication Layer                       │  │
│  │  (A2A Protocol - JSON-RPC 2.0)             │  │
│  ├────────────────────────────────────────────┤  │
│  │  Transport Layer                           │  │
│  │  (mTLS, TLS 1.3, certificate rotation)    │  │
│  └────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Quick Links

Wiki Page	Description
Getting Started	Installation, prerequisites, and your first secure agent in minutes
Architecture	Deep dive into AgentWeave's layered security architecture
Agent Lifecycle	How agents initialize, register identity, and handle requests
Configuration Reference	Complete YAML configuration reference with all options
Identity and Security	SPIFFE/SPIRE integration, SVIDs, trust domains, and certificate rotation
Authorization	OPA policies, Rego rules, default deny, and authorization flow
A2A Protocol	Agent-to-Agent protocol: Agent Cards, tasks, streaming, and capability discovery
Transport Layer	mTLS configuration, TLS 1.3, and cross-cloud networking
CLI Reference	Command-line tools: validate, serve, card generate, authz check
Observability	Metrics, distributed tracing, structured logging, and audit trails
Deployment	Kubernetes, Helm, Docker Compose, and production deployment guides
Testing Guide	Mock providers, test utilities, and integration testing strategies
API Reference	Complete Python API reference for all public classes and methods

Security Guarantees

AgentWeave enforces the following security properties at all times:

• Every agent has cryptographic identity -- Each agent receives a SPIFFE SVID (X.509 certificate) that uniquely identifies it within the trust domain
• No agent can start without identity -- Agent initialization fails if SPIFFE/SPIRE infrastructure is unavailable; there is no fallback to insecure mode
• All traffic is encrypted -- TLS 1.3 is the default for all agent-to-agent communication; plaintext is never an option
• Mutual authentication is required -- Both the client and server must present valid certificates; one-sided TLS is not supported
• No request proceeds without authorization -- Every incoming request is evaluated against OPA policies before any capability handler executes
• Credentials auto-rotate -- SPIFFE SVIDs are automatically rotated before expiry with zero downtime
• No hardcoded secrets -- Identity is cryptographic; there are no API keys, passwords, or tokens embedded in code or configuration
• Full audit trail -- Every authorization decision, identity rotation, and agent interaction is logged for compliance and forensics

Quick Example

from agentweave import SecureAgent, capability, AgentConfig

class MyAgent(SecureAgent):
    @capability("search")
    async def search(self, query: str) -> dict:
        return {"results": [...]}

# Configuration via YAML
config = AgentConfig.from_file("config.yaml")
agent = MyAgent(config)
await agent.start()

A minimal config.yaml:

agent:
  name: my-search-agent
  version: 1.0.0

identity:
  trust_domain: example.org
  spire_socket: unix:///run/spire/sockets/agent.sock

authorization:
  policy_path: ./policies/

server:
  host: 0.0.0.0
  port: 8443

With just this, your agent will:

1. Obtain a SPIFFE SVID from SPIRE
2. Start an mTLS-secured A2A server on port 8443
3. Publish an Agent Card advertising the search capability
4. Authorize every incoming request against OPA policies
5. Automatically rotate certificates before they expire

Requirements

Requirement	Version	Notes
Python	>= 3.11	Required for modern async features
SPIFFE/SPIRE	SPIRE 1.x	Workload identity infrastructure
OPA	0.60+	Authorization policy engine

Installation

pip install agentweave

For development:

git clone https://github.com/aj-geddes/agentweave.git
cd agentweave
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

License

AgentWeave is released under the Apache License 2.0.

---

GitHub