> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Companion Agent

> Configure the AI companion agent that powers Kodexa workspace chat and task assistance, including modules, runtime, prompts, and workspace bindings.

The **companion agent** is the AI assistant that powers the [Chat & AI](https://developer.kodexa.ai/studio/workspace/chat-and-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:

| Setting | Merge behavior |
| - | - |
| **Modules** | Union of project + task template modules (deduplicated) |
| **Prompt** | Task template overrides project if set |
| **Agent Runtime** | Task 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.

> [!TIP]
>
> 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](https://developer.kodexa.ai/studio/project/task-templates).

> [!NOTE]
>
> The Companion tab is only available for non-planned task templates. Planned task templates use [Agent plan steps](https://developer.kodexa.ai/studio/project/planning-mode) 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](https://developer.kodexa.ai/guides/project-templates/building-project-templates.md), include the companion configuration in YAML:

### Project Options

```yaml theme={null}
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

```yaml theme={null}
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.
```

## Related Documentation

* [Chat & AI](https://developer.kodexa.ai/studio/workspace/chat-and-ai) — Using the workspace chat interface
* [Task Templates](https://developer.kodexa.ai/studio/project/task-templates) — Configuring task template settings
* [Project Settings](https://developer.kodexa.ai/studio/project/settings-and-options) — Project-level configuration
* [Assistants](https://developer.kodexa.ai/concepts/assistants) — Understanding assistant types including agentic assistants
* [Project Template Structure](https://developer.kodexa.ai/concepts/project_template_structure.md) — Complete template reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.