Skip to content

Quickstart Guide

Get Adaptive Sentience running in 5 minutes.

Prerequisites

  • Python 3.9+
  • Git
  • (Optional) Android device with ADB for mobile testing

Installation

1. Clone the Repository

git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh

2. Set Up Python Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Running Your First Workflow

We'll run a simple 3-terminal setup: Gateway → Edge Node → Demo Script

Terminal 1: Start the Gateway

python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token

You should see: 

Gateway running on http://127.0.0.1:8787
Dev token enabled

Gateway is ready

The HTTP gateway is now accepting requests on port 8787

Terminal 2: Start an Edge Node

cd edge_node
NODE_PORT=8000 python3 node.py

You should see: 

Edge node running on port 8000
Node ID: local:abc123

Node is ready

The edge node has joined the mesh and is ready to execute tools

Terminal 3: Run a Demo Workflow

python demos/llm_client_demo.py

This demo will:

  1. Connect to the gateway
  2. Discover available tools on the edge node
  3. Execute a workflow with tool calls
  4. Display execution evidence including trace ID and execution path

Example output: 

{
  "ok": true,
  "verified": true,
  "result": {
    "redacted_text": "Contact [REDACTED]",
    "redactions": [{"type": "email", "start": 8, "end": 25}]
  },
  "execution_path": ["local:abc123"],
  "degraded": false
}

Understanding What Just Happened

1. Tool Discovery

The gateway discovered available tools on your edge node using UDP multicast:

# Gateway asks: "What tools do you have?"
# Node responds: "I can do: pii_redact, summarize, validate_schema"

2. Workflow Execution

Your demo script sent a workflow request:

{
  "target": { "kind": "local" },
  "tool_name": "pii_redact",
  "tool_args": { "text": "Contact john@example.com" },
  "token": { "capabilities": ["tool:pii_redact"] }
}

3. Policy Enforcement

The runtime checked:

  • ✅ Capability token has required permission
  • ✅ Tool exists on the node
  • ✅ Input schema is valid
  • ✅ Node is trusted (or uses TOFU)

4. Execution Evidence

After execution, you received:

  • Trace ID: Unique identifier for this execution
  • Execution path: Which nodes handled the work
  • Verified status: Cryptographic verification passed
  • Results: Tool output with schema validation

Next Steps

Try Offline Operation

  1. Stop the edge node (Ctrl+C in Terminal 2)
  2. Run the demo again
  3. The gateway will queue the request
  4. Restart the node → Request delivers automatically

Store-and-Forward

Requests are stored in the gateway's mailbox and delivered when nodes come back online

Add More Nodes

Run additional edge nodes on different ports:

# Terminal 4
cd edge_node
NODE_PORT=8001 python3 node.py

The gateway will automatically discover and use both nodes for failover.

Test the Android App

See Android Deployment for instructions on running the mobile app.

Explore the MCP Server

python -m gateway.mcp_server_cli --host 127.0.0.1 --port 8790

Connect with Claude Desktop or other MCP clients.

Common Issues

Port Already in Use

Error: Address already in use

Solution: Use a different port: 

python -m gateway.http_gateway --port 8788

Node Not Discovered

Symptoms: Gateway says "No nodes available"

Solutions:

  1. Check firewall: UDP port 9999 must be open for multicast
  2. Check network: Nodes must be on same LAN
  3. Manual targeting: Use "target": {"node_id": "local:abc123"}

Permission Denied

Error: Capability token missing required permission

Solution: Add the capability to your token: 

token = {
    "capabilities": ["tool:pii_redact", "tool:summarize"]
}

Getting Help