Skip to main content

Chapter 18: The worka/orchestrator Virtual Pack

TL;DR​

  • The worka/orchestrator pack is a built-in API for the AI engine.
  • It is a "virtual pack," meaning it's a hardcoded address that routes to internal Host functions, not a real pack on disk.
  • To use it, target it with the useTool hook: 
    import { useTool } from '@worka-ai/sdk';
    import { useMemo } from 'react';

    const orchestratorTarget = useMemo(() => ({ tenant: 'worka', name: 'orchestrator' }), []);
    const { call: triggerWorkflow } = useTool('trigger_workflow', orchestratorTarget);
  • Its key tools are upsert_agent, upsert_tool, and trigger_workflow.

Now we arrive at the heart of the platform: the AI Orchestrator itself. How do you, as a pack developer, create agents, define tools for them, and ask them to perform tasks? You do this by communicating with a special, built-in pack: worka/orchestrator.

What is a Virtual Pack?​

Unlike the packs you build, a "virtual pack" doesn't exist as a folder of files on your disk. It is a special address that the Worka Host application listens for. When you make a useTool call targeting a virtual pack, the Host intercepts the request and, instead of forwarding it to an external MCP server, routes it directly to its own internal Rust code.

This is a secure and standardized mechanism that allows sandboxed packs to access core, privileged Host services. You will see this pattern for other virtual packs as well, such as worka/ui for controlling the user interface and worka/db for accessing the database.

The Role of worka/orchestrator​

This virtual pack is your single entry point for all AI-related operations. It exposes a set of powerful tools that allow you to programmatically manage and interact with the AI engine.

How to Use It​

Using the orchestrator is just like calling a tool on any other pack. You use the useTool hook from the SDK and provide the correct target.

Because the target object { tenant: 'worka', name: 'orchestrator' } will be the same for every call, it's a best practice to define it once with useMemo and reuse it.

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

function MyAiComponent() {
  // Define the target for the orchestrator once
  const orchestratorTarget = useMemo(() => ({ tenant: 'worka', name: 'orchestrator' }), []);

  // Now you can get any of its tools
  const { call: upsertAgent } = useTool('upsert_agent', orchestratorTarget);
  const { call: triggerWorkflow } = useTool('trigger_workflow', orchestratorTarget);

  // ... your component logic
}

Overview of Key Tools​

The worka/orchestrator pack provides several crucial tools. The next chapters will cover them in detail, but here is a brief overview:

  • upsert_agent: This tool allows you to create a new AI Agent or update an existing one. You use it to define the agent's persona, its rules, and its core configuration.
  • upsert_tool: This tool registers a tool's schema (its name, description, and parameters) with the orchestrator. This is how an Agent learns what tools are available to it and how to use them.
  • trigger_workflow: This is the tool you call to kick off an AI task. You provide it with a goal and the ID of the agent you want to use, and the orchestrator starts the DAG execution.