Olly Observability Agent Skill

Use this skill to interact with Coralogix's Observability Agent (Olly) via MCP tools. Olly can analyze your observability data, answer questions about alerts, metrics, logs, and generate artifacts like charts and reports.

When calling Olly via MCP, agent_to_agent_mode defaults to true. Olly acts as a sub-agent to you (the parent agent): it runs shorter, asks clarifying questions instead of guessing when context is missing, relies on your broader context, and skips charts/tables (returns previews, citations, and text instead). Pass false if you don't have context to share (like quick access to source files) or if the created chat is only for human usage.

MCP Tools

Tool	Purpose	Key parameters
olly_ask	Send a message to the Observability Agent	message, chat_id, model, should_block, agent_to_agent_mode
olly_get_interaction	Poll an interaction started in background	chat_id, interaction_id
olly_list_chats	List user's chat sessions	-
olly_get_chat	Get a chat with full history	chat_id
olly_list_artifacts	List all generated artifacts	chat_id (optional)
olly_get_artifact	Get artifact content by ID	artifact_id

Chat Commands

Ask Olly (default: async)

olly_ask defaults to should_block=False: it returns immediately with status=in_progress instead of waiting. Use this for investigations and any non-trivial request, and poll with olly_get_interaction until terminal:

result = olly_ask(message="Why is the checkout service showing high latency?")
chat_id, interaction_id = result["chat_id"], result["interaction_id"]

status = result["status"]
while status == "in_progress":
    time.sleep(30)  # pace polling; investigations can take a while
    result = olly_get_interaction(chat_id=chat_id, interaction_id=interaction_id)
    status = result["status"]

response = result["response"]

chat_id starts a new chat; pass an existing one to continue the conversation with context (e.g. olly_ask(message="What changed in the last hour?", chat_id=chat_id)).

For a short question you expect Olly to answer almost immediately, pass should_block=True instead to skip polling:

olly_ask(message="What alerts fired today?", should_block=True)["response"]

List previous chats

olly_list_chats()

Returns all chat sessions for the current user. Use to find a previous conversation to continue.

Get chat history

olly_get_chat(chat_id="<chat-id>")

Returns the full conversation history including all messages and responses.

Model selection

The model parameter is optional. If omitted, the Olly API uses its default.

To see currently supported models, ask Olly directly, for example:

olly_ask(message="What models do you support?")

You can pass model on any olly_ask call when the user specifies one:

olly_ask(message="Explain this error", model="<model-id>")

Response format

olly_ask / olly_get_interaction response

{
  "chat_id": "chat-uuid-123",
  "interaction_id": "interaction-uuid-456",
  "status": "completed",
  "response": "Here are the results..."
}

Field	Description
chat_id	Unique chat session ID — save this for follow-up questions
interaction_id	This turn's interaction ID — save this to poll with olly_get_interaction
status	Interaction status (see table below)
response	Olly's text answer, or a user-facing fallback if no assistant text. Absent when async and still in_progress — a note field is present instead, telling you to poll

Status values

Status	Meaning	Action
completed	Success, response available	Use the response
in_progress	Still processing (expected right after an async olly_ask call)	Poll with olly_get_interaction until status is terminal
error	Failed	Check error message, retry with different query
stopped	Cancelled/interrupted	Retry if needed

olly_list_artifacts response

[
  {
    "id": "artifact-123",
    "type": "coralogix_logs",
    "chat_id": "chat-456",
    "interaction_id": "interaction-789",
    "created_at": "2024-01-15T10:30:00Z",
    "chat_title": "Latency investigation"
  }
]

olly_get_artifact response

{
  "id": "artifact-123",
  "type": "coralogix_logs",
  "download_url": "https://storage.../presigned-url",
  "params": {
    "query": "source logs | filter ...",
    "description": "Error logs from checkout service"
  }
}

The download_url returns a link to the artifact in gzip-compressed JSON format.

Artifacts

Olly can generate artifacts like query results, previews, and citations. Artifact IDs may appear in the response.

List all artifacts

olly_list_artifacts()
# Or filter by chat:
olly_list_artifacts(chat_id="<chat-id>")

