API Reference

This page documents the Multi-Agent Planning API endpoints available on the Orchestrator service.

Base URLs

http://localhost:8080    # Agent (primary entry point)
http://localhost:8081    # Orchestrator (internal, requires auth context)

Governance-First Architecture

For governance compliance, MAP requests should be routed through the Agent service. The Agent handles authentication, policy enforcement, and audit logging before forwarding to the Orchestrator. Direct calls to the Orchestrator require authentication context that includes user information.

Recommended: Use the SDKs which handle routing automatically.

Prerequisites

MAP requires an LLM provider to be configured. Without a provider, plans will generate but execution will fail.

# .env or orchestrator configuration
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...

See LLM Providers for configuration details.

Endpoints

Generate and Execute Plan

The primary endpoint generates a plan and executes it in a single request. This is a synchronous operation - the plan is generated based on available agents and then executed immediately.

POST /api/v1/plan

Single-Call Architecture

Unlike traditional orchestration systems with separate generate/execute phases, AxonFlow's MAP uses a single-call pattern where the plan is generated AND executed in one request. This simplifies client integration and ensures atomic execution.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language query to plan
`domain`	string	No	Domain hint (travel, healthcare, finance, generic)
`execution_mode`	string	No	Execution mode: `sequential`, `parallel`, `auto`
`context`	object	No	Additional context for the plan
`user`	object	Yes*	User context (required when routing through Agent)

*When using the SDK or routing through the Agent, user context is automatically populated.

Example Request (via SDK - Recommended)

The SDK handles authentication and routing through the Agent automatically:

import { AxonFlow } from '@axonflow/sdk';

const client = new AxonFlow({
  endpoint: 'http://localhost:8080',  // Agent URL
  licenseKey: 'your-license-key',     // Or use self-hosted mode
});

// Generate and execute plan in one call
const result = await client.generatePlan(
  'Research the benefits of remote work',
  'generic'  // domain hint
);

console.log(`Plan ID: ${result.planId}`);
console.log(`Steps executed: ${result.steps.length}`);

Example Request (via Agent API)

Requests should be routed through the Agent's /api/request endpoint:

curl -X POST http://localhost:8080/api/request \
  -H "Content-Type: application/json" \
  -H "X-License-Key: $LICENSE_KEY" \
  -d '{
    "query": "Research the benefits of remote work for software teams",
    "request_type": "multi-agent-plan",
    "context": {
      "domain": "generic"
    }
  }'

Response

{
  "success": true,
  "plan_id": "plan_1765851929_abc123",
  "result": "## Benefits of Remote Work for Software Teams\n\n### 1. Increased Productivity\n...",
  "steps": [
    {
      "id": "step_1",
      "name": "research-benefits",
      "type": "llm-call",
      "description": "Research remote work benefits",
      "agent": "research-agent"
    },
    {
      "id": "step_2",
      "name": "summarize-findings",
      "type": "llm-call",
      "description": "Summarize research findings",
      "depends_on": ["step_1"],
      "agent": "summarizer"
    }
  ],
  "metadata": {
    "tasks_executed": 2,
    "execution_mode": "sequential",
    "execution_time_ms": 4580,
    "tasks": [
      {"name": "research-benefits", "status": "completed", "time_ms": 2340},
      {"name": "summarize-findings", "status": "completed", "time_ms": 2240}
    ]
  }
}

Error Responses

Status	Code	Description
400	`INVALID_REQUEST`	Invalid request body
400	`NO_AGENTS_AVAILABLE`	No agents match the query
401	`UNAUTHORIZED`	Invalid or missing authentication
408	`PLANNING_TIMEOUT`	Planning exceeded timeout
500	`PLANNING_ERROR`	Internal planning error
503	`SERVICE_UNAVAILABLE`	Planning engine not initialized

List Agents

List available agents in the registry.

GET /api/v1/agents

Query Parameters

