> ## 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.

# Troubleshooting

> Common issues when working with the Kodexa Agent in the project workspace, and how to get unstuck.

When the agent does not behave the way you expect, the answer is almost always in one of three places: the **companion configuration**, the **channel context**, or the **channel history**. Walk through these in order.

## The Agent Does Not Know About A Resource

Symptom: you ask the agent about a resource the project clearly uses, and it says it cannot see it.

Check:

* **Channel.** Are you in the right channel? The task channel scopes context to that task; the project channel sees the whole project.
* **Bindings.** Is the resource actually bound to this project? Ask *"What's currently bound to this project?"* in the project channel.
* **Module bindings.** If the resource is exposed through a module, is the module bound on the **Project Settings → Companion** tab? See [Configure the Companion](/guides/kodexa-agent/configuring-the-companion).

## The Agent Says A Skill Is Not Enabled

Symptom: you ask for an authoring action — *"add a step to the activity plan"* — and the agent replies that the relevant skill is not enabled on its runtime.

What it means: the companion runtime in use does not have the skill that exposes that capability.

Fix: ask your org admin to publish or share a runtime with the required skill enabled, then update the project's runtime selection on the **Companion** tab.

## My Change Did Not Save

Symptom: you asked the agent to make a change, the editor showed the proposed edit, and you closed the tab — but the change is not live.

Cause: agent-authored changes are **drafts**. They do not persist until you click **Save** in the resource editor. Closing the editor tab does *not* save and does *not* discard — the draft stays in your session.

Fix: reopen the resource. If the draft is still there, review it and click **Save**.

<Note>
  Atomic operations — like binding or unbinding a resource — do not use this draft model. They apply immediately when the agent invokes the tool. The draft pattern is specific to the five authoring resource types described in [Manage Project Resources](/guides/kodexa-agent/managing-project-resources).
</Note>

## The Agent Is Taking A Long Time

Some operations are genuinely slow:

* Reading a large document.
* Calling out to a long-running module.
* Validating a complex activity plan.

Watch the message stream — the agent typically streams progress as tool calls complete. If the stream goes silent for a long stretch and there is no visible activity, switching to a different channel and back can refresh the chat pane. If the agent stays unresponsive, your org admin can check the runtime health.

## Where Do I See What The Agent Did?

The **channel history** is the audit trail. Scroll back through the channel where the action happened. You will see:

* Your prompts.
* The agent's text replies.
* Tool actions the agent took, including UI commands like opening a document.
* Drafts the agent created.
* Confirmations of atomic changes (bindings, status transitions).

This is the canonical record. If you need to confirm what the agent did, this is the place to look — not the resource itself, which only shows the final saved state.

## The Agent Wrote Something I Did Not Ask For

If the agent made a draft you did not want, just discard it from the resource editor. The draft was scoped to your browser session and never persisted.

If the agent made an atomic change you did not want — for example, unbinding a resource — ask it to reverse the change in the same conversation. The agent has the context to know what was undone and can usually reapply the original state.

## I Cannot See The Chat Pane

Symptom: no floating Ask Agent button, no chat sidecar.

Check:

* **Companion configured?** A companion runtime must be set at the org or project level. If neither is configured, the chat pane will not appear.
* **Permissions.** You must have project access. The agent acts as you, so a user with no permission on a project will not see its chat surface.
* **Project Settings → Companion** is where the runtime is set. If you cannot edit that tab, ask a project admin.