Chapter 20: Triggering and Monitoring Workflows

TL;DR

1. Call the trigger_workflow tool on the worka/orchestrator pack.
2. Provide parameters: You must provide the agent_id you want to use and the initial prompt (the user's goal).

   const { call: trigger, data } = useTool('trigger_workflow', orchestratorTarget);
   
   trigger({
     agent_id: 12345,
     prompt: "Write a summary of the latest AI news."
   });

3. Get the conversation_id: The tool returns immediately with a conversation_id. It does not wait for the AI to finish.

   // `data` from the hook would contain:
   { "conversation_id": 67890 }

4. The workflow runs in the background. You use the conversation_id to fetch events, monitor progress, and retrieve the final results.

---

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: The trigger_workflow Tool

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.

Let's look at how you would call it from a UI component.

import { useTool } from '@worka-ai/sdk';
import { useMemo, useState } from 'react';

function WorkflowTrigger() {
  const [prompt, setPrompt] = useState('');
  const orchestratorTarget = useMemo(() => ({ tenant: 'worka', name: 'orchestrator' }), []);
  const { call: trigger, data: convoData } = useTool('trigger_workflow', orchestratorTarget);

  const handleStart = () => {
    // The ID of the 'research-agent' we created in the last chapter
    const researchAgentId = 12345; 

    trigger({
      agent_id: researchAgentId,
      prompt: prompt,
    });
  };

  return (
    <VStack>
      <Input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
      <Button onClick={handleStart}>Start Workflow</Button>
      {convoData && <Text>Started Conversation ID: {convoData.conversation_id}</Text>}
    </VStack>
  );
}

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.

The data you get back from the useTool hook will contain the unique identifier for this new workflow: the conversation_id.

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's UI can then periodically fetch these events to display a real-time view of the AI's progress or to retrieve the final output once the workflow is complete. You would do this by calling another tool on the orchestrator, such as get_conversation_events.