Developer Guide

Choose your role

Install

Client Quick Start

Fetch an ANML duckument, read its knowledge, and execute an action.

import asyncio
from anml_client import AnmlClient, AllowListTrustPolicy

async def main():
    client = (
        AnmlClient.builder()
        .base_url("https://shop.example.com")
        .trust_policy(AllowListTrustPolicy(["https://shop.example.com"]))
        .build()
    )

    # Fetch the service's ANML duckument
    doc = await client.fetch("/.well-known/anml")

    # Read what the service wants to tell us
    for inform in doc.knowledge.inform if doc.knowledge else []:
        print(f"ℹ️  {inform.content}")

    # Check what data the service needs
    for ask in doc.knowledge.ask if doc.knowledge else []:
        print(f"❓ Needs: {ask.field} (purpose: {ask.purpose})")

    # Execute an action (after getting user consent for disclosed fields)
    response = await client.execute_action(doc, "checkout", {
        "email": "user@example.com",
        "shipping_address": "123 Main St",
    })
    print(f"✅ {response.status_code}")

asyncio.run(main())

import { AnmlClient, AllowListTrustPolicy } from '@anml-foundation/client';

const client = AnmlClient.builder()
  .baseUrl('https://shop.example.com')
  .trustPolicy(new AllowListTrustPolicy(['https://shop.example.com']))
  .build();

// Fetch the service's ANML duckument
const doc = await client.fetch('/.well-known/anml');

// Read knowledge the service shares
for (const inform of doc.knowledge?.inform ?? []) {
  console.log(`ℹ️  ${inform.content}`);
}

// Execute an action
const response = await client.executeAction(doc, 'checkout', {
  email: 'user@example.com',
  shippingAddress: '123 Main St',
});
console.log(`✅ ${response.status}`);

Server Quick Start

Build an ANML duckument that describes your service to agents. The SDK handles serialization, validation, and discovery — you provide the business logic.

from fastapi import FastAPI, Request
from anml_server import AnmlDocument, negotiate_content_type

app = FastAPI()

@app.get("/.well-known/anml")
async def serve_anml(request: Request):
    doc = (
        AnmlDocument.builder()
        .title("Acme Electronics — Checkout")
        .ttl(300)
        # Brand & persona
        .persona(
            tone="helpful",
            instructions="Show itemized totals. Confirm before payment.",
            brand_color="#4F46E5",
            logo_url="https://acme.example.com/logo.png",
        )
        # Privacy constraints
        .disclosure("payment-credential", requires="explicit-consent")
        .disclosure("shipping-address", requires="explicit-consent")
        .disclosure("email", requires="legitimate-interest")
        # Workflow state
        .flow([
            Step("browse", label="Browse", status="completed"),
            Step("checkout", label="Checkout", status="current", action="submit-order"),
            Step("confirm", label="Confirmed", status="pending"),
        ])
        # Actions the agent can take
        .action(
            "submit-order",
            method="POST",
            endpoint="/api/orders",
            auth="required",
            confirm=True,
        )
        # Knowledge exchange
        .inform("Free shipping on orders over $75. 30-day returns.", ttl=3600)
        .inform("Holiday sale: 20% off all monitors through Dec 31.", ttl=86400)
        .ask("email", action="submit-order", required=True, purpose="receipt")
        .ask("shipping-address", action="submit-order", required=True, purpose="delivery")
        # Usage rights
        .rights("cache")
        # Content
        .body("4K Monitor x1 — $599.00 | USB-C Cable x2 — $29.98 | Subtotal: $628.98")
        .build()
    )

    content_type = negotiate_content_type(request.headers.get("accept", ""))
    return doc.to_response(content_type=content_type)

import express from 'express';
import { AnmlDocument, negotiateContentType } from '@anml-foundation/server';

const app = express();

app.get('/.well-known/anml', (req, res) => {
  const doc = AnmlDocument.builder()
    .title('Acme Electronics — Checkout')
    .ttl(300)
    .persona({
      tone: 'helpful',
      instructions: 'Show itemized totals. Confirm before payment.',
      brandColor: '#4F46E5',
      logoUrl: 'https://acme.example.com/logo.png',
    })
    .disclosure('payment-credential', { requires: 'explicit-consent' })
    .disclosure('shipping-address', { requires: 'explicit-consent' })
    .flow([
      { id: 'browse', label: 'Browse', status: 'completed' },
      { id: 'checkout', label: 'Checkout', status: 'current', action: 'submit-order' },
      { id: 'confirm', label: 'Confirmed', status: 'pending' },
    ])
    .action('submit-order', {
      method: 'POST',
      endpoint: '/api/orders',
      auth: 'required',
      confirm: true,
    })
    .inform('Free shipping on orders over $75. 30-day returns.', { ttl: 3600 })
    .ask('email', { action: 'submit-order', required: true, purpose: 'receipt' })
    .ask('shipping-address', { action: 'submit-order', required: true, purpose: 'delivery' })
    .rights('cache')
    .body('4K Monitor x1 — $599.00 | USB-C Cable x2 — $29.98 | Subtotal: $628.98')
    .build();

  const contentType = negotiateContentType(req.headers.accept);
  res.type(contentType).send(doc.serialize(contentType));
});

app.listen(3000);

Key Concepts

Package Registries

All SDKs are published to their language's standard package registry and versioned with semantic versioning.

Resources