5-Minute Quickstart

Run your first secure agent in 5 minutes

Edit on GitHub

5-Minute Quickstart

Get your first AgentWeave agent running in 5 minutes. This guide assumes you have installed AgentWeave and have Docker running.

Goal: Build and run a secure agent that can greet users. Understand the basic AgentWeave workflow without getting into complex details.

Step 1: Install AgentWeave

If you haven't already:

1

pip install agentweave

Verify installation:

1

agentweave --version

Step 2: Start Infrastructure

Start SPIRE and OPA using Docker Compose:

1
2
3
4
5
6
7
8

# Download the starter template
curl -O https://raw.githubusercontent.com/agentweave/agentweave-starter/main/docker-compose.yaml

# Start services
docker-compose up -d

# Verify they're running
docker-compose ps

You should see spire-server, spire-agent, and opa running.

Step 3: Create Your Agent

Create a file called hello_agent.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

from agentweave import SecureAgent, capability

class HelloAgent(SecureAgent):
    """A simple greeting agent."""

    @capability("greet")
    async def greet(self, name: str = "World") -> dict:
        """Greet someone by name."""
        return {
            "message": f"Hello, {name}! I'm a secure agent.",
            "agent": self.config.agent.name
        }

if __name__ == "__main__":
    agent = HelloAgent.from_config("config.yaml")
    agent.run()

That's it! Just 15 lines of code for a fully secure, production-ready agent.

Step 4: Create Configuration

Create config.yaml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

agent:
  name: "hello-agent"
  trust_domain: "quickstart.local"
  description: "My first secure agent"
  capabilities:
    - name: "greet"
      description: "Greet someone"

identity:
  provider: "spiffe"
  allowed_trust_domains:
    - "quickstart.local"

authorization:
  provider: "opa"
  opa_endpoint: "http://localhost:8181"
  default_action: "log-only"  # Permissive for quickstart

server:
  port: 8443

Development Only: We're using default_action: "log-only" for this quickstart. In production, always use "deny" and write explicit policies.

Step 5: Register with SPIRE

Register your agent to get a cryptographic identity:

1
2
3
4

docker exec spire-server spire-server entry create \
  -spiffeID spiffe://quickstart.local/agent/hello-agent \
  -parentID spiffe://quickstart.local/spire/agent \
  -selector unix:uid:$(id -u)

You should see:

1
2
3
4
5
6
7

Entry ID         : <uuid>
SPIFFE ID        : spiffe://quickstart.local/agent/hello-agent
Parent ID        : spiffe://quickstart.local/spire/agent
Revision         : 0
X509-SVID TTL    : default
JWT-SVID TTL     : default
Selector         : unix:uid:1000

Step 6: Run Your Agent

Start your agent:

1
2

export SPIFFE_ENDPOINT_SOCKET=unix:///tmp/spire-agent/public/api.sock
python hello_agent.py

You should see logs indicating the agent started successfully:

1
2
3

{"level": "INFO", "message": "Agent starting", "agent": "hello-agent"}
{"level": "INFO", "message": "Identity acquired", "spiffe_id": "spiffe://quickstart.local/agent/hello-agent"}
{"level": "INFO", "message": "Server listening", "port": 8443}

Step 7: Test Your Agent

Open a new terminal and test your agent:

Check Health

1

curl http://localhost:8443/health

Response:

1

{"status": "healthy", "timestamp": "2025-12-07T10:30:00Z"}

View Agent Card

1

curl http://localhost:8443/.well-known/agent.json | jq

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "name": "hello-agent",
  "description": "My first secure agent",
  "version": "1.0.0",
  "capabilities": [
    {
      "name": "greet",
      "description": "Greet someone"
    }
  ],
  "extensions": {
    "spiffe_id": "spiffe://quickstart.local/agent/hello-agent"
  }
}

Call the Agent

To call the agent from another agent, create caller.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import asyncio
from agentweave import SecureAgent

async def main():
    # Create a caller agent
    caller = SecureAgent.from_config("caller-config.yaml")

    # Call the hello agent
    result = await caller.call_agent(
        target="spiffe://quickstart.local/agent/hello-agent",
        task_type="greet",
        payload={"name": "Alice"}
    )

    print(f"Response: {result.artifacts[0]['data']}")

if __name__ == "__main__":
    asyncio.run(main())

Note: You'll need to create caller-config.yaml and register the caller agent with SPIRE. See the Hello World Tutorial for a complete multi-agent example.

What Just Happened?

Behind the scenes, AgentWeave handled:

  1. Identity: Fetched your agent's X.509 certificate (SVID) from SPIRE
  2. Server: Started an HTTPS server with mTLS on port 8443
  3. Protocol: Implemented the A2A (Agent-to-Agent) protocol
  4. Discovery: Published your capabilities at /.well-known/agent.json
  5. Authorization: Connected to OPA for policy enforcement
  6. Observability: Set up logging and metrics

When another agent calls your greet capability:

1
2
3
4
5
6
7
8
9

Caller Agent                          Hello Agent
     |                                      |
     |  1. Get own SVID from SPIRE          |
     |  2. Check OPA: can I call hello?     |
     |  3. Establish mTLS connection   ---> |
     |                                  4. Verify caller's SVID
     |                                  5. Check OPA: is caller allowed?
     |                                  6. Execute greet()
     | <--- 7. Return result over mTLS     |

All of this is automatic - you just implement the @capability method.

What's Next?

You've just run your first secure agent! Here's where to go next:

Learn More

Try Examples

  • Multi-agent orchestration - See examples/orchestrator/
  • Data pipeline - See examples/data_pipeline/
  • LLM integration - See examples/llm_agent/

Production Readiness

Common Issues

"Failed to connect to SPIRE Agent"

Make sure the SPIRE Agent is running and the socket path is correct:

1
2
3
4
5
6
7
8

# Check if socket exists
ls -l /tmp/spire-agent/public/api.sock

# Check SPIRE Agent logs
docker-compose logs spire-agent

# Verify environment variable
echo $SPIFFE_ENDPOINT_SOCKET

"No SPIFFE ID found"

You need to register your agent with SPIRE:

1
2
3
4

# List existing entries
docker exec spire-server spire-server entry show

# Create entry if missing (see Step 5)

"Port 8443 already in use"

Change the port in your config:

1
2

server:
  port: 9443  # Use a different port

"OPA connection refused"

Ensure OPA is running:

1
2
3
4
5

# Check OPA status
docker-compose ps opa

# Test OPA endpoint
curl http://localhost:8181/health

Tips for Development

Use the CLI

The agentweave CLI has helpful commands:

1
2
3
4
5
6
7
8

# Validate your config before running
agentweave validate config.yaml

# Generate SPIRE registration command
agentweave spire-entry config.yaml

# Test connectivity to another agent
agentweave ping spiffe://quickstart.local/agent/other-agent

Enable Debug Logging

For more verbose output:

1
2
3

observability:
  logging:
    level: "DEBUG"

Auto-reload on Changes

During development, use watch mode:

1
2
3
4
5

# Install watchdog
pip install watchdog

# Run with auto-reload
agentweave serve config.yaml --reload

Clean Up

When you're done:

1
2
3
4
5
6
7

# Stop your agent (Ctrl+C)

# Stop infrastructure
docker-compose down

# Remove volumes (optional)
docker-compose down -v
Previous: ← Installation Next: Core Concepts →