Skip to main content

Multi-Agent Planning (MAP)

Multi-Agent Planning (MAP) is AxonFlow's orchestration layer for coordinating multiple AI agents to accomplish complex tasks. MAP breaks down user requests into subtasks, assigns them to specialized agents, and aggregates results—all while enforcing governance policies at every step.

MAP is optional

AxonFlow can be used purely as a governance layer around existing agent frameworks (LangChain, LangGraph, CrewAI, AutoGen) without adopting MAP:

See Choosing a Mode for detailed guidance.

How It Works​

Key Components​

Planning Engine​

The Planning Engine analyzes incoming requests and generates execution plans:

  • Query Analysis: Detects intent and required capabilities
  • Agent Selection: Chooses appropriate agents based on capabilities
  • Step Generation: Creates execution steps with dependencies
  • Domain Templates: Uses domain-specific templates (travel, healthcare, finance)

Agent Registry​

The Agent Registry manages available agents:

ModeDescriptionEdition
File-basedAgents defined in YAML configuration filesCommunity
Database-backedAgents stored in PostgreSQL with CRUD APIEnterprise
HybridBoth file-based and database agents (DB takes priority)Enterprise

Workflow Engine​

The Workflow Engine executes plans:

  • Step Execution: Runs each step type (llm-call, connector-call, etc.)
  • Dependency Management: Ensures steps run in correct order
  • Parallel Execution: Runs independent steps simultaneously
  • Template Variables: Passes data between steps via {{input.key}} and {{steps.name.output}}

Step Types​

MAP supports five step types for different operations:

Step TypeDescriptionUse Case
llm-callInvoke an LLM provider for inferenceText generation, analysis
connector-callQuery an MCP connectorDatabase queries, API calls
conditionalBranch based on conditionsDecision logic
function-callExecute a custom functionData transformation
api-callCall an external HTTP APIThird-party integrations

See Step Types for detailed configuration.

Agent Types​

TypeDescriptionExample
SpecialistSingle-domain expertiseFlight search, data analysis
CoordinatorOrchestrates other agentsTrip planner, workflow manager

Execution Modes​

ModeDescriptionWhen to Use
SequentialSteps run in order, each receiving previous outputDependent tasks
ParallelIndependent steps run simultaneouslyMultiple data sources
ConditionalSteps run based on conditionsDecision trees

Policy Enforcement​

MAP integrates with AxonFlow's policy engine to enforce governance at plan execution time. Before a plan executes, policies are evaluated against the plan context.

How Policy Enforcement Works​

Plan Execution Request → Policy Evaluation → Execute or Block
                              ↓
                    ┌─────────────────────┐
                    │ Dynamic Policies    │
                    │ • Risk thresholds   │
                    │ • Cost limits       │
                    │ • Model restrictions│
                    │ • Domain rules      │
                    └─────────────────────┘

Policy Evaluation in ExecutePlan​

When you call executePlan(), the following happens:

  1. Policy Evaluation: Dynamic policies are evaluated against the plan context
  2. Decision: allow, block, or require_approval
  3. PolicyInfo in Response: The response includes policy evaluation details
const result = await axonflow.executePlan(planId);

// PolicyInfo shows what policies were evaluated
console.log(result.policyInfo);
// {
//   allowed: true,
//   applied_policies: ["cost-limit", "model-restriction"],
//   risk_score: 0.2
// }

Blocked Plans​

If policies block execution, the API returns HTTP 403 with details:

{
  "success": false,
  "error": "Plan execution blocked by policy",
  "policy_info": {
    "allowed": false,
    "block_reason": "Risk score exceeds threshold",
    "matched_policies": ["high-risk-block"]
  }
}

Audit Logging​

All MAP operations are automatically logged to the audit trail for compliance and debugging.

Operations Logged​

Request TypeWhen LoggedData Captured
plan_createdPlan is storedplan_id, query, domain, step_count
plan_execution_startedExecution beginsplan_id, domain
plan_completedExecution succeedsplan_id, final_status, policy_info
plan_failedExecution failsplan_id, error_message

Querying Plan Audit Logs​

Use the SDK audit search methods to query MAP audit logs:

# Python SDK
from axonflow.types import AuditSearchRequest
from datetime import datetime, timedelta, timezone

response = await client.search_audit_logs(
    AuditSearchRequest(
        start_time=datetime.now(timezone.utc) - timedelta(hours=1),
        limit=100,
    )
)

# Filter by plan operations
for entry in response.entries:
    if entry.request_type.startswith("plan_"):
        print(f"{entry.request_type}: {entry.query_summary}")

See Audit Logging for more details.

Community vs Enterprise​

FeatureCommunityEnterprise
File-based agent registry✅✅
Plan generation✅✅
Sequential execution✅✅
Parallel execution✅✅
All 5 step types✅✅
Decision & Execution Replay API✅✅
Policy enforcement in plans✅✅
Plan audit logging✅✅
Database-backed agents✅
Agent CRUD API✅
Agent versioning✅
Multi-tenant isolation (RLS)✅
Execution analytics dashboard✅
Compliance export (PDF/CSV)✅

Quick Example​

1. Define an Agent​

# agents/research-agent.yaml
apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: research-agent
  domain: generic
spec:
  type: specialist
  description: Research and summarize information
  capabilities:
    - research
    - summarization
  llm:
    provider: openai
    model: gpt-4

2. Generate a Plan​

All MAP requests go through the AxonFlow Agent (port 8080), which handles authentication and policy enforcement before routing to the Orchestrator.

# Generate a plan via Agent proxy
curl -X POST http://localhost:8080/api/request \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: my-org" \
  -d '{
    "query": "Research the benefits of remote work",
    "request_type": "multi-agent-plan",
    "context": {
      "domain": "generic"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123",
    "steps": [...]
  },
  "policy_info": {
    "static_checks": ["sql_injection", "pii_detection"],
    "processing_time": "4.2ms"
  }
}

3. Execute the Plan​

# Execute the generated plan
curl -X POST http://localhost:8080/api/request \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: my-org" \
  -d '{
    "query": "execute",
    "request_type": "execute-plan",
    "context": {
      "plan_id": "plan_abc123"
    }
  }'

Using the SDK​

For production use, prefer the SDK methods which handle authentication and error handling:

TypeScript:

// Generate a plan
const plan = await axonflow.generatePlan(
  "Research the benefits of remote work",
  "generic"  // domain
);

// Execute the plan
const result = await axonflow.executePlan(plan.planId);

Go:

// Generate a plan
plan, err := client.GeneratePlan(
    "Research the benefits of remote work",
    "generic", // domain
)

// Execute the plan
result, err := client.ExecutePlan(plan.PlanID)

Next Steps​

Enterprise Features​

For database-backed agents, CRUD APIs, versioning, and analytics: