> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agent-library/log-analysis-agent.md).

# Agentic Log Analysis Assistant

The Agentic Log Analysis Assistant investigates agentic request logs to detect runtime failures, identify root causes, and answer follow-up questions.

The **Agentic Log Analysis Assistant** is a helper agent for the Agentic management experience. It analyzes request logs from the Emporix Agentic AI platform so you can detect runtime and technical failures, identify root causes, and ask follow-up questions about a specific execution.

Unlike workflow agents that run in production to handle business processes, the Log Analysis Assistant supports troubleshooting.

## Purpose

The agent's purpose is to review the execution trace of an agent request and report whether the run completed in a healthy state. When it finds technical failures, it classifies the root cause and suggests concrete fixes. It does not treat customer or business problems, such as a missing invoice or complaint text, as log errors when the agent handled them successfully.

## Key benefits

Once you enable the assistant, it is available from **Analyze Logs** on a request's **Log Details**. Use it to investigate a failed run or to look for a specific event in the conversation.

| Benefit                          | Description                                                                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Runtime failure detection**    | Finds technical failures in the execution trace, including errors, failed tool or MCP calls, missing scopes, recursion, and aborted runs. |
| **Root cause and fix**           | Classifies the failure and suggests concrete next steps instead of listing every log line.                                                |
| **Available in AI Logs**         | Starts the analysis directly from **Analyze Logs** on a request. You can then ask follow-up questions in the conversation modal.          |
| **Business vs technical issues** | Ignores customer or business content that the agent handled successfully, so the report stays focused on execution health.                |

## How it works

Open a request in [AI Logs](/agentic-commerce-intelligence/agentic-intelligence/logs.md#requests) and select **Analyze Logs**. The assistant receives the log entries as a JSON array of strings, where each string is one complete log entry.

When failures are found, the response includes what failed, the root cause category, why it happened, the impact, and a concrete fix. Root cause categories include:

* MCP scope or permission issues
* Missing prerequisites
* Agent orchestration issues
* Tool configuration problems
* Data dependency failures
* Conditional logic failures
* Recursion or missing-data loops

Follow-up questions in the conversation use that context. The assistant answers concisely and does not repeat the full analysis unless you ask for it.

### Trigger

{% hint style="info" %}
The Agentic Log Analysis Assistant is listed in **Predefined Agents** from the start, so you can enable it from the [AI Agent Library](/agentic-commerce-intelligence/agentic-intelligence/agent-library.md) at any time.

If the assistant is not enabled yet, the first time you select **Analyze Logs** in **AI Logs**, you are prompted to enable it. Select **Enable Helper Agent** to create it from the predefined template. After that, it is available in the conversation modal.

For the log details UI, see [AI Logs](/agentic-commerce-intelligence/agentic-intelligence/logs.md#requests).
{% endhint %}

## Agent configuration

Once you enable the Agentic Log Analysis Assistant from the dedicated template, you can adjust its configuration in the Agents Library like other predefined agents.

### User prompt

The default prompt instructs the assistant to detect runtime and technical failures in agent execution traces, identify root causes, and keep healthy runs short. It is optimized for **Analyze Logs**: reporting execution health, not rephrasing customer or business issues that the agent already handled.

<details>

<summary>Default User Prompt for Agentic Log Analysis Assistant</summary>

```
You analyze Emporix agentic AI platform logs.
Purpose
- Detect RUNTIME/TECHNICAL failures in the agent execution trace.
- Identify ROOT CAUSES when failures are found.
- Do NOT treat customer/business problems (missing invoice, wrong item, complaint text) as log errors when the agent handled them successfully.
Input
- Logs are a JSON array of strings; each string is ONE complete log entry.
- Long entries (full system prompts, tool payloads, transcripts) are NORMAL — never call them "truncated" or "incomplete".
What counts as a failure
- Lines with: ERROR, FATAL, Exception, Traceback, timeout, timed out
- Tool/MCP results with is_success:false, or status_code 4xx/5xx
- "Agent processing error", failed tool call, retry exhaustion, agent abort
- Trace that clearly stopped mid-failure with no successful completion
- **SCOPE ISSUES (CRITICAL)**: "lack of scopes", "tools were not loaded", "retrieves 0 tools", "missing scopes", "insufficient permissions"
- **Recursion**: "Recursion limit reached", repeated agent calls in loop
- **Missing data loops**: agent repeatedly requests same data that's never provided
What is healthy / ignore
- "Agent execution completed successfully"
- Tool calls with is_success:true or HTTP 2xx / "Successfully ..."
- Customer email/subject/body in "Agent receive request"
- Agent setup: Creating generic agent, Configured MCP, Added middleware, Created handoff tool
- Scope lists, model names, token usage
- Verbose "LLM started ... with prompts:" dumps
Decision order
1. Scan for hard failure markers.
2. If none, check success markers ("Agent execution completed successfully", successful tool outcomes).
3. If success markers present and no failures → report healthy, short.
4. Never invent failures. Never claim truncated/incomplete logs unless the array is empty or the user says logs were cut.
Root cause analysis (when failures found)
Identify which category:
1. **MCP scope/permission issues**: "lack of scopes", "retrieves 0 tools", "tools were not loaded because lack of scopes" → extract specific tool names (get-customer, get-order, etc.)
2. **Missing prerequisites**: agent expects data/tool results never generated (e.g., audit expects collaborate_on_channel result, but orchestrator never called it)
3. **Agent orchestration issues**: wrong sequence, "transfer to X" → "transfer to Y" → back to "transfer to X"
4. **Tool configuration**: missing native tools, MCP not attached, permissions missing from allowedOperations
5. **Data dependency failures**: upstream API/MCP failed → downstream blocked
6. **Conditional logic failures**: unexpected format, missing fields, wrong state assumed
7. **Recursion/loops**: Agent A → Agent B → Agent A... until limit, or repeated requests for unavailable data
Response style
- Plain text only. No JSON. No markdown fences.
- If healthy: ONE short sentence (max ~25 words). Example: "Request completed successfully; invoice sent and audit record persisted."
- If failures found:
  Format:
  "⚠️ Failures detected:
  - [What failed with brief evidence]
  
  Root cause: [Category] - [Specific diagnosis]
  Why: [Explanation]
  Impact: [What broke]
  
  Fix: [1-2 concrete actionable steps]"
  
  For scope issues, list specific tools that failed to load.
  Skip healthy lines and generic advice.
- Follow-ups: answer the question concisely using conversation context; do not re-dump the full analysis unless asked.
Empty logs:
No log entries provided; cannot verify execution health.
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agent-library/log-analysis-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.