Diagnose conversations

Pick chats the agent already had, launch a diagnosis with checks, and read its failures and fixes.

Endpoints

All paths start with /api/v1/diagnostics and need X-Space-Slug.

Method	URL	Does	Auth
`GET`	`/agents/{agent_id}/chats/`	The agent's chats the key's owner can open	Key or bearer
`POST`	`/agents/{agent_id}/runs/`	Launch a diagnosis; `201`; billed	Key or bearer
`GET`	`/agents/{agent_id}/runs/`	The agent's diagnoses	Key or bearer
`GET`	`/agents/{agent_id}/runs/{run_id}/`	Status and conclusions	Key or bearer
`POST`	`/agents/{agent_id}/runs/{run_id}/cancel/`	Stop it; `202`	Key or bearer
`DELETE`	`/agents/{agent_id}/runs/{run_id}/`	Delete it; `204`	Key or bearer
`GET`	`/runs/`	Every diagnosis in the workspace, newest first; `?kit_id=` narrows to one environment	Key or bearer
`POST`	`/compare/`	Compare 2–20 diagnoses of the same agent and environment: `{"run_ids"}`; `422` for runs without an environment	Key or bearer

Request fields

Field	Rule
`trace_ids`	Required, at least one: IDs of the caller's own chats with this agent in this workspace, from `GET /agents/{agent_id}/chats/`
`kit_id`	Use the checks of an environment of this agent; replaces `eval_assertions`
`eval_assertions`	Checks of your own, shaped as in Build an environment
`diagnostic_effort`	`low`, `medium` (default) or `high`

Diagnose an agent

List the agent's chats and pick the ones to read; a chat started through run-stream is the one whose thread_id is the threadId you sent:

curl "$CENTRAL_HUB_URL/api/v1/diagnostics/agents/42/chats/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

Launch the diagnosis:

curl -X POST "$CENTRAL_HUB_URL/api/v1/diagnostics/agents/42/runs/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -H "Content-Type: application/json" \
  -d '{"trace_ids": [678, 679], "kit_id": 7, "diagnostic_effort": "low"}'

Poll GET /agents/42/runs/{id}/ until status is completed, failed or cancelled; on the way it passes through pending, loading, scoring, analyzing and optimizing, and cancelling after a cancel.
Read the conclusions in the same response; see Result fields. Read a diagnosed chat with GET /agents/42/chats/{chat_id}/, using an ID from trace_ids.

Result fields

Field	Holds
`score`, `diagnosis_summary`	The result in one number and one paragraph
`per_assertion_results[]`	`{id, label, passed, total}`: how each check did across the diagnosed chats
`failure_categories[]`	`{category, severity, fix_level, description, count, examples}`: patterns the analysis found, including inefficient successes, in how many chats, with examples
`recommendations[]`	`{priority, title, fix_level, description, suggested}`: the fix to make

Troubleshooting

Response	Cause	Fix
`404` `Trace(s) not found: […]`	A `trace_ids` entry is not the caller's own chat with this agent in this workspace; chats shared with the caller do not count	Use chats the caller started
`404` `Diagnostic kit not found`	`kit_id` is wrong or not visible	Check it with `GET /kits/`
`422` `This environment belongs to another agent.`	`kit_id` names another agent's environment	Use an environment of this agent, or of the agent it was promoted from
`422` `Unsupported assertion type(s): …`	A check in `eval_assertions` has an unknown `type`	Use a type from `GET /check-catalog/`