diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index d6fdbd8e9..6063495ab 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -16,7 +16,20 @@ A standard MCP `Streamable HTTP ` does, and returns the answer in markdown. An investigation can take seconds or minutes, longer than most MCP clients wait for one tool call, so the call is split in two: + +* ``ask_holmes`` waits up to ``wait_seconds`` (default 240, at most 280; pass a shorter wait when your MCP client's tool timeout is shorter) for the answer. When the answer is ready in time, the result has ``status: "completed"``, the ``answer`` and ``steps``, the tool calls behind the answer as ``{tool, description, failed?}`` in order (the first 50; ``steps_truncated: true`` when more ran); otherwise it has ``status: "running"`` and a ``conversation_id``. +* ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. + +While a call waits, the server reports each step of the investigation (the tools Holmes runs, its plan, its intermediate notes) as MCP progress notifications to a client that asked for them: a ``tools/call`` carrying ``_meta.progressToken`` and ``Accept: text/event-stream`` is answered as an event stream of ``notifications/progress`` messages ending in the result. Claude Code and the official MCP SDKs do this on their own and reset their timeouts on each notification; a client that sends no token gets a plain JSON response. + +A client that speaks `MCP Tasks `_ (protocol 2025-11-25, experimental) can run ``ask_holmes`` and ``ask_holmes_followup`` as tasks instead: a ``tools/call`` carrying ``task`` answers at once with a working task whose id is the ``conversation_id``, ``tasks/get`` polls it, ``tasks/result`` waits for the answer (the same result as ``get_holmes_answer``), and ``tasks/cancel`` stops it. A task is reachable by the API key that created it alone, is kept for as long as the conversation, and ``tasks/list`` is not served. + +Questions asked this way run on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so they never delay a person's chat in the Robusta UI, which runs on ``manual``. + +.. list-table:: + :widths: 20 15 65 + :header-rows: 1 + + * - Argument + - Required + - Description + * - ``question`` + - Yes + - The question, with every detail Holmes needs (namespace, workload or pod names, time window, what was observed). + * - ``cluster`` + - When more than one cluster can be asked + - The cluster whose Holmes answers. The error of a call without it names the clusters you can ask. + * - ``wait_seconds`` + - No + - How long the call waits for the answer. Keep it under your MCP client's tool timeout. + +Both tools answer with ``{"conversation_id", "cluster", "status", "answer", "ui_link"}``; ``ui_link`` opens the conversation in the Robusta UI. + +.. code-block:: json + + { + "conversation_id": "78170c9f-2403-43ac-88ed-d6d39efd90ed", + "cluster": "prod-eu", + "ui_link": "https://platform.robusta.dev/my-account/holmes/chat/78170c9f-2403-43ac-88ed-d6d39efd90ed", + "status": "completed", + "answer": "3 of the 12 pods in `checkout` restarted in the last hour ..." + } + +Two more tools work on a conversation ``ask_holmes`` started: + +* ``ask_holmes_followup`` takes a ``conversation_id`` and the next ``question``, and waits like ``ask_holmes``. Holmes answers with the earlier questions, its findings and tool results as context, so use it to dig into an answer or redirect the investigation instead of asking afresh. The conversation must have ended first: one still ``running`` is refused, so wait for its answer with ``get_holmes_answer`` or stop it. +* ``stop_holmes_conversation`` ends an investigation that is still running, when its answer is no longer needed. The result has ``stopped: true`` and ``status: "stopped"``; a conversation that had already ended comes back with ``stopped: false`` and the status it ended in, and a later ``get_holmes_answer`` on a stopped conversation reports the stop instead of an answer. + +Only clusters whose Holmes agent takes conversations from the platform (Holmes 0.24 or later, with the conversation worker enabled) can be asked, and only those the key's owner may chat with. + Rate limits and errors ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configuration/holmesgpt/holmes-chat-api.rst b/docs/configuration/holmesgpt/holmes-chat-api.rst index b085992bd..b582efefa 100644 --- a/docs/configuration/holmesgpt/holmes-chat-api.rst +++ b/docs/configuration/holmesgpt/holmes-chat-api.rst @@ -6,6 +6,8 @@ Holmes Chat API Use this endpoint to send questions to Holmes AI for root cause analysis. You can provide alert context and Holmes will investigate and return a detailed markdown analysis. +On clusters whose Holmes takes questions directly (no Robusta runner), the question runs on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so it never delays a person's chat in the Robusta UI. The pool can be resized per account with the ``conversation_executors`` account setting. + .. _holmes-chat-api: POST https://api.robusta.dev/api/holmes//chat