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

# Track and fix problems with Issues

> Collect what went wrong in an AI agent's conversations, from the agent itself, from transcript reviews and by hand, then triage, merge and resolve each problem.

An issue is one problem with how an agent behaves: a wrong answer, a gap in
its knowledge, a tool that failed, a handoff that should not have happened.
When it came from a conversation, the issue keeps that conversation's
transcript beside it. Issues are about your agent's own work. They are not the
support tickets an agent opens for customers, which live in the
[Helpdesk](https://cntillion.com/docs/helpdesk.md).

Open **Issues** in an agent's sidebar to see that agent's issues. Open
**Issues** in the workspace sidebar to see every agent's issues in one list,
with an **Agent** column and an **Agent** filter.

Owners and Members can create, edit, comment on, merge and resolve issues.
Viewers can read them. See [workspace roles](https://cntillion.com/docs/workspaces/members.md).

## Where issues come from

**Raised by** on each issue says how it started.

| Raised by | How it starts |
| - | - |
| Agent | The agent calls the [Flag issue for review](https://cntillion.com/docs/agents/system-tools.md#flag-issue-for-review) tool during a live conversation, [a tool call is refused before anything is sent](#when-a-tool-call-is-refused), for example because a variable the tool reads has no value, or [a call closes after its workflow stalled](#when-a-call-closes-after-its-workflow-stalled). |
| Conversation review | A teammate chooses **Flag issue** on a transcript, either on one reply or on the whole conversation, or on a reply in a [test run](https://cntillion.com/docs/agents/tests.md). |
| Manual | A teammate chooses **New issue**, or asks Mastermind to open one, for a one-off fix or a to-do such as "add the holiday hours to the knowledge base". |
| Analysis | Reserved for issues that analysis of recent conversations opens. Nothing raises these yet. |

## Statuses and priorities

| Status | Meaning |
| - | - |
| Pending | Nobody has reviewed it yet. New issues start here. |
| In progress | Someone is working on it. |
| Resolved | The problem behind it is fixed. |
| Cancelled | Closed without a fix, for example because it was not a real problem. |
| Merged | Folded into another issue with the same cause. Merged issues leave the list and link to the issue they went into. |

Priority is **Urgent**, **High**, **Medium**, **Low** or none.

## Find an issue

The list groups issues by status. **Pending** and **In progress** start open,
**Resolved** and **Cancelled** start folded; select a group's name to open or
fold it.

* **Search issues** matches titles, descriptions, comments and comments on a
  reply. When the match is in a comment, the row shows where.
* **Status** shows one status, or **All**.
* **Filter** narrows by **Raised by** (how it started, or who raised it),
  **Assignee** (including **Unassigned**) and **Priority**. Each filter in use
  becomes a dark chip. Select the chip's value to change it, or **×** to remove
  it.
* **Sort** orders by **Newest** or **Highest priority**.

The address keeps the search, filters and sort, so a link opens the same view.
On a row, select the status or priority icon, or the assignee, to change it
without opening the issue. Hover a row to copy its issue ID.

## Open an issue

Select a row to open the issue beside the list. **↑** and **↓** in its header
step through the list, and **Open fullscreen details** gives the issue its own
page.

* An issue raised by hand shows its **Description**, which you can **Edit**.
* An issue about a conversation shows the **Transcript**. Replies with a
  comment on them are highlighted with what was flagged. **Open full
  conversation** opens it on the Conversations page.
* **Activity** lists comments, comments on a reply (marked with the turn
  number), status and priority changes, merges and Mastermind chats.
* **Details** has the issue ID, when it was created, its status, priority, who
  raised it and who it is assigned to.

Write in the comment box with Markdown, or use its formatting bar, and check
the result in **Preview**. **Comment** adds it to the activity. **Resolve with
comment** adds it and resolves the issue in one step.

## Work through an issue with Mastermind

**Discuss with Mastermind** opens a [Mastermind](https://cntillion.com/docs/agents/mastermind.md) chat that
starts with the issue, and records the chat in the issue's activity. Mastermind
can read the issue and the conversations behind it and suggest a fix. Once a
chat exists, **Continue in Mastermind** returns to it and **New Mastermind
chat** starts another one.

You can also ask Mastermind about issues directly: which issues are open for an
agent, what the most common one was this week, to summarize one and suggest a
fix, to mark one resolved, to open one, or to merge several that share a cause.
Opening, updating and commenting on an issue happen as soon as you ask, in
every [mode](https://cntillion.com/docs/agents/mastermind.md#changes-and-undo) except **Plan first**.
Merging waits for you to approve it in its card.

## Resolve, reopen and merge

* **Resolve** marks the issue resolved. **Reopen** brings a resolved or
  cancelled issue back to **Pending**.
* **Merge into…** folds this issue into another pending or in-progress issue
  of the same agent. Pick the issue to keep: its conversations and the more
  urgent of the two priorities move to it, and it counts both reports. Fix the
  cause once, on the issue you kept.
* Under **Merge proposal**, **Link** connects the
  [merge proposal](https://cntillion.com/docs/agents/releases-and-workflows.md) that fixes the issue.
  Merging that proposal resolves the issue.

## Flag an issue from a conversation

On a transcript in [Conversations](https://cntillion.com/docs/workspaces/conversations.md), hover a reply
and choose **Flag issue** to comment on that reply, or choose **Flag issue**
beside the conversation's summary to comment on the whole conversation.
Describe what went wrong, set a status, priority or assignee if you like, and
choose **Flag issue**. The summary then shows the issue's status and **View
issue**.

## The agent's Flag issue for review tool

Turn on [Flag issue for review](https://cntillion.com/docs/agents/system-tools.md#flag-issue-for-review) in
the agent's **Tools** to let it open issues itself. When it is unsure how to
proceed, for example on an ambiguous request, a policy question or a tool that
failed, it writes a short description of the problem and keeps helping the
customer. The customer is not told. If it flags again in the same
conversation while the issue is open, the new description is added to the same
issue as a comment.

## When a tool call is refused

A tool call is refused before anything reaches the tool when a required
parameter has no value, such as a **Dynamic variable** the conversation never
supplied, or when a value doesn't fit its parameter's type. The call fails as
usual, so a workflow **Tool** step takes its failure path. During a live
conversation the agent's Issues also get an issue, raised by **Agent**, that
names the workflow step (or says the agent called the tool), the tool, the
parameter and the variable it reads, and says that nothing was sent. It never
includes the conversation's values. Another refused call in the same
conversation is added to the open issue as a comment. Preview conversations and
[test](https://cntillion.com/docs/agents/tests.md) runs don't raise these issues, and neither do errors the
tool's own server returns, such as an HTTP error or a timeout.

## When a call closes after its workflow stalled

On a voice call, when the person is still on the line but the conversation
stops moving on a workflow step, the agent checks in with them. If the call
still doesn't move, the agent closes it, and the call is recorded as
**Failed**.

When that step is not one that only closes the call, no step that closes the
call ran, so nothing the workflow records there ran either, such as a tool
that logs the call's outcome, and the agent told the person that a member of
the team would follow up. The agent's Issues then get an issue, raised by
**Agent**, with a title such as
`Call closed after the workflow stalled on "Qualify the lead"`. It names the
step, says how long the call had been on it and that no outcome was recorded,
and suggests checking the step's exits against the call's transcript. It never includes what was said or the
conversation's values. If the conversation already has an open issue the agent
raised, this one is added to it as a comment. A call that stalls on a step
that only closes the call, with nothing left to collect, ends with a plain
goodbye and raises no issue. Preview calls never raise one.

## Use the API

The [developer API](https://cntillion.com/docs/api-reference/developer-api.md) lists, reads, opens,
updates, comments on, merges and deletes issues, so you can triage them from
your own tools. A key deletes only the issues its creator raised, even when an
Owner created the key; it gets `403` for any other issue. Cancel an issue to
close it instead.


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