Complaint Agent

The Complaint Agent is designed to streamline how customer complaints are handled.

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.

The Complaint Agent is designed to support B2B cases only as its configuration requires Company Contact Information to properly handle the issues.

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 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.

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 and Creating a Value Stream documentation.

You can also use a standard API to call the Agent from external system. For more information, check the AI Service API Reference.

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

For more information about custom entities, see the Custom Entities.

For more information about mixin schemas, see the Mixin Schemas.

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 according to the prompt in the agent definition.

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

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.

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:

Default User Prompt for Complaint Agent

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.

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 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.

If you extend custom entities, update the prompt accordingly to instruct the agent on how to populate the new fields.

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.

  The send-invoice tool is enabled by default. Removing the tool prevents the automatic action.

• 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 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.

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.

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.

For more information on how to create a bot, see the Communication Tools.

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.

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 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.

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.

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.