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 UI orchestration and elicitation.

render / update / dismiss / render_message​

Host‑level UI rendering primitives used by the runtime.

  • Parameters: A2UI payloads (binary/proto in runtime).
  • Returns: null

toast​

Displays a transient notification.

  • Parameters: { "message": "...", "level": "info|warning|error" } (shape may vary by host).
  • Returns: null

elicit​

Shows an elicitation UI to collect user input.

  • Parameters: UiElicitation payload (proto) including requested_schema and/or worka_ui.
  • Returns: null

respond_elicitation​

Resolves an elicitation request.

  • Parameters: { "elicitation_id": "...", "action": "accept|decline|cancel", "content": {...} }
  • Returns: null

Frontend Actions (UI surface)​

The host also supports frontend actions (A2UI worka_action names) such as:

  • open_tab
  • open_dialog
  • open_view

These are UI‑level actions handled by the host when invoked from A2UI.

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.

execute_query​

Executes a SQL query with parameters.

  • Parameters:
    • sql (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 sql string.
    • tx_id (string, optional): Transaction ID from begin_transaction.
  • Returns: An array of objects representing rows.

execute_batch​

Executes a list of SQL statements.

  • Parameters: { "sql": ["...","..."], "tx_id": "optional" }
  • Returns: { "statements_executed": <number> }

begin_transaction / commit_transaction / rollback_transaction​

Transaction lifecycle helpers.

  • Parameters: { "mode": "READ_WRITE|READ_ONLY", "timeout_ms": 0 } for begin_transaction
  • Returns: { "tx_id": "..." } / { "committed": true } / { "rolled_back": true }

Packs can include sql/ migration files in the pack root. The host creates a private schema for the pack and runs those files on install, giving you managed Postgres tables.

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.

worka/brain​

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

Local and cloud LLM tooling.

  • stream_chat_completion
  • list_local_models
  • load_model
  • unload_model
  • uninstall_model

worka/cloud​

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

Cloud‑backed services used by select packs (e.g. messaging, media, places).

  • messaging.send, messaging.inbound, messaging.thread
  • twilio.send
  • media.put, media.get
  • places.search, places.get_details, places.rank_candidates
  • notifications.send

worka/runtime​

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

Pack lifecycle tools.

  • list_installed_packs
  • install_pack
  • uninstall_pack
  • list_pack_views