# Operate AI agents

This page is written for platform engineers and business operators who run [AI agents](https://docs.diagrid.io/concepts/ai-agents) on Catalyst. It covers how to find a running agent, what each piece of the agent execution view shows, and which operations are best done from the console versus the CLI. For authoring agents, see [Develop AI agents](https://docs.diagrid.io/develop/agents).

## Find a running agent

The **Agents** page lists every agent registered in the current project. Each agent is associated with an [ID](https://docs.diagrid.io/concepts/identities) — the identity Catalyst assigns to the workload hosting the agent. Each row shows:

- **Name** — the agent identifier. Agents provisioned by Catalyst are marked as **Managed agent**.
- **Role** — the agent's declared role (for example `researcher`, `planner`).
- **Type** — the framework and agent type, formatted as `Framework (AgentType)`. Supported frameworks include Dapr Agents, CrewAI, LangGraph, Strands, Microsoft Agent Framework, Google ADK, OpenAI Agents, Pydantic AI, and Deep Agents — see [Develop AI agents](https://docs.diagrid.io/develop/agents) for the full list.
- **App** — the workload hosting the agent. Click through to see the app's components, policies, and metrics.
- **Registered** — when the agent was first registered with the project.

Filter by app, agent name, or type to narrow the list during an incident — for example, all `LangGraph` agents on `app-billing`.

![Agents list in the Catalyst console showing name, role, type, app, and registered timestamp columns](https://docs.diagrid.io/img/catalyst/agent-list-light.png)

## Agent execution view

Click an agent to open the detail view. The header shows the agent name, its **App**, and badges identifying the agent type (for example `DurableAgent`) and whether it is **Managed agent** by Catalyst. Two actions are available from the header:

- **Trigger agent** — invoke the agent ad-hoc with a payload, useful for reproducing a reported failure.
- **Call model only** — send a request directly to the model without going through the agent's tool loop, useful for confirming the LLM is responsive when an agent is stuck.

Below the header, the view is split into **Agent configuration** and **Agent executions**.

### Agent configuration

The configuration panel shows what the agent was registered with — useful for confirming an incident matches a recent deploy:

- **Role**, **Registered**, and **Updated** timestamps.
- **Goal** — the agent's stated objective.
- **System instructions** — the system prompt the agent runs with (collapsible).
- **Available tools** — every tool the agent can call. An `auto` badge means the framework selects tools dynamically. Use this list to confirm a missing or unexpected tool is the cause of a failure before inspecting executions.
- **Model configuration** — the model client (for example `DaprChatClient`), the resource it points at, and **Max iterations**. The **View API logs** button jumps to [API Logs](https://docs.diagrid.io/operate/project-operations/observability/api-logs) filtered to this agent's LLM calls.
- **PubSub execution channel** — the pub/sub component and input topic used to drive the agent. For multi-agent setups, this is where broadcast and per-agent topics surface.

If the agent was registered with persistent memory, a memory section also appears showing the short-term and long-term components backing the agent's conversation history.

![Agent detail view in the Catalyst console showing agent configuration, available tools, model configuration, and pub/sub execution channel](https://docs.diagrid.io/img/catalyst/agent-details-light.png)

### Agent executions

Each agent execution is a durable workflow — a run whose state is checkpointed so it survives process crashes and restarts. The executions list captures:

- **Execution** — the task description from the input (truncated) or the workflow ID.
- **Status** — `running`, `completed`, `failed`, `canceled`, `terminated`, `suspended`, `pending`, or `stalled`.
- **Started** and **Duration**.
- **Execution ID** — click through to the per-execution detail.

### Reading a single execution

Opening an execution shows:

- **Input** and **Output** — JSON-formatted side-by-side. Catalyst auto-extracts the `task` and `content` fields when present, and falls back to the raw payload otherwise. This is the first thing to check when an agent returns the wrong answer.

- **Conversation history** — for agents configured with memory, the conversation turns persist to the configured memory store (Redis, Postgres, etc.) and replay into each LLM call. They appear in the execution detail as the inputs passed to each model call.

  ![Agent execution detail showing the Input and Output panels side-by-side for a selected execution](https://docs.diagrid.io/img/catalyst/conversation-history-light.png)

- **Step-by-step history** — every execution links to the underlying durable workflow, where the full step graph shows each LLM call, tool invocation, and child workflow with their inputs, outputs, and timestamps. This is where you confirm which tool a failing agent looped on, or which model call produced a malformed plan. See [Operate workflows](https://docs.diagrid.io/operate/project-operations/workflows) for the full execution graph reference.

- **Error resolution** — for failed or stalled executions, **rerun**, **resume**, **terminate**, or **purge** using the same controls used for any durable workflow.

Combine the agent view with [API Logs](https://docs.diagrid.io/operate/project-operations/observability/api-logs) to see the underlying LLM calls — including model, token counts, and latency — that each execution triggered. To put a ceiling on what an agent can spend, give it a [token budget](https://docs.diagrid.io/operate/project-operations/token-budgets).

## CLI commands

The [`diagrid agent`](https://docs.diagrid.io/references/catalyst/cli-reference/agent) command surfaces agents registered in a project:

```bash
# List every agent in the project
diagrid agent registry list --project my-project

# Get a single agent's configuration
diagrid agent registry get my-agent --project my-project

# Disambiguate when two agents share a name across App IDs
diagrid agent registry get my-agent --id my-app --project my-project

# Machine-readable output for scripting
diagrid agent registry list --project my-project --output json
```

Because agent executions run as durable workflows, the [`diagrid workflow`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow) command is what you use to act on a specific run. `workflow list` is project-wide by default, and narrows with `--id`, `--status`, `--name`, and the `--start-after` / `--end-before` time bounds:

```bash
# List workflow executions across the project (max 250)
diagrid workflow list --project my-project --limit 250 --output json

# Narrow to the failed runs of one agent's App ID
diagrid workflow list --id my-agent-app --status failed

# Inspect a single execution — workflow ID is positional
diagrid workflow get <workflow-id> --id my-agent-app

# Pause and resume an in-flight execution
diagrid workflow pause --id my-agent-app --instance-id <id>
diagrid workflow resume --id my-agent-app --instance-id <id>

# Terminate a stuck execution
diagrid workflow terminate --id my-agent-app --instance-id <id>

# Rerun from a specific event with a new workflow ID
diagrid workflow rerun \
  --id my-agent-app \
  --instance-id <id> \
  --event-id <event-id> \
  --new-workflow-id <new-id>
```

### CLI or console?

| Task | Best surface | Why |
|------|--------------|-----|
| Browse agents and confirm registration | Console | Filtered list with framework, role, and app at a glance. |
| Read an execution's step-level history | Console | The execution graph is visual; the CLI returns JSON only. |
| Cross-reference an execution with LLM token usage | Console | Click through from the agent's Model configuration to [API Logs](https://docs.diagrid.io/operate/project-operations/observability/api-logs). |
| Recover a single failed execution after a fix | Console | One-click rerun; the CLI `rerun` requires `--event-id` and `--new-workflow-id` per call. |
| Wire agent inspection into runbooks or CI | CLI | Structured `--output json` and exit codes are scriptable; filter client-side with `jq`. |
| Pull an agent's configuration into a ticket | CLI | `diagrid agent registry get … -o yaml` copies cleanly. |

## During an incident

A typical triage path for "an agent is misbehaving":

1. Open **Agents**, filter to the affected app, and confirm the agent's framework, role, and **Available tools** match the expected deploy.
2. Open **Agent executions**, filter to `failed` or `stalled`, and click into the most recent one.
3. Compare **Input** and **Output**; if the agent looped, follow through to the underlying workflow to find the repeated tool activity.
4. Cross-reference with [API Logs](https://docs.diagrid.io/operate/project-operations/observability/api-logs) for the failing LLM call (model, status, latency, token count).
5. If the agent's access to a downstream service or MCP server looks wrong, confirm the app's [policies](https://docs.diagrid.io/concepts/policies) still permit the call — denied calls show up in API Logs as failed requests.
6. Once the root cause is fixed, **rerun** the affected executions. Use the console for ad-hoc reruns — the CLI `workflow rerun` needs the event ID to rerun from and a new workflow ID, so it's better suited to scripted recovery than one-offs.

For common runtime issues — stalled executions, tool loops, memory not persisting — see [Troubleshooting / FAQ](https://docs.diagrid.io/references/troubleshooting).

## Next steps

- [Operate workflows](https://docs.diagrid.io/operate/project-operations/workflows) — Inspect the step-by-step execution graph that backs every agent run.
- [API Logs](https://docs.diagrid.io/operate/project-operations/observability/api-logs) — Drill into LLM and Dapr API calls — model, status, token counts, latency.
- [Develop AI agents](https://docs.diagrid.io/develop/agents) — Build durable agents in your framework of choice.
- [Troubleshooting & FAQ](https://docs.diagrid.io/references/troubleshooting) — Fixes for common agent runtime issues and console errors.