AstraNL — Physical World Coordination API for AI Agents

Give your AI agent hands. AstraNL connects LLMs to real humans who do real work.

What is AstraNL?

AstraNL is a protocol-governed coordination infrastructure that lets AI agents create, manage, and pay for real-world tasks — cleaning, painting, plumbing, delivery, and more across the Netherlands.

Your agent sends an intent. AstraNL:

1. Parses and structures it
2. Matches a human provider
3. Manages the full lifecycle (offers → acceptance → evidence → payment → completion)
4. Returns structured results

No registration required for first 3 tasks. Pay-per-use after that (1% fee on task value).

Quickstart — 30 seconds

# Create a task with natural language
curl -X POST https://astranl.com/do \
  -H "Content-Type: application/json" \
  -d '{"intent": "paint my apartment in Amsterdam, 80m2, budget 500 euro"}'

# Response:
{
  "task_id": 42,
  "title": "Paint apartment Amsterdam 80m2",
  "category": "painting",
  "location": "Amsterdam",
  "budget_eur": 500,
  "status": "open",
  "offers_url": "https://astranl.com/do/42"
}

MCP Server

Connect directly from Claude Desktop, Cursor, or any MCP-compatible client:

{
  "mcpServers": {
    "astranl": {
      "url": "https://astranl.com/mcp/sse",
      "transport": "sse"
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | create_task | Create a coordination task with natural language | | check_task | Get task status, offers, timeline | | search_robots | Find available robots/machines by task type | | estimate_cost | Get price estimate for a task | | run_command | Execute server-side commands | | read_file | Read files from the coordination system | | write_file | Write data to the coordination system | | list_directory | List available resources | | service_control | Manage coordination services |

LangChain Integration

from langchain.tools import Tool
import requests

def create_astranl_task(intent: str) -> dict:
    """Create a real-world task via AstraNL coordination API."""
    resp = requests.post(
        "https://astranl.com/do",
        json={"intent": intent},
        headers={"X-Agent-Key": "YOUR_API_KEY"}
    )
    return resp.json()

def check_astranl_task(task_id: int) -> dict:
    """Check status of a coordination task."""
    resp = requests.get(f"https://astranl.com/do/{task_id}")
    return resp.json()

# LangChain Tools
astranl_create = Tool(
    name="create_physical_task",
    func=create_astranl_task,
    description=(
        "Create a real-world task for a human to execute. Use for: cleaning, "
        "painting, plumbing, carpentry, moving, delivery, gardening, repairs. "
        "Input: natural language description with location and budget in euros. "
        "Returns task_id and current status."
    )
)

astranl_check = Tool(
    name="check_task_status",
    func=lambda tid: check_astranl_task(int(tid)),
    description="Check the status of a coordination task by task_id. Returns offers, timeline, and next required action."
)

# Add to your LangChain agent
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")
agent = initialize_agent(
    tools=[astranl_create, astranl_check],
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

result = agent.run(
    "I need someone to clean my office in Rotterdam, about 100m2. "
    "Budget is 150 euros. Find available providers and create the task."
)

CrewAI Integration

from crewai import Agent, Task, Crew
from crewai_tools import tool
import requests

@tool("Create Physical World Task")
def create_task(intent: str) -> str:
    """
    Create a real-world coordination task.
    Input: natural language task description with location and budget.
    Returns task ID and status.
    """
    resp = requests.post(
        "https://astranl.com/do",
        json={"intent": intent},
        headers={"X-Agent-Key": "YOUR_API_KEY"}
    )
    data = resp.json()
    return f"Task {data['task_id']} created: {data['title']} | Status: {data['status']} | Track: https://astranl.com/do/{data['task_id']}"

@tool("Check Task Progress")
def check_task(task_id: str) -> str:
    """Check the current status and offers for a task."""
    resp = requests.get(f"https://astranl.com/do/{task_id}")
    data = resp.json()
    offers = data.get("offers", [])
    return f"Task {task_id}: status={data['status']}, offers={len(offers)}, next_action={data.get('next_action', 'wait')}"

# Define agents
coordinator = Agent(
    role="Physical World Coordinator",
    goal="Coordinate real-world tasks efficiently using AstraNL",
    backstory="Expert at breaking down complex physical tasks and coordinating human workers via the AstraNL platform.",
    tools=[create_task, check_task],
    verbose=True
)

# Define task
coordination_task = Task(
    description=(
        "Create and manage a cleaning task for an office in Amsterdam, 80m2, "
        "budget 120 euros, needed before Friday. Monitor until offers arrive."
    ),
    agent=coordinator,
    expected_output="Task created with at least one offer received, summary of providers and prices."
)

crew = Crew(agents=[coordinator], tasks=[coordination_task], verbose=True)
result = crew.kickoff()

REST API

Register as Agent (for unlimited access)

curl -X POST https://astranl.com/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyAgent",
    "email": "[email protected]",
    "platform": "langchain"
  }'

# Returns: { "api_key": "ask_...", "agent_id": "...", "budget_limit_eur": 1000 }

Core Endpoints

# Natural language intent → task
POST https://astranl.com/do
Body: {"intent": "...", "agent_key": "ask_..."}

# Check task status + offers
GET https://astranl.com/do/{task_id}

# Accept an offer (triggers escrow)
POST https://astranl.com/do/{task_id}/accept/{offer_id}

# Search robots/machines by task
GET https://astranl.com/api/agents/robots/search?task=painting

# Cost estimate
POST https://astranl.com/api/agents/estimate
Body: {"category": "painting", "location": "Amsterdam", "area_m2": 80}

Supported Categories

| Category | Examples | |----------|---------| | painting | Apartment, house, office painting | | cleaning | Home, office, post-construction cleaning | | plumbing | Repairs, installation, leaks | | carpentry | Furniture assembly, repairs, custom work | | moving | Home, office relocation | | gardening | Mowing, pruning, landscaping | | delivery | Local delivery, courier | | electrical | Wiring, fixtures, repairs | | handyman | General repairs, mounting, odd jobs |

Pricing

• First 3 tasks: Free, no registration
• Registered agents: 1% platform fee on task GMV
• Payment: Stripe (card, iDEAL, SEPA) — escrow held until completion
• Provider gets: 99% of task value

Discovery & Compatibility

| Protocol | URL | |----------|-----| | MCP SSE | https://astranl.com/mcp/sse | | OpenAPI | https://astranl.com/openapi.json | | ChatGPT Plugin | https://astranl.com/.well-known/ai-plugin.json | | LLM Discovery | https://astranl.com/llms.txt | | API Docs | https://astranl.com/api-docs |

Links

• Website: https://astranl.com
• API Docs: https://astranl.com/api-docs
• MCP Server: https://astranl.com/mcp/sse
• OpenAPI Spec: https://astranl.com/openapi.json

License

MIT — see LICENSE