Get artifact content

olly_get_artifact(artifact_id="<artifact-id>")

Returns:

• download_url — pre-signed link to the artifact in gzip-compressed JSON format
• type — artifact type (coralogix_logs, coralogix_spans, coralogix_metrics, etc.)
• params — query details (e.g., DataPrime query used)

Artifact types

Type	Description
coralogix_logs	DataPrime log query results
coralogix_spans	DataPrime span/trace query results
coralogix_metrics	PromQL metrics query results
alert_watch_data	Alert trigger data with associated query results
kubernetes_query_results	Kubernetes resource query results

Workflow Examples

Investigate an issue

# Start investigation and poll until terminal (see polling pattern above)
result = olly_ask(message="Why is the checkout service showing high latency? Check logs with `checkout:` strings and aws related metrics")
chat_id = result["chat_id"]
# ... poll olly_get_interaction until status != "in_progress" ...

# Follow up with context, then poll that interaction to terminal too
result = olly_ask(message="What changed in the last hour?", chat_id=chat_id)
# ... poll olly_get_interaction until status != "in_progress" ...

# Get any generated artifacts (safe now that both interactions are terminal)
for artifact in olly_list_artifacts(chat_id=chat_id):
    olly_get_artifact(artifact_id=artifact["id"])

Get generated data

# List recent artifacts
artifacts = olly_list_artifacts()

# Get the content of an artifact
artifact = olly_get_artifact(artifact_id="<id>")
# Use artifact["download_url"] to fetch the actual data

When to use Olly vs direct tools

Use olly_ask when:

• User needs multi-step investigation across logs, metrics, alerts
• User doesn't know the exact DataPrime or PromQL syntax
• User wants AI-guided analysis with explanations

Use direct tools when:

• User provides a specific DataPrime query → use query_dataprime
• User asks about alerts or incidents → use olly_ask
• User asks about specific metrics with PromQL → use query_promql_instant or query_promql_range
• User needs raw log/span data with precise filters → use query_dataprime

To summarize: if the user is asking for simple data retrieval or straightforward information, use the other available tools instead of Olly.

Use Olly when the request requires investigation, analysis, or understanding what happened (for example, troubleshooting an issue, identifying root causes, or analyzing system behavior), or when the user explicitly asks to use Olly.

Common pitfalls

• Forgetting chat_id — Always save the chat_id from the first response. Without it, follow-up questions lose context and start a new conversation.
• Costly feature not enabled — Olly tools are hidden unless the x-allow-costly-use: true header is set. If tools are missing, check this header.
• 403 errors — Surface the API detail from the error to the user. You cannot verify API key scopes, quota, subscription status, or log/trace permissions from here.
• Using Olly for specific queries — Olly is for observability investigation, not for simple questions that can be answered with other tools (for example, when the user already provided exact DataPrime or PromQL). Use query_dataprime, query_promql_instant, or query_promql_range directly in those cases.
• Empty assistant text — If Olly returns no assistant text, response includes a short fallback (for example, error with retry guidance, stopped, or no response received).
• Missing artifact data — The artifact download_url returns a link to a gzip-compressed JSON file. Decompress it before parsing.

Key principles

• Async by default — olly_ask defaults to should_block=False; poll with olly_get_interaction until the status is terminal. Only pass should_block=True for short questions you expect Olly to answer almost immediately — never for multi-step investigations.
• Chat IDs enable context — save the chat_id from responses to continue conversations
• Artifact IDs are in responses — look for artifact references when Olly generates data
• Optional model parameter — ask Olly which models are supported when the user needs a specific model
• Check source code before asking — Give Olly concrete context from the source code if available, such as which metric to start investigating from, before calling it.
• Limit investigation scope - Guide Olly to the correct limited scope. For example limit to just logs or to specific time ranges.

Related skills

• DataPrime queries — skill://coralogix-dataprime/SKILL.md
• Log querying — skill://coralogix-logs/SKILL.md
• Trace querying — skill://coralogix-spans/SKILL.md
• Metrics querying — skill://coralogix-metrics-query/SKILL.md
• RUM (Real User Monitoring) — skill://coralogix-rum/SKILL.md