Parameter	Type	Description
`domain`	string	Filter by domain
`capability`	string	Filter by capability
`type`	string	Filter by type (specialist, coordinator)

Example Request

curl "http://localhost:8081/api/v1/agents?domain=travel" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "agents": [
    {
      "name": "flight-search",
      "domain": "travel",
      "type": "specialist",
      "description": "Search for flight options",
      "capabilities": ["flight_search", "fare_comparison"],
      "source": "file"
    },
    {
      "name": "hotel-search",
      "domain": "travel",
      "type": "specialist",
      "description": "Search for hotel accommodations",
      "capabilities": ["hotel_search", "rate_comparison"],
      "source": "file"
    }
  ],
  "total": 2
}

Get Agent Details

Get detailed configuration for a specific agent.

GET /api/v1/agents/{agentName}

Path Parameters

Parameter	Type	Description
`agentName`	string	Agent name

Example Request

curl http://localhost:8081/api/v1/agents/flight-search \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "name": "flight-search",
  "domain": "travel",
  "type": "specialist",
  "description": "Search for flight options",
  "capabilities": ["flight_search", "fare_comparison"],
  "llm": {
    "provider": "openai",
    "model": "gpt-4"
  },
  "source": "file",
  "metadata": {
    "createdAt": "2025-12-01T00:00:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}

Validate Agent Configuration

Validate an agent configuration without creating it.

POST /api/v1/agents/validate

Request Body

Agent configuration YAML or JSON.

Example Request

curl -X POST http://localhost:8081/api/v1/agents/validate \
  -H "Content-Type: application/yaml" \
  -H "Authorization: Bearer $API_KEY" \
  -d '
apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: test-agent
  domain: generic
spec:
  type: specialist
  description: Test agent
  capabilities:
    - testing
  llm:
    provider: openai
    model: gpt-4
'

Response (Valid)

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Response (Invalid)

{
  "valid": false,
  "errors": [
    {
      "field": "spec.llm",
      "message": "llm configuration required for specialist agents"
    }
  ],
  "warnings": [
    {
      "field": "spec.timeout",
      "message": "no timeout specified, using default 60s"
    }
  ]
}

SDK Examples

The SDKs use a single-call pattern that generates and executes plans atomically.

TypeScript SDK

import { AxonFlow } from '@axonflow/sdk';

const client = new AxonFlow({
  endpoint: 'http://localhost:8080',  // Agent URL
  licenseKey: 'YOUR_LICENSE_KEY',
});

// Generate and execute plan in one call
const result = await client.generatePlan(
  'Research AI governance best practices',
  'generic'  // domain hint
);

console.log(`Plan ID: ${result.planId}`);
console.log(`Steps executed: ${result.steps.length}`);
console.log(`Domain: ${result.domain}`);

// Access step information
for (const step of result.steps) {
  console.log(`  - ${step.name} (${step.type}): ${step.agent}`);
}

// Access execution metadata
console.log(`Execution metadata:`, result.metadata);

Python SDK

from axonflow import AxonFlow

async with AxonFlow(
    agent_url="http://localhost:8080",
    license_key="YOUR_LICENSE_KEY"
) as client:
    # Generate and execute plan in one call
    result = await client.generate_plan(
        query="Research AI governance",
        domain="generic"
    )

    print(f"Plan ID: {result.plan_id}")
    print(f"Steps executed: {len(result.steps)}")

    # Access step information
    for step in result.steps:
        print(f"  - {step.name} ({step.type}): {step.agent}")

    # Access execution result
    print(f"Result: {result.result[:100]}...")

Go SDK

package main

import (
    "context"
    "fmt"
    "github.com/getaxonflow/axonflow-sdk-go"
)

func main() {
    client := axonflow.NewClient(
        axonflow.WithAgentURL("http://localhost:8080"),
        axonflow.WithLicenseKey("YOUR_LICENSE_KEY"),
    )

    ctx := context.Background()

    // Generate and execute plan in one call
    result, err := client.GeneratePlan(ctx, &axonflow.GeneratePlanRequest{
        Query:  "Research AI governance",
        Domain: "generic",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Plan ID: %s\n", result.PlanID)
    fmt.Printf("Steps executed: %d\n", len(result.Steps))

    // Access step information
    for _, step := range result.Steps {
        fmt.Printf("  - %s (%s): %s\n", step.Name, step.Type, step.Agent)
    }

    // Access execution metadata
    fmt.Printf("Execution time: %dms\n", result.Metadata.ExecutionTimeMs)
}

Java SDK

import com.getaxonflow.sdk.AxonFlowClient;
import com.getaxonflow.sdk.models.PlanResponse;

public class MapExample {
    public static void main(String[] args) {
        try (AxonFlowClient client = AxonFlowClient.builder()
                .agentUrl("http://localhost:8080")
                .licenseKey("YOUR_LICENSE_KEY")
                .build()) {

            // Generate and execute plan in one call
            PlanResponse result = client.generatePlan(
                "Research AI governance",
                "generic"  // domain
            );

            System.out.println("Plan ID: " + result.getPlanId());
            System.out.println("Steps executed: " + result.getSteps().size());

            // Access step information
            for (var step : result.getSteps()) {
                System.out.printf("  - %s (%s): %s%n",
                    step.getName(), step.getType(), step.getAgent());
            }
        }
    }
}

Error Codes

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Request body validation failed
`NO_AGENTS_AVAILABLE`	400	No agents match the query or domain
`UNAUTHORIZED`	401	Invalid or missing authentication
`FORBIDDEN`	403	Insufficient permissions
`AGENT_NOT_FOUND`	404	Agent not found
`PLANNING_TIMEOUT`	408	Planning or execution exceeded timeout
`RATE_LIMITED`	429	Rate limit exceeded
`PLANNING_ERROR`	500	Internal planning error
`EXECUTION_ERROR`	500	Plan execution failed
`SERVICE_UNAVAILABLE`	503	Planning engine not initialized

Rate Limits

Tier	Requests/min	Concurrent Plans
Community	60	5
Professional	300	25
Enterprise	1000	100

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702893600

Webhooks (Enterprise)

Enterprise customers can configure webhooks for plan events:

POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["plan.completed", "plan.failed", "step.completed"],
  "secret": "your-webhook-secret"
}

Webhook payload:

{
  "event": "plan.completed",
  "timestamp": "2025-12-18T10:35:00Z",
  "data": {
    "planId": "plan_abc123",
    "status": "completed",
    "totalExecutionTimeMs": 5240
  },
  "signature": "sha256=..."
}

Next Steps

Getting Started - Quick start guide
Step Types - All step type configurations
Planning Patterns - Common patterns

Base URLs​

Prerequisites​

Endpoints​

Generate and Execute Plan​

Request Body​

Example Request (via SDK - Recommended)​

Example Request (via Agent API)​

Response​

Error Responses​

List Agents​

Query Parameters​

Example Request​

Response​

Get Agent Details​

Path Parameters​

Example Request​

Response​

Validate Agent Configuration​

Request Body​

Example Request​

Response (Valid)​

Response (Invalid)​

SDK Examples​

TypeScript SDK​

Python SDK​

Go SDK​

Java SDK​

Error Codes​

Rate Limits​

Webhooks (Enterprise)​

Next Steps​

Base URLs

Prerequisites

Endpoints

Generate and Execute Plan

Request Body

Example Request (via SDK - Recommended)

Example Request (via Agent API)

Response

Error Responses

List Agents

Query Parameters

Example Request

Response

Get Agent Details

Path Parameters

Example Request

Response

Validate Agent Configuration

Request Body

Example Request

Response (Valid)

Response (Invalid)

SDK Examples

TypeScript SDK

Python SDK

Go SDK

Java SDK

Error Codes

Rate Limits

Webhooks (Enterprise)

Next Steps