Skip to content

Async request lifecycle

Status: Current | Last reviewed: 2026-05-28

How a triggered workflow runs end to end. Async work happens outside any conversation: post-call analysis, batch enrichment, scheduled jobs, agent-emitted background tasks.

The path

Trigger source
  ├─ conversation lifecycle event (start / end / message)
  ├─ inbound webhook (email, SMS, PagerDuty, Salesforce)
  ├─ scheduled (cron)
  └─ direct API call (ai-manager, agent tool)
       │
       ▼
trigger_rules table       (matches event → workflow_config_id)
       │
       ▼
async-agent consumer      (RabbitMQ queue)
       │
       ▼
workflow_graph_builder    (loads workflow_versions.config, builds LangGraph StateGraph)
       │
       ▼
LangGraph execution       (nodes: tool, llm, foreach, human_review, code, …)
       │
       ▼
Output sinks              (write to conversation, post to webhook, store result, escalate)

Trigger sources

Source How it fires Example
Conversation lifecycle conversation-api writes a row to trigger_rules matches via pre/post filters "After every call ends, score CSAT"
Inbound webhook Lambda (e.g., email-ingest-lambda) POSTs to async-agent "When a customer emails support@, classify and route"
Scheduled Cron entry in workflow definition "Every hour, sync FedEx tickets"
Direct API ai-manager API or an agent tool calls /workflows/run Manual run from the UI

See workflow-triggers.md for the exact match logic.

async-agent

Python service at apps/async-agent. One Overmind process in Vanguard; replicated as a Deployment in cluster.

The consumer (app/workers/consumer.py) polls RabbitMQ. For each job:

  1. Load workflow_versions.config for the matched workflow.
  2. Build a LangGraph StateGraph via workflow_graph_builder.py.
  3. Execute, passing WorkflowInputs (the trigger payload).
  4. Persist run state to workflow_runs and emit lifecycle events.

See langgraph-construction.md for how the graph is shaped.

Node types

Workflow nodes are registered in app/nodes/registry.py and implemented one-per-file under app/nodes/:

  • tool — invoke an MCP tool via agent-host.
  • llm — single LLM call with structured output.
  • foreach — iterate a collection, fan out child runs.
  • human_review — pause and wait for an approval row.
  • code — execute sandboxed Python via code-executor.
  • pii_redaction — multi-provider PII scrub (Comprehend, DLP, Azure Language).
  • branch / condition — graph routing.

Adding a node type: write the implementation, register it, add the schema entry in shared/workflow-node-types, surface it in ai-manager workflow editor.

Output sinks

A workflow can:

  • Append messages or events to a conversations row (post-call summarization, agent assist).
  • POST to an external webhook (configured per workflow).
  • Write to cases or domain-specific tables.
  • Emit an event via event-publisher for cross-cloud fan-out.
  • Escalate to a human_review queue.

State and durability

Layer Where Survives restart?
Job queue RabbitMQ (Vanguard) / Amazon MQ (AWS) Yes
Run state workflow_runs (Postgres) Yes
LangGraph checkpoint workflow_run_checkpoints (Postgres) Yes — long-running workflows resume from checkpoint
In-flight node async-agent process memory No — restarts replay from last checkpoint

See also