Skip to main content

Chapter 20: Triggering and Monitoring Workflows

TL;DR​

  1. Call trigger_workflow on worka/orchestrator.
  2. Provide agent_id and prompt.
  3. The tool returns immediately with a conversation_id.
  4. The workflow runs asynchronously; use conversation_id to fetch events.

With your agents and tools registered, you have everything you need to set the AI in motion. This is done by triggering a workflow.

Step 1: Call trigger_workflow​

The primary entry point to the AI engine is the trigger_workflow tool, available on the worka/orchestrator virtual pack. This tool tells the Orchestrator to start a new task.

You can call it from backend code or from A2UI.

Backend example (Rust):

let client = McpClient::inproc();
let response = client.call(
  "worka/orchestrator",
  "trigger_workflow",
  json!({ "agent_id": 12345, "prompt": "Summarize the latest AI news." })
).await?;
// response contains conversation_id

A2UI example:

{
  "type": "button",
  "props": {
    "label": "Start Workflow",
    "onClick": {
      "type": "worka_action",
      "target": "worka/orchestrator",
      "tool": "trigger_workflow",
      "input": { "agent_id": 12345, "prompt": "Summarize the latest AI news." }
    }
  }
}

Parameters​

  • agent_id (number, required): The unique ID of the agent you want to assign this task to.
  • prompt (string, required): The initial, high-level goal for the agent.
  • conversation_id (number, optional): If you want to continue a previous task, you can provide its ID here. If omitted, a new conversation is created.

Step 2: Understanding the Asynchronous Response​

A critical concept to understand is that AI workflows can take a long time to complete. A research task might take several minutes. Therefore, the trigger_workflow tool does not wait for the task to finish.

It returns immediately with a conversation_id. Use this ID to track progress and results.

Step 3: What Happens in the Background?​

As soon as you call trigger_workflow, the Orchestrator springs into action behind the scenes:

  1. It creates a new Conversation in the database, identified by the conversation_id it just returned to you.
  2. It creates the very first Step in the DAG for this conversation: a prompt_llm step.
  3. This initial step contains your prompt and the target agent_id.
  4. The worker loop immediately picks up this first step, and the Agent begins the planning process, generating the next steps in the DAG.

Step 4: Monitoring the Workflow​

Since the process is asynchronous, you need a way to check on its progress and get the final result. Every action the Orchestrator takes—creating a step, a tool succeeding, a tool failing, an agent responding—is recorded as an Event in the database, linked to the conversation_id.

Your pack can fetch these events to display a real‑time timeline or retrieve the final output. Use tools like get_conversation_events on the orchestrator to read event streams.