> 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/complaint-agent.md).

# Complaint Agent

The **Complaint Agent** is a prebuilt solution provided by Emporix as part of the Agents Library. Like other prebuilt agents, it runs in the background and integrates into existing business workflows. It steps in when needed, reducing the need for manual intervention in complaint management.

{% hint style="warning" %}
The Complaint Agent is designed to support B2B cases only as its configuration requires Company Contact Information to properly handle the issues.
{% endhint %}

## Purpose

The Complaint Agent aims to solve common business challenges immediately related to customer complaints. By automating aspects of complaint handling, it helps to reduce manual work and workflows, thereby saving time and contributing to a more efficient and customer-friendly operation.

## Key benefits

Enabling the Complaint Agent offers several benefits.

| Benefit                              | Description                                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Streamlined complaint management** | It is specifically designed to make the process of handling customer complaints more efficient.               |
| **Reduced manual work**              | It helps reduce the manual effort required from your team, freeing them to focus on other areas.              |
| **Increased efficiency**             | The agent contributes to a more efficient operation by handling routine tasks automatically.                  |
| **Enhanced customer experience**     | It helps merchants deliver a more customer-friendly operation.                                                |
| **Immediate solution**               | As a prebuilt agent, it provides a ready-to-use solution to address complaint management challenges promptly. |
| **Scalability**                      | It enables businesses to scale operations without adding complexity to their complaint handling processes.    |

## How it works

The Complaint Agent template creates three collaborating generic agent instances:

| Instance                     | Role                                                                                                                                                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Complaint Categorization** | Analyzes the complaint source and assigns a category.                                                                                                                                                                                                   |
| **Complaint Agent**          | Applies the category rules, runs automatic actions, and, when human collaboration is required, starts collaboration and assigns the [Support Agent](/agentic-commerce-intelligence/agentic-intelligence/agent-library/support-agent.md) to the channel. |
| **Complaint Audit**          | Persists records of each complaint case in the `COMPLAINT_AGENT_CONTEXT` with all the relevant details. If collaboration is started, it also creates the `SUPPORT_AGENT_CONTEXT`.                                                                       |

These instances collaborate with each other as a team. You trigger the complaint flow by API calls, typically as part of a value stream in your own environment.

### Triggers

Trigger the Complaint Agent flow, for example, when:

* an email arrives in the customer support inbox
* a support ticket is created in Jira or Zendesk, or other tool
* a new customer issue is detected by another tool or workflow you integrate with

You have full freedom to integrate the Complaint Agent into your existing processes and tools.

{% hint style="success" %}
The easiest and recommended way of importing agents into your workflows is by using an agent within a value stream step. You need to establish a connection with the specific agent and configure the value stream step to incorporate it. For more information about the value streams, see the [Value Streams](/value-stream-modeller/value-streams/value-stream-introduction.md) and [Creating a Value Stream](/value-stream-modeller/value-stream-designer/creating-value-stream.md) documentation.

You can also use a standard API to call the Agent from external system. For more information, check the [AI Service API Reference](/api-references/api-guides/artificial-intelligence/ai-service.md).
{% endhint %}

### Custom entities

Upon the installation, the Complaint Agent template automatically creates two **custom entity types** with corresponding mixin schemas defined:

* **Complaint Agent Context**
* **Support Agent Context**

<figure><img src="/files/S6OxSvpHTcZrRmNzOZTH" alt="Custom Entities"><figcaption></figcaption></figure>

{% hint style="info" %}
For more information about custom entities, see the [Custom Entities](/ce/management-dashboard/settings/custom-entities.md).

For more information about mixin schemas, see the [Mixin Schemas](/ce/management-dashboard/settings/mixin-schemas.md).
{% endhint %}

Whenever the Complaint Agent flow comes into action, the instances of these entities are created and stored in the system for monitoring purposes.

#### Complaint Agent Context

Each time a Complaint Agent flow is triggered in any of your workflows, for example in a value stream, the **Complaint Audit** records this event in a created instance of the Complaint Agent Context. Thanks to that, you are able to check when and how the agent was invoked, and what was the undertaken activity. The Complaint Agent Context stores the following information about complaints:

