Workflow & Multi-Agent Planning API

Execute workflows and leverage multi-agent planning for complex task decomposition through the Orchestrator API.

Overview

The Workflow API provides:

• Workflow Execution: Execute predefined workflows with sequential/parallel steps
• Multi-Agent Planning (MAP): LLM-powered task decomposition and execution
• Execution Tracking: Monitor workflow progress and retrieve results

Base URL: http://localhost:8081 (Orchestrator)

---

Workflow Execution

POST /api/v1/workflows/execute

Execute a workflow definition.

Request:

curl -X POST http://localhost:8081/api/v1/workflows/execute \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": {
      "metadata": {
        "name": "travel-booking",
        "version": "1.0"
      },
      "spec": {
        "steps": [
          {
            "name": "search_flights",
            "type": "mcp_query",
            "connector": "amadeus-travel",
            "statement": "search_flights",
            "parameters": {
              "origin": "SFO",
              "destination": "CDG",
              "departure_date": "2025-06-01"
            }
          },
          {
            "name": "search_hotels",
            "type": "mcp_query",
            "connector": "amadeus-travel",
            "statement": "search_hotels",
            "parameters": {
              "city": "Paris",
              "check_in": "2025-06-01",
              "check_out": "2025-06-07"
            }
          },
          {
            "name": "summarize",
            "type": "llm",
            "prompt": "Summarize the flight and hotel options for a trip from SFO to Paris",
            "depends_on": ["search_flights", "search_hotels"]
          }
        ]
      }
    },
    "input": {
      "budget": 5000,
      "currency": "USD"
    },
    "user": {
      "id": 123,
      "email": "[email protected]",
      "role": "user"
    }
  }'

Request Body:

Field	Type	Required	Description
workflow.metadata.name	string	Yes	Workflow name
workflow.spec.steps	array	Yes	Array of workflow steps
input	object	No	Input data for the workflow
user	object	Yes	User context for audit

Step Types:

Type	Description
mcp_query	Execute a query via MCP connector
mcp_execute	Execute a command via MCP connector
llm	Send prompt to LLM provider
condition	Conditional branching
parallel	Execute steps in parallel

Response (200 OK):

{
  "id": "wf_exec_abc123",
  "status": "completed",
  "workflow_name": "travel-booking",
  "started_at": "2025-01-02T10:00:00Z",
  "completed_at": "2025-01-02T10:00:05Z",
  "steps": [
    {
      "name": "search_flights",
      "status": "completed",
      "process_time": "1.234s",
      "output": {
        "flights": [
          {"airline": "Air France", "price": 850}
        ]
      }
    },
    {
      "name": "search_hotels",
      "status": "completed",
      "process_time": "1.456s",
      "output": {
        "hotels": [
          {"name": "Hotel Eiffel", "price_per_night": 200}
        ]
      }
    },
    {
      "name": "summarize",
      "status": "completed",
      "process_time": "2.123s",
      "output": "I found great options for your trip..."
    }
  ],
  "output": {
    "final_result": "I found great options for your trip..."
  }
}

---

GET /api/v1/workflows/executions/{id}

Get details of a workflow execution.

Request:

curl http://localhost:8081/api/v1/workflows/executions/wf_exec_abc123

Response (200 OK):

{
  "id": "wf_exec_abc123",
  "status": "completed",
  "workflow_name": "travel-booking",
  "started_at": "2025-01-02T10:00:00Z",
  "completed_at": "2025-01-02T10:00:05Z",
  "duration_ms": 5234,
  "steps": [
    {
      "name": "search_flights",
      "status": "completed",
      "started_at": "2025-01-02T10:00:00Z",
      "completed_at": "2025-01-02T10:00:01Z",
      "process_time": "1.234s"
    },
    {
      "name": "search_hotels",
      "status": "completed",
      "started_at": "2025-01-02T10:00:00Z",
      "completed_at": "2025-01-02T10:00:01Z",
      "process_time": "1.456s"
    },
    {
      "name": "summarize",
      "status": "completed",
      "started_at": "2025-01-02T10:00:02Z",
      "completed_at": "2025-01-02T10:00:05Z",
      "process_time": "2.123s"
    }
  ],
  "output": {
    "final_result": "I found great options for your trip..."
  }
}

