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

# Copilot Agents

> Mastra agents behind the CopilotKit runtime — how they are invoked from both the webapp and Temporal, and how their actions are audited

# Copilot Agents

`@cona/agents` — Mastra-based agents routed through Vercel AI Gateway. Two entry points:
the CopilotKit runtime in the webapp, and a Temporal activity for reconciliation.

## Wiring

```mermaid theme={null}
flowchart TB
    User["Organisation user"]
    UI["copilot UI<br/>@copilotkit/react-core"]
    Route["api/copilotkit<br/>InMemoryAgentRunner"]
    Flag["assertCopilotEnabled"]

    Memory["getCopilotMemory"]
    Instructions["buildAgentInstructions<br/>selectKnowledge"]

    AgUI["createConaAGUIAgents"]
    Mastra["createConaMastra"]
    Gateway["gateway.ts<br/>prefix vercel/"]
    AIGW["Vercel AI Gateway"]

    Activity["run-reconciliation-agent<br/>Temporal activity"]
    Suggest["reconciliation/suggest.ts"]

    Audit[("copilot_runs<br/>copilot_actions<br/>copilot_memory")]

    User --> UI --> Route
    Route --> Flag
    Route --> Memory
    Route --> Instructions
    Route --> AgUI
    AgUI --> Mastra
    Mastra --> Gateway --> AIGW

    Activity --> Suggest
    Suggest --> Mastra

    Route --> Audit
    Activity --> Audit

    classDef app fill:#dbe2fb,stroke:#3B56C5,color:#111827
    classDef pkg fill:#e8eafd,stroke:#4967E6,color:#111827
    classDef external fill:#fff4dd,stroke:#c98a12,color:#111827
    classDef async fill:#e3f7ea,stroke:#2f9e5c,color:#111827
    classDef data fill:#fde8e8,stroke:#c53b3b,color:#111827
    classDef actor fill:#eceff4,stroke:#64748b,color:#111827

    class UI,Route,Flag,Memory app
    class Instructions,AgUI,Mastra,Gateway,Suggest pkg
    class AIGW external
    class Activity async
    class Audit data
    class User actor
```

## Package surface

`packages/agents/src/`:

| File                        | Role                                                                       |
| --------------------------- | -------------------------------------------------------------------------- |
| `agents.ts`                 | builds Mastra `Agent` instances; one id, `CONA_COPILOT_AGENT_ID`           |
| `ag-ui.ts`                  | `createConaAGUIAgents` — AG-UI protocol binding for CopilotKit             |
| `mastra.ts`                 | `createConaMastra` — the Mastra runtime                                    |
| `gateway.ts`                | model routing                                                              |
| `client.ts`                 | client wiring                                                              |
| `instructions/`             | `buildAgentInstructions` plus a `knowledge/` subtree and `selectKnowledge` |
| `reconciliation/suggest.ts` | the reconciliation suggestion agent                                        |
| `types.ts`                  | shared types                                                               |

Consumers: webapp (10 imports), `@cona/temporal-workflows` (3 imports).

## Model routing

Every model id is forced through Vercel AI Gateway — `agents.ts:27-29` prefixes with
`vercel/` unless already prefixed. There is no direct provider SDK call anywhere in the
package.

## Two invocation paths

### Interactive — CopilotKit

`apps/webapp/app/api/copilotkit/route.ts` runs on the Node runtime with CopilotKit's
`InMemoryAgentRunner` from `@copilotkit/runtime/v2`. Before anything else it calls
`assertCopilotEnabled` — the feature is flag-gated.

The route composes three inputs into the agent's instructions:

1. **Copilot memory** — `getCopilotMemory`, persisted per organisation
2. **Knowledge selection** — `selectKnowledge` picks relevant instruction fragments
3. **Task-specific instructions** — e.g. `getReconciliationAgentInstructions`

Agent ids are validated with `isConaCopilotAgentId` before dispatch, so an arbitrary
agent name in the request envelope cannot reach the runner.

### Background — Temporal

`packages/temporal-workflows/src/activities/reconciliation/run-reconciliation-agent.ts`
invokes the same agents from `reconciliationAgentSuggestionsWorkflow`, so suggestions are
generated in bulk rather than only on demand. See
[Reconciliation & Payments](/architecture/reconciliation-payments).

## Audit

Three tables in the Platform cluster:

| Table             | Records                           |
| ----------------- | --------------------------------- |
| `copilot_runs`    | one row per agent invocation      |
| `copilot_actions` | individual actions an agent took  |
| `copilot_memory`  | persisted per-organisation memory |

The `copilot-audit` core domain owns writes. `reconciliation-agent` imports it **7 times**
— the strongest single edge into that domain, because every suggestion, approval, and
rejection is recorded.

Users can inspect and edit memory at
`(settings)/(configuration)/settings/copilot-memory`.

## Notes

**Agents propose, humans dispose.** Nothing the reconciliation agent produces is applied
automatically — `execute-reconciliation-agent-suggestion.ts` runs only after approval, and
`reject-reconciliation-agent-suggestion.ts` records the alternative.

**There is a learning loop.** `learn-approved-candidate-allocation-iban.ts` records the
IBAN association once a human approves, and `get-manual-reconciliation-examples.ts` feeds
prior manual work back as examples.

**Copilot is flag-gated.** `assertCopilotEnabled` guards the route, so the feature can be
disabled per environment.

**Instructions are assembled, not hardcoded.** `buildAgentInstructions` combines the
knowledge subtree, organisation memory, and task instructions at request time.