* **Action Input** - The source of the incoming complaint, for example, email content.
* **Action Summary** - The action generated by the agent.
* **Automatic Action** - The indicator whether the action was automatically resolved by the agent or required some collaboration from other agents or humans in the loop.
* **Category** - The categorization of the complaint. The agent analyzes the information included in the complaint source and assigns a specific [category](#categories) according to the prompt in the agent definition.

<figure><img src="/files/Dmnk5ZlcHbbCxWH8DXlr" alt="Complaint Agent Context"><figcaption></figcaption></figure>

#### Support Agent Context

If the Complaint Agent flow requires human collaboration, **Complaint Audit** creates a Support Agent Context instance and stores it in the **Custom Instances**. The Support Agent Context keeps the following information:

* Collaboration tool used
* Slack or MS Teams Channel ID created for the complaint case
* Conversation history
* Invited participants

<figure><img src="/files/JELCEIZrGW365gwWQcox" alt="Support Agent Context"><figcaption></figcaption></figure>

#### Contact Info mixin

Additionally, installing the Complaint Agent adds the **Contact Info** mixin to the **Company** entity. This mixin stores information about the contacts within a company.

The Complaint Agent uses the details from the **Contact Info** mixin to invite company contacts as participants to a collaboration channel. Invitation depends on the attached communication tool and its **Allowed operations**.

<figure><img src="/files/aRRrdRYun4o2F4ZIzvgi" alt="Company Contact Info"><figcaption></figcaption></figure>

## Agent configuration

The Complaint Agent offers flexibility in the way how the customer complaints are handled. You can define **automatic** actions that the agent is able to handle by itself. For more complex use cases that require involving human interactions through the communication tool (Slack, MS Teams), you can define **semi-automatic** agent actions.

### User Prompt

The **User Prompt** is editable. The default prompt defines the following behavior for the Complaint Agent:

<details>

<summary>Default User Prompt for Complaint Agent</summary>

```
You are the Complaint orchestrator for Emporix B2B commerce.

## Specialists (hand off in order)

1. **Complaint Categorization** — call FIRST. Wait for CATEGORY line before any action.
2. **Complaint Audit** — call LAST after all actions below. Audit persists all custom-type records.

## Category → action matrix

After Categorization returns `CATEGORY:`:

| Category | Actions |
|----------|---------|
| MISSING_INVOICE | Call `send-invoice` MCP with order id from categorization or complaint. No human collaboration. Hand off to Audit. |
| INCORRECT_INVOICE, DAMAGED_GOODS, WRONG_ITEM | Fetch order + legal entity + customer (sequential rules below). Escalate via native communication tool (see below). Hand off to Audit. |
| OTHER | No MCP fetch required unless ids are known. No human collaboration. Hand off to Audit. |

## MCP fetch rules (escalate categories only)

**One MCP tool call per turn. Never parallel MCP calls.**

1. **Turn 1:** `get-order` with order id from `ORDER_ID:` or complaint text.
2. **Turn 2:** Read `data.legalEntityId` from get-order response. Call `get-legal-entity` with THAT id — never use order id as legal entity id.
3. **Turn 3:** `get-customer` with customer id from order or categorization.
4. Only after all three succeed (or fail with logged reason): proceed to human collaboration.

If get-order fails: still escalate if category requires it; note missing data in handoff to Audit.

## Human collaboration escalation
When category is INCORRECT_INVOICE, DAMAGED_GOODS, or WRONG_ITEM, escalate using **your native collaboration tool** (whichever communication tool is in your tool list).
Do not assume a specific provider — read provider from the collaborate tool result `source`:
- `slack_collaboration` → provider `slack`
- `teams_collaboration` → provider `teams`

**Collaboration parameters:**
- **inbound_agent_id:** ALWAYS `support-agent` (Support Agent). Required on every collaborate/create call so Support owns all subsequent human replies in that channel. Do not leave unset.
- **participants:** account manager emails from `mixins.contactsInfo.accountManagers` on legal entity response. Empty list if none.
- **context_ref:** MUST be stable for the case: `complaint:<orderId>` (e.g. `complaint:EON1002`). Reuse an existing case when this ref already has a channel.
- **channel_name / topic:** MUST be unique per new escalation.
  - Format: `complaint-<orderId>` (lowercase, Slack-safe: letters, digits, hyphens; max 80 chars).
- **message / summary:** descriptive, well formatted case summary including category and order id
- **extra context:** include `category`, `orderId`, `customerId`, `legalEntityId` when known

Example (Slack):
collaborate_on_channel(
  message="<one-line summary>",
  channel_name="complaint-<orderId>",
  participants=[...],
  context_ref="complaint:<orderId>",
  inbound_agent_id="support-agent"
)

**After collaborate succeeds**, capture from tool result for Audit handoff:
- **provider** (from `source` as above)
- **conversation_id:** first non-empty of `data.channel_id`, `data.conversation_id`, `data.chat_id`
- **conversation_name:** `data.channel_name` or `data.chat_topic` if present
- **inbound_agent_id** used (`support-agent`)
- **context_ref**, participants invited

## Before finishing

- Hand off to Complaint Audit — persistence happens there.
- Do not claim custom type instances were created yourself.
- Wait until Audit confirms persistence (see below).

## Audit handoff

Hand off to Complaint Audit with a short checklist:

- CATEGORY and verbatim customer complaint text
- Order / legal entity / customer fetch results (or errors)
- Human collaboration (if any): **provider**, **conversation_id**, conversation_name, participants, context_ref, collaborate tool result
- For MISSING_INVOICE: send-invoice result

## Finish only when Audit confirms

Audit must report instance ids from **its own** tool calls:

- Escalated cases: SUPPORT instance id + COMPLAINT instance id (two different ids)
- Non-escalated: COMPLAINT instance id only

If Audit returns ids without evidence of separate upsert tool calls (escalated path), hand off to Audit again with: "Call upsert-custom-type-instance for each required type. Do not reuse ids from this thread."

Then give the customer a brief confirmation of what was done.

## Response
CRITICAL: Your final response to the user MUST be plain text only.
Do NOT return JSON schemas or categorization objects.
Only return your human-readable summary message.
After Audit confirms, respond with:
- What the problem was
- What actions were taken
- What the outcome is
- Any next steps for the customer
Never include raw JSON, schemas, or structured data in your final response.
```

</details>

When creating an agent from the **Complaint Agent** template, configure the agent by adjusting the rules for the agent's behavior in the **User Prompt** field.

Using the prompt `<rules>`, define the expected [categories](#categories) of the complaints that might occur and specify the corresponding agent's actions for each category. For instance, you can add new complaint categories, disable automatic actions (such as invoice resending), or even extend the custom entities with new fields.

{% hint style="warning" %}
If you extend custom entities, update the prompt accordingly to instruct the agent on how to populate the new fields.
{% endhint %}

#### Categories

The categories define the agent's responses to certain triggers. The category recognition is first handled by Complaint Categorization subagent in the complaint source. Based on the result, the agent undertakes a specific action as defined for a particular category.

The predefined categories:

* Missing Invoice – The agent automatically resends the invoice using the `send-invoice` tool. The invoice is sent to the email address associated with the order, not to the sender’s email. Then, the complaint if handed over to the Complaint Audit subagent to record the complaint case.

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>The <code>send-invoice</code> tool is enabled by default. Removing the tool prevents the automatic action.</p></div>
* Incorrect Invoice / Delivery Too Late / Product Damaged – These categories follow the same escalation flow:
  1. Retrieve order, legal entity, and customer details.
  2. Start collaboration: create a channel, invite participants from company **Contact Info**, and post a case message.
  3. If collaboration is in place, assign the [Support Agent](/agentic-commerce-intelligence/agentic-intelligence/agent-library/support-agent.md) to the channel.
  4. Hand off to Complaint Audit to persist the Complaint Agent Context and, because collaboration started, the Support Agent Context.
  5. Participants communicate with the Support Agent in the created channel.
* Other Complaints – The agent takes **no action**. This prevents unnecessary collaboration or automation for unrelated emails. The complaint goes to the Complaint Audit to record the complaint case.

Use the predefined categories as a starting point to configure your Complaint Agent to your needs.

{% hint style="success" %}
For automation of fetching and updating the actual data from/to an external system (ERP, CRM etc), register a custom MCP Server with relevant AI tools and enable them directly for the Agent. This approach allows you to let the Agent take care of more tasks for you.
{% endhint %}

### Scopes

Select the scopes required to trigger the agent. If you want the agent to be triggered by your existing ticketing system, use the **Integration** scope.

### AI Tools

The Complaint Agent flow requires the connection to the **Slack AI Tool** or **MS Teams AI Tool** when human collaboration is needed. First, create the communication tool bot in the **Agentic AI** -> **AI Tools**.

{% hint style="info" %}
For more information on how to create a bot, see the [Communication Tools](/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/comm-tools.md).
{% endhint %}

Once the communication tool is ready, establish the connection with the bot by selecting the right AI communication tool in the **Native Tools**. Channel creation depends on the tool's **Allowed operations**.

<figure><img src="/files/1KVhRgiDmO7Ej59sBAoW" alt="Adding native communication tool and scoping capabilities"><figcaption></figcaption></figure>

This way, the Complaint Agent can hand off to the Support Agent, which acts directly within the Slack workspace or MS Teams team.

The capabilities of the Complaint Agent require MCP server tools. Upon creation, the agent is equipped with the tools for **Customer** and **Order** entities management.

Default toolset for Complaint Agent:

| Tool                   | Capabilities                                |
| ---------------------- | ------------------------------------------- |
| **Customer MCP Tools** |                                             |
| `get-customer`         | Retrieves customer details.                 |
| `get-legal-entity`     | Fetches details of a specific legal entity. |
| **Order MCP Tools**    |                                             |
| `get-order`            | Retrieves a specific order.                 |
| `get-orders`           | Lists all orders.                           |
| `send-invoice`         | Resends an invoice.                         |

Default toolset for Complaint Categorization:

| Tool                   | Capabilities                                                    |
| ---------------------- | --------------------------------------------------------------- |
| **Frontend MCP Tools** |                                                                 |
| `get-customer-orders`  | Retrieves customer orders made on the storefront by a customer. |
| `get-returns`          | Fetches returns.                                                |
| **Order MCP Tools**    |                                                                 |
| `get-customer-orders`  | Retrieves orders assigned to a customer.                        |
| `get-order`            | Retrieves a specific order.                                     |
| `get-orders`           | Lists all orders.                                               |
| `get-return`           | Retrieves details of a return.                                  |
| `get-returns`          | Fetches returns.                                                |

Default toolset for Complaint Audit:

| Tool                          | Capabilities                                                      |
| ----------------------------- | ----------------------------------------------------------------- |
| **Extensibility MCP**         |                                                                   |
| `upsert-custom-type-instance` | Required for handling custom entities and collaboration contexts. |

Extend or limit the tools according to your needs in the **Tools** tab. Add or remove the tools from the list.

### Collaboration

The Complaint Agent template instances (**Complaint Audit**, **Complaint Categorization**, and **Complaint Agent**) are predefined to collaborate with each other. When human involvement is required, the Complaint Agent fetches the required data, starts collaboration (creates the channel, invites participants, and posts a message), and assigns the [Support Agent](/agentic-commerce-intelligence/agentic-intelligence/agent-library/support-agent.md) to the channel. Complaint Audit then persists the Complaint Agent Context and, if collaboration was started, the Support Agent Context. Participants use the channel to communicate with the Support Agent. You can attach additional agents when configuring your Complaint Agent instances to extend the team for different cases.

{% hint style="danger" %}
**Agent Dependencies**

For its correct operation, the Complaint Agent requires the following:

* the **AI tools** from the Extensibility MCP server
* the **custom entities** automatically created during the agent installation
* the **Support Agent** when collaboration categories are enabled, with a matching Slack or MS Teams tool and non-empty **Allowed operations**

Be careful NOT TO remove them accidentally.
{% endhint %}

{% hint style="info" %}
All Agents operations are tracked in the **AI Logs** view. You can check the details of the requests, jobs, and sessions for monitoring and evaluation purposes. For more information, see the [AI Logs](/agentic-commerce-intelligence/agentic-intelligence/logs.md).
{% endhint %}


---

# 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/complaint-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.