Skip to main content
The companion agent is the AI assistant that powers the Chat & AI panel in the workspace. It is automatically provisioned for each user when they open the workspace, and its capabilities are defined by the modules, runtime, and prompt configured at the project and task template level.

​
How It Works

When a user opens the workspace chat, the platform:
  1. Loads the project’s companion configuration from project settings (baseline modules, runtime, and prompt)
  2. If the user is working on a task created from a template, loads the task template’s companion configuration and merges it
  3. Creates (or reuses) a companion agent instance with the resolved configuration
  4. The agent can then use the configured modules as tools when responding to user messages
The merging strategy ensures task-specific tools are available without losing the project-wide baseline:
SettingMerge behavior
ModulesUnion of project + task template modules (deduplicated)
PromptTask template overrides project if set
Agent RuntimeTask template overrides project if set

​
Project-Level Configuration

The project companion configuration provides the baseline for all workspace chat sessions in the project. Configure it in Project Settings > Companion.

​
Agent Runtime

Specify the agent runtime using an orgSlug/runtimeSlug reference (e.g., kodexa/claude-code-agent). Leave empty to let the platform auto-resolve the appropriate runtime.

​
Modules

Add modules that should be available as tools to the companion agent. These are specified as module references (e.g., kodexa/my-extraction-model:1.0.0). Click Add Module to browse and select from available modules in your organization.

​
System Prompt

Provide a system prompt that guides the companion’s behavior. This prompt is sent to the agent runtime alongside every user message, giving the agent context about the project’s purpose and how it should assist users.
A good system prompt describes the project’s domain, the types of documents being processed, and what kind of assistance users typically need. For example: “You are assisting with invoice processing. Help users review extracted line items, validate totals, and flag discrepancies.”

​
Task Template Configuration

Task templates can extend the project’s companion configuration with additional modules and overrides specific to the task type. Configure this in the Companion tab of the Task Template Editor.
The Companion tab is only available for non-planned task templates. Planned task templates use Agent plan steps with their own module configuration instead.

​
Agent Runtime Override

Optionally override the project-level runtime for tasks using this template using an orgSlug/runtimeSlug reference. Leave empty to inherit the project setting.

​
Additional Modules

Modules added here are merged with (not replacing) the project-level companion modules. This lets you add task-specific tools without losing the project baseline. For example, if the project configures a general extraction module and the task template adds a validation module, the companion agent will have both available when a user opens a task created from that template.

​
Prompt Override

If set, this prompt replaces the project-level system prompt for tasks using this template. This allows task-specific instructions while still inheriting the project’s module configuration.

​
Project Template YAML

The companion configuration is stored in options.companion for the project and metadata.companion for task templates. When building project templates, include the companion configuration in YAML:

​
Project Options

options:
  companion:
    agentRuntimeRef: "kodexa/my-runtime"  # optional, auto-resolved if omitted
    moduleRefs:
      - "kodexa/document-qa-model:1.0.0"
      - "kodexa/extraction-model:2.0.0"
    prompt: |
      You are an AI assistant for invoice processing.
      Help users review extracted data and flag discrepancies.

​
Task Template Metadata

taskTemplates:
  - slug: review-task
    title: Invoice Review
    metadata:
      companion:
        moduleRefs:
          - "kodexa/validation-model:1.0.0"
        prompt: |
          You are assisting with invoice review.
          Focus on validating line items against the source PDF.