Skip to content
2 min read · 377 words

API — Workflows

POST /agents/{id}/workflows/email — run the multi-agent email workflow

Requires email_analyzer → 403 otherwise. Pipeline internals: Email Workflow.

Body (MultiAgentEmailWorkflowRequest):

FieldTypeDefaultMeaning
email_textstringrequiredthe inbound email
create_tasksbooltruerun the task stage (also needs the task_creator tool)
bash
curl -X POST http://localhost:8001/agents/1/workflows/email \
  -H "Content-Type: application/json" \
  -d '{"email_text": "Production API is down since 09:00 UTC. Need a status update within the hour.", "create_tasks": true}'
json
{
  "email_text": "Production API is down since 09:00 UTC...",
  "analysis": {
    "summary": "Outage report requesting a status update within the hour.",
    "intent": "incident report",
    "priority": "high",
    "deadline": null,
    "action_items": ["Investigate API outage", "Send status update within the hour"],
    "suggested_reply": "..."
  },
  "tasks_created": [
    { "id": 11, "title": "Investigate API outage", "priority": "high", "status": "open", "...": "..." }
  ],
  "suggested_reply": "Thank you for the report. We are investigating...",
  "review": {
    "approved": true,
    "quality_score": 0.91,
    "issues": [],
    "recommendation": "Send the reply and begin the incident task immediately."
  }
}

Side effects: 1 WorkflowRun + up to 4 WorkflowSteps + 3–4 ToolCalls (LLM stages costed) + 0..n Tasks. 500 on any stage failure — run marked failed, workflow_error step written; tasks created before the failure persist. Latency: several seconds (three sequential LLM calls).

GET /agents/{id}/workflow-runs — list workflow runs

200 → WorkflowRunResponse[], newest first:

json
[{
  "id": 3, "agent_id": 1,
  "workflow_name": "multi_agent_email_workflow",
  "input_text": "Production API is down...",
  "final_output": "{\"analysis\": {...}, \"tasks_created\": [...], \"suggested_reply\": \"...\", \"review\": {...}}",
  "status": "success",
  "quality_score": "0.91",
  "error_message": null,
  "created_at": "2026-07-16T10:20:00"
}]

Notes: final_output is a JSON string (parse it client-side); quality_score is a string; status ∈ running (in flight or crashed), success, failed.

GET /agents/workflow-runs/{run_id}/steps — one run's trace

404 if the run doesn't exist. 200 → WorkflowStepResponse[], oldest first — the flight recorder:

json
[
  { "step_name": "analysis_agent",  "status": "success", "latency_ms": 1650, "input_data": "...", "output_data": "{...}" },
  { "step_name": "task_agent",      "status": "success", "latency_ms": 3,    "output_data": "[{...}]" },
  { "step_name": "reply_agent",     "status": "success", "latency_ms": 2100, "output_data": "Thank you..." },
  { "step_name": "reviewer_agent",  "status": "success", "latency_ms": 1900, "output_data": "{\"approved\": true, ...}" }
]

A failed run's trace ends with a workflow_error step whose error_message names the exception. input_data/output_data are JSON strings where the payload was structured.

PreviousTasks & EmailNextDocuments & RAG