# Translation Agent

The **Translation Agent** template is designed to enhance your productivity as you can build an agent that translates the provided data on the fly.

## Purpose

The agent automates the translation process of data in Emporix system. The predefined Translation Agent serves as a basic template for you to create agents covering different languages and different kinds of data. For example, you can build an agent to cover translations of localized products or categories data, or localized custom mixins fields, and much more. Basing on this template, create separate agents for translations to different data languages you use in your tenant and incorporate the agents in your workflows to make the processes more efficient.

## Key benefits

Enabling the Translation Agent facilitates your workflows.

| Benefit                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Process automation** | The Translation Agent reduces manual work and speeds up internal preparation processes, such as for example product onboarding.                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Generic usage**      | The Translation Agent template is designed in such a way so that you can adjust its usage to your needs. The agent can be triggered by API, which brings a variety of possibilities to invoke it when needed. You can incorporate the agent into existing workflows or value stream steps. Depending on your requirements, you can adjust the Agent to provide translations that are to be reviewed and approved by merchants, or allow even more automation so that the Agent updates the entities with its translation output. |

## How it works

In its default setup, the Translation Agent translates the provided input fields into the target language and returns output JSON file that includes the localized versions of the requested fields in a target language. The JSON file can serve as an input for next steps in your workflows to further process the data, approve it or update entities in the system.

### Trigger

The Agent can be triggered by API calls. Call the agent by its ID and pass the data to translate in the request. To see an example of calling the Translation Agent by API, refer to the [AI Service Tutorials](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/artificial-intelligence/ai-service/ai-tutorial). The API approach allows you to conveniently call the Agent from other parts of the system, for example in a step of a value stream.

{% hint style="success" %}
The recommended way of including the Translation Agent in your internal workflows is through the value streams. The Agent can complete a step in the process, preparing content for the subsequent steps. Find out more in the [Value Streams](https://app.gitbook.com/s/8dAaH7DfB59pzZwLxmur/value-streams/working-with-value-streams) documentation.
{% endhint %}

## Agent Configuration

When you create the Translation Agent from the template, you can configure its actions to adjust the agent as you like. You can create separate agents for different languages you use in your setup, or separate agents to cover translations of different scopes of data. For example, you can have one agent for translating product data, such as names or descriptions, another for translating categories data, and another for translating custom entities data. Configuration allows for flexibility of agents usage and capabilities.

{% hint style="success" %}
The default template provides the basic functionality but allows for intuitive extension of its capabilities. The configuration of individual Translation Agents depends on how you want to use them, in which workflows and what access you want to grant.
{% endhint %}

### User prompt

The default prompt for the Translation Agent is a simple command that can be adjusted by the users to translate the given content to different languages, for exmaple:

```
Translate the following fields into German:
- name
- description
```

### Template prompt

The template prompt shows what stands behind the simple user prompt, and what can be used, for example, in [Value Streams](https://app.gitbook.com/s/rSc4haeKWrTrOPHzdrMO/value-stream-library/pl-introduction) templates.

```
You are a simple translation agent.

<objective>
Extract the fields "name" and "description" from provided JSON data, translate them into the requested target language, and return them in a fixed input/output translation structure.
</objective>

<input_format>
The input to the agent consists of:
- {{user_prompt}} — a natural-language request containing the target language (e.g., "please translate to German", "translate this into Spanish").
- data — a JSON object containing the fields to translate.
</input_format>

<steps>
<step>Determine the target language code ("toLanguage") by analyzing {{user_prompt}}. If no language is found, return {"error": "No target language found in user_prompt"}.</step>

<step>Parse the "data" object. If invalid, return {"error": "Input data is not valid JSON"}.</step>

<step>Resolve the object in data that contains the fields:
  - name
  - description

These fields must be localization maps:
{
  "en": "...",
  "pl": "...",
  ...
}
If a field is missing or has an invalid structure, treat its value as null.
</step>

<step>Extract the source text for translation:
  - Prefer "en"
  - Otherwise use any available language
Record the language used as "fromLanguage". If no valid text exists, set the respective value to null and fromLanguage to null.</step>

<step>Translate the extracted values into the target language ("toLanguage"). If the input value is null, output should also be null.</step>

<step>Return ONLY the following structure:

{
  "translation": {
    "input": {
      "name": "<original or null>",
      "description": "<original or null>"
    },
    "output": {
      "name": "<translated or null>",
      "description": "<translated or null>"
    }
  },
  "fromLanguage": "<source or null>",
  "toLanguage": "<target>"
}
</step>
</steps>

<rules>
<rule>No explanations. No markdown. Return ONLY the JSON output.</rule>
<rule>Output must contain plain strings (no localization maps).</rule>
<rule>If anything is invalid, return the appropriate {"error": "..."} JSON.</rule>
</rules>
```

With this prompt, the agent looks for `name` and `description` fields in the JSON object passed in the API request. The Agent provides `de` translations of the fields and returns back the JSON response that additionally includes the German translations. The original content is preserved.

For example, the Agent response can look as follows:

```json
{
  "response": {
    "fromLanguage": "en",
    "toLanguage": "de",
    "translation": {
      "input": {
        "description": "Awaken your senses with our hand-selected Gourmet Coffee, crafted for true coffee lovers who crave depth, aroma, and sophistication in every sip. Sourced from the world’s finest high-altitude farms, each bean is carefully harvested at peak ripeness, then small-batch roasted to unlock its natural sweetness and complex flavor notes.",
        "name": "Delight Coffee"
      },
      "output": {
        "description": "Wecken Sie Ihre Sinne mit unserem handverlesenen Gourmetkaffee, kreiert für wahre Kaffeeliebhaber, die Tiefe, Aroma und Raffinesse in jedem Schluck suchen. Aus den besten Hochlandfarmen der Welt bezogen, wird jede Bohne sorgfältig zum Höhepunkt ihrer Reife geerntet und dann in kleinen Chargen geröstet, um ihre natürliche Süße und komplexen Geschmacksnoten freizusetzen.",
        "name": "Delight Kaffee"
      }
    }
  }
}
```

By modifying the **Prompt**, adjust the agent to translate different fields, into different languages, or with a different style or parameters. Use this Prompt as a starting point to configure your agent to cover specific use cases.

### MCP Servers

The Translation Agent can get more power in completing tasks on its own if you give it access to the MCP Servers. This way, for example, the Agent you create can get ability to modify the objects directly after translations are done.

For example, in the **MCP Servers**, attach the Emporix Product MCP and add `partial-update-product` tool. Once you adjust the Prompt accordingly, the Translation Agent can directly update the product object in question and add the German translations for `name` and `description` fields. Similarly, you can attach your custom MCP Servers and grant more capabilities for your agent.

<figure><img src="https://1530167654-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GgoeZEZYjZrpjOU6w52%2Fuploads%2Fgit-blob-27b803ef04d7b5253cdb8d6a586aed49bfe1b670%2Fagentic_translation_agent.png?alt=media" alt="Translation Agent" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
To see the example of how to trigger the Translation Agent, refer to the [AI Service Tutorials](https://developer.emporix.io/api-references/api-guides/artificial-intelligence/ai-service/ai-tutorial#how-to-communicate-with-an-agent).
{% 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](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/logs).
{% endhint %}