Skip to main content

Appendix C: Virtual Pack Tool Reference

This document provides a reference for the tools available on Worka's built-in virtual packs. You call these tools from your pack's UI or backend by providing the appropriate target.

worka/ui​

Target: { tenant: 'worka', name: 'ui' }

Provides tools for interacting with the main Worka application user interface.

open_tab​

Asks the Worka Host to open a new tab in the main content area.

  • Parameters:
    • view (string, required): The name of the view to render in the tab (e.g., 'MyView'). This must correspond to a view component defined in the target pack.
    • title (string, required): The text to display on the tab.
    • pack_origin (object, optional): An object with tenant, name, and version specifying which pack the view belongs to. If omitted, it defaults to the pack making the call.
  • Returns: null

worka/db​

Target: { tenant: 'worka', name: 'db' }

Provides secure, brokered access to the database. All queries made through this pack are automatically executed within the calling pack's private, isolated schema.

db_query​

Executes a SQL query with parameters.

  • Parameters:
    • query (string, required): The SQL query string to execute. Use placeholders like $1, $2 for parameters.
    • params (array, optional): An array of values corresponding to the placeholders in the query string.
  • Returns: An array of objects, where each object represents a row from the query result.

worka/orchestrator​

Target: { tenant: 'worka', name: 'orchestrator' }

Provides the primary API for interacting with the AI engine, managing agents, and running workflows.

upsert_agent​

Creates a new agent or updates an existing one.

  • Parameters: An object containing the agent's properties.
    • name (string, required): A unique, machine-readable name for the agent.
    • description (string, required): The detailed persona, background, and high-level strategy for the agent.
    • rules (array, optional): An array of rule objects to provide state-based guidance.
  • Returns: The full agent object that was created or updated.

upsert_tool​

Registers a tool's schema with the orchestrator, making it available for agents to use.

  • Parameters:
    • name (string, required): The name of the tool. Must match the name in the MCP server.
    • description (string, required): A natural language description of what the tool does, for the LLM to understand.
    • schema (object, required): A JSON Schema object describing the tool's parameters.
  • Returns: The full tool object that was created or updated.

trigger_workflow​

Starts a new AI workflow.

  • Parameters:
    • agent_id (number, required): The ID of the agent that should execute the task.
    • prompt (string, required): The initial high-level goal or query.
    • conversation_id (number, optional): Provide an existing ID to continue a conversation, or omit to start a new one.
  • Returns: An object containing the conversation_id for the newly created workflow: { "conversation_id": 12345 }.

get_conversation_events​

Fetches the log of events for a given workflow to monitor its progress and results.

  • Parameters:
    • conversation_id (number, required): The ID of the conversation to fetch events for.
  • Returns: An array of event objects, detailing each step of the workflow's execution.