---

GET /api/v1/workflows/executions

List recent workflow executions.

Request:

curl "http://localhost:8081/api/v1/workflows/executions?limit=10"

Query Parameters:

Parameter	Type	Description
limit	integer	Number of executions to return (default: 10)

Response (200 OK):

{
  "executions": [
    {
      "id": "wf_exec_abc123",
      "workflow_name": "travel-booking",
      "status": "completed",
      "started_at": "2025-01-02T10:00:00Z",
      "duration_ms": 5234
    },
    {
      "id": "wf_exec_def456",
      "workflow_name": "data-pipeline",
      "status": "failed",
      "started_at": "2025-01-02T09:00:00Z",
      "error": "Step 'fetch_data' timed out"
    }
  ],
  "count": 2
}

---

GET /api/v1/workflows/executions/tenant/{tenant_id}

List workflow executions for a specific tenant.

Request:

curl http://localhost:8081/api/v1/workflows/executions/tenant/my-tenant

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "count": 5,
  "executions": [
    {
      "id": "wf_exec_abc123",
      "workflow_name": "travel-booking",
      "status": "completed",
      "started_at": "2025-01-02T10:00:00Z"
    }
  ]
}

---

Multi-Agent Planning (MAP)

POST /api/v1/plan

Submit a complex query for LLM-powered task decomposition and execution.

Request:

curl -X POST http://localhost:8081/api/v1/plan \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Plan a business trip from San Francisco to Paris for June 1-7, find flights under $1000 and 4-star hotels near the Eiffel Tower",
    "domain": "travel",
    "execution_mode": "auto",
    "user": {
      "id": 123,
      "email": "[email protected]",
      "role": "user"
    },
    "context": {
      "budget": 5000,
      "currency": "USD",
      "preferences": {
        "airline_alliance": "SkyTeam",
        "hotel_amenities": ["wifi", "breakfast"]
      }
    }
  }'

Request Body:

Field	Type	Required	Description
query	string	Yes	Natural language query
domain	string	No	Domain hint: travel, healthcare, finance, generic
execution_mode	string	No	Execution mode: auto, parallel, sequential
user	object	Yes	User context (required for governance)
context	object	No	Additional context for planning

Response (200 OK):

{
  "success": true,
  "plan_id": "plan_xyz789",
  "steps": [
    {
      "id": "step_1_search_flights",
      "name": "search_flights",
      "type": "mcp_query",
      "description": "Search for flights from SFO to CDG under $1000",
      "depends_on": [],
      "agent": "amadeus-travel",
      "parameters": {
        "origin": "SFO",
        "destination": "CDG",
        "departure_date": "2025-06-01",
        "return_date": "2025-06-07",
        "max_price": 1000
      }
    },
    {
      "id": "step_2_search_hotels",
      "name": "search_hotels",
      "type": "mcp_query",
      "description": "Search for 4-star hotels near Eiffel Tower",
      "depends_on": [],
      "agent": "amadeus-travel",
      "parameters": {
        "city": "Paris",
        "check_in": "2025-06-01",
        "check_out": "2025-06-07",
        "star_rating": 4,
        "landmark": "Eiffel Tower"
      }
    },
    {
      "id": "step_3_summarize",
      "name": "summarize_options",
      "type": "llm",
      "description": "Create a summary of travel options",
      "depends_on": ["step_1_search_flights", "step_2_search_hotels"]
    }
  ],
  "workflow_execution_id": "wf_exec_abc123",
  "result": "I found excellent options for your Paris trip:\n\n**Flights:**\n- Air France AF123: $850 direct, departing 10:00 AM\n- Delta DL456: $920 with 1 stop\n\n**Hotels:**\n- Hotel Eiffel Palace (4-star): $180/night, 0.5 km from Eiffel Tower\n- Le Meridien Étoile (4-star): $210/night, 1.2 km from Eiffel Tower\n\nTotal estimated cost: $1,930-$2,390 (within your $5,000 budget)",
  "metadata": {
    "tasks_executed": 3,
    "execution_mode": "parallel",
    "execution_time_ms": 4567,
    "tasks": [
      {"name": "search_flights", "status": "completed", "time_ms": 1234},
      {"name": "search_hotels", "status": "completed", "time_ms": 1456},
      {"name": "summarize_options", "status": "completed", "time_ms": 2345}
    ]
  }
}

