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: a hardcoded address that routes to host internals, not a real pack on disk.
  • You call it like any other pack tool using MCP requests (from backend code or via A2UI actions).
  • Key tools include upsert_agent, upsert_tool, and trigger_workflow.

The Orchestrator is the AI execution engine of Worka. Pack developers interact with it through a special, built‑in pack named worka/orchestrator.

What is a Virtual Pack?​

Virtual packs are host‑owned services that expose tools through the same MCP interface as normal packs. They don’t exist as folders on disk. The Host intercepts tool calls to these addresses and routes them to internal Rust code.

This lets sandboxed packs access privileged services safely and consistently. Examples include:

  • worka/orchestrator (AI workflows)
  • worka/ui (elicitation + UI control)
  • worka/db (scoped database access)

The Role of worka/orchestrator​

worka/orchestrator is your entry point for AI‑driven workflows. It exposes tools to:

  • register agent personas (upsert_agent)
  • register tool schemas (upsert_tool)
  • trigger workflows (trigger_workflow)

How to Call It​

You can call orchestrator tools from:

  1. Backend code inside your pack (using the in‑process MCP client).
  2. A2UI actions in your views (the host routes these to MCP).

Example (Backend / Rust)​

// Pseudocode – exact SDK API may differ
let client = McpClient::inproc();
client.call(
  "worka/orchestrator",
  "upsert_agent",
  json!({ "name": "research-agent", "description": "..." })
).await?;

Example (A2UI Action)​

{
  "type": "button",
  "props": {
    "label": "Start",
    "onClick": {
      "type": "worka_action",
      "target": "worka/orchestrator",
      "tool": "trigger_workflow",
      "input": { "agent_id": 123, "prompt": "Draft a reply." }
    }
  }
}

Key Tools (Overview)​

  • upsert_agent: create or update an AI agent persona.
  • upsert_tool: register the schema of a tool so agents can reason about it.
  • trigger_workflow: start an AI workflow asynchronously.