Getting Started

Install an SDK and dispatch your first policy-gated action in under ten minutes.

Two ways to build with MAP - pick your surface:

• Reference tree (full framework). Clone the repo and run from source with tsx. This gives you the map() helper, the policy DSL, the built-in adapters, BaseMicroAgent, and the demo server. Best for evaluating the complete developer experience.
• Published SDK (@sidianlabs/map). npm install the client package for server-to-server usage: MapAssistantClient with dispatch, batch, approvals, streaming, signing transports, and observability.

Both are covered below.

Installation

# Full reference tree (map() DSL, adapters, demo server)
git clone https://github.com/SidianLabs/micro-agent-protocol.git
cd micro-agent-protocol
npm install

# Published client SDK (best-supported npm surface today)
npm install @sidianlabs/map

# Python (preview: source install)
pip install -e packages/python

# Go (preview: source package)
go get github.com/SidianLabs/micro-agent-protocol/packages/go/mapproto

The fastest path: the map() helper

Available in the reference tree (src/map.ts), exercised by the test suite (map-simple.test.ts). The published npm package exposes the same concepts through MapAssistantClient (see Client SDK usage).

The highest-level API is one call. You declare policy, register handlers for what your agent does, and every run() goes through the policy engine automatically.

import { map } from '@sidianlabs/map';

const agent = map({
  policy: [
    // Payments: require approval above $1000
    { when: 'payment.*',   amount_gt: 1000,    require: 'approval' },

    // Database: block all writes to production
    { when: 'db.write',     env: 'production',  require: 'deny' },

    // Infrastructure: always require approval
    { when: 'aws.*',        env: 'production',  require: 'approval' },

    // Everything else: allow
    { when: '*',                                require: 'allow' },
  ],
  onApprovalRequired: async ({ capability, approve }) => {
    const ok = await askHuman(`Approve ${capability}?`);
    if (ok) await approve();
  },
});

// Register handlers for whatever your agent does
agent.can('payment.execute', async (input) => {
  return await stripe.charges.create({ amount: input.amount });
});

agent.can('db.write', async (input) => {
  return await db.query(input.sql, input.params);
});

// Run any capability - MAP enforces your policy automatically
const result = await agent.run('payment.execute', {
  amount: 5000,
  currency: 'USD',
  vendor_id: 'vendor_abc',
});

// result.status  -> 'executed' | 'denied' | 'approval_required'
// result.output  -> whatever your handler returned
// result.receipt -> cryptographically signed proof of what happened

That's it. No TaskEnvelope. No AgentDescriptor. No DelegationToken. Just policy, handlers, and receipts.

Client SDK usage

For server-to-server usage against a running MAP server:

TypeScript

import { MapAssistantClient } from '@sidianlabs/map';

const client = MapAssistantClient.forBaseUrl('http://localhost:8787');
client.configureSigning('your-key-id', 'your-secret');

const result = await client.dispatch({
  capability: 'payment.process',
  negotiation: { delivery_mode: 'sync' },
  envelope: {
    task_id: 'task-001',
    requester_identity: { type: 'user', id: 'user-123' },
    target_agent: 'agent-payment',
    intent: 'Process a payment of $100',
    constraints: { common: { max_amount: 1000 } },
    risk_class: 'medium',
    delegation_token: 'tok_xxx',
    requested_output_mode: 'full',
  },
});

console.log(result.result);

Python

Preview: the Python SDK is not yet fully aligned with the current reference HTTP contract.

from mapprotocol import Client

client = Client(base_url="http://localhost:8787")
client.configure_signing(key_id="your-key-id", secret="your-secret")

result = client.dispatch({
    "capability": "payment.process",
    "envelope": {
        "task_id": "task-001",
        "requester_identity": {"type": "user", "id": "user-123"},
        "target_agent": "agent-payment",
        "intent": "Process a payment of $100",
        "constraints": {"common": {"max_amount": 1000}},
        "risk_class": "medium",
        "delegation_token": "tok_xxx",
        "requested_output_mode": "full",
    },
})

Go

Preview: the Go SDK is not yet fully aligned with the current reference HTTP contract.

import (
	"context"
	"time"

	"github.com/SidianLabs/micro-agent-protocol/mapproto"
)

signer := mapproto.NewHMACSigner([]byte("your-secret-key"), "key-id")

client, err := mapproto.NewClient(
	mapproto.WithBaseURL("http://localhost:8787"),
	mapproto.WithTimeout(30*time.Second),
	mapproto.WithSigner(signer),
)
if err != nil {
	log.Fatal(err)
}

result, err := client.Dispatch(context.Background(), &mapproto.DispatchRequest{
	Capability: "payment.process",
	Envelope: mapproto.TaskEnvelope{
		TaskID:      "task-001",
		TargetAgent: "agent-payment",
		Intent:      "Process a payment of $100",
		RiskClass:   "medium",
	},
})

Running the demo server

The repository ships with a demo server and example agents:

git clone https://github.com/SidianLabs/micro-agent-protocol.git
cd micro-agent-protocol
npm install

# Start the demo server (includes example agents)
npm run dev:demo-server
# MAP demo server listening on http://localhost:8787

# In another terminal, run a demo
npm run demo:payment
npm run demo:db-read

HTTP server deployment

For production deployments, run MAP as an HTTP server:

MAP_POLICY_PATH=./policy.json \
MAP_APPROVAL_WEBHOOK_URL=https://your-app.com/approvals \
MAP_SIGNING_SECRET=your-secret \
npm run dev:server

# Dispatch an intent
curl -X POST http://localhost:8787/dispatch \
  -H "Content-Type: application/json" \
  -d '{ "capability": "payment.execute", "envelope": { ... } }'

# Get current policy
curl http://localhost:8787/policy

# Hot-swap policy at runtime
curl -X POST http://localhost:8787/policy -d @policy.json

# Query the audit trail
curl http://localhost:8787/audit-events

Environment variables

Variable	Default	Description
PORT	8787	Server port
MAP_DEPLOYMENT_PROFILE	open	open, verified, or regulated
MAP_POLICY_PATH	-	Path to JSON policy file
MAP_SIGNING_SECRET	demo key	HMAC signing secret
MAP_APPROVAL_WEBHOOK_URL	-	Default webhook for approval notifications
MAP_SERVER_BASE_URL	-	Server base URL used in approval payloads
MAP_ADMIN_TOKEN	-	Token for admin endpoints
MAP_REQUIRE_TENANT	false	Require tenant_id on all requests
MAP_PAYMENT_API_KEY	-	Payment provider API key
MAP_DB_CONNECTION_STRING	-	PostgreSQL connection string