---

Agent Configuration

GET /api/v1/agents

List available agents for multi-agent planning.

Request:

curl http://localhost:8081/api/v1/agents

Response (200 OK):

{
  "agents": [
    {
      "id": "amadeus-travel",
      "name": "Amadeus Travel Agent",
      "domain": "travel",
      "capabilities": ["search_flights", "search_hotels", "search_activities"],
      "connector_type": "amadeus",
      "enabled": true
    },
    {
      "id": "salesforce-crm",
      "name": "Salesforce CRM Agent",
      "domain": "crm",
      "capabilities": ["query_contacts", "query_opportunities", "create_lead"],
      "connector_type": "salesforce",
      "enabled": true
    },
    {
      "id": "llm-analyst",
      "name": "LLM Analysis Agent",
      "domain": "generic",
      "capabilities": ["analyze", "summarize", "recommend"],
      "connector_type": "llm",
      "enabled": true
    }
  ],
  "count": 3
}

---

GET /api/v1/agents/{id}

Get details of a specific agent.

Request:

curl http://localhost:8081/api/v1/agents/amadeus-travel

Response (200 OK):

{
  "id": "amadeus-travel",
  "name": "Amadeus Travel Agent",
  "description": "Agent for searching flights, hotels, and activities via Amadeus GDS",
  "domain": "travel",
  "capabilities": [
    {
      "name": "search_flights",
      "description": "Search for flights between airports",
      "parameters": {
        "origin": {"type": "string", "required": true},
        "destination": {"type": "string", "required": true},
        "departure_date": {"type": "string", "required": true},
        "return_date": {"type": "string", "required": false}
      }
    },
    {
      "name": "search_hotels",
      "description": "Search for hotels in a city",
      "parameters": {
        "city": {"type": "string", "required": true},
        "check_in": {"type": "string", "required": true},
        "check_out": {"type": "string", "required": true}
      }
    }
  ],
  "connector_type": "amadeus",
  "enabled": true,
  "health": {
    "status": "healthy",
    "last_check": "2025-01-02T10:00:00Z"
  }
}

---

GET /api/v1/agents/domain/{domain}

Get agents by domain.

Request:

curl http://localhost:8081/api/v1/agents/domain/travel

Response (200 OK):

{
  "domain": "travel",
  "agents": [
    {
      "id": "amadeus-travel",
      "name": "Amadeus Travel Agent",
      "capabilities": ["search_flights", "search_hotels", "search_activities"],
      "enabled": true
    }
  ],
  "count": 1
}

---

POST /api/v1/agents/validate

Validate an agent configuration.

Request:

curl -X POST http://localhost:8081/api/v1/agents/validate \
  -H "Content-Type: application/json" \
  -d '{
    "id": "custom-agent",
    "name": "Custom Data Agent",
    "domain": "analytics",
    "connector_type": "postgres",
    "connector_config": {
      "name": "analytics-db"
    },
    "capabilities": ["query_metrics", "aggregate_data"]
  }'

Response (200 OK):

{
  "valid": true,
  "agent": {
    "id": "custom-agent",
    "name": "Custom Data Agent",
    "domain": "analytics"
  },
  "warnings": [
    "Connector 'analytics-db' not found - agent will be unavailable until connector is configured"
  ]
}

---

Execution Status Values

Status	Description
pending	Execution queued but not started
running	Execution in progress
completed	All steps completed successfully
failed	One or more steps failed
timeout	Execution exceeded timeout
cancelled	Execution was cancelled

---

Error Responses

HTTP Status	Error Code	Description
400	INVALID_WORKFLOW	Workflow definition is invalid
400	MISSING_USER_CONTEXT	User context required for governance
404	EXECUTION_NOT_FOUND	Workflow execution not found
500	PLANNING_FAILED	LLM planning engine failed
504	EXECUTION_TIMEOUT	Workflow exceeded timeout

---

Next Steps

• Agent Endpoints - Policy enforcement API
• MCP Connectors - Configure data connectors
• Integration Guides - Framework integrations