# Set up AI Agents

Step-by-step guide to configuring and using AI Agents in your Hygraph project for translation, summarization, and SEO automation.

This guide walks you through configuring AI Agents in your Hygraph project. For an overview of what AI Agents can do, see [AI Agents overview](https://hygraph.com/docs/hygraph-ai/ai-agents).

## Prerequisites

Before you begin, ensure you have:

- A Hygraph project on Enterprise plan
- To run agents in workflows, you need a user with permission to configure [Workflows](https://hygraph.com/docs/developer-guides/project/content-workflows) and at least one [workflow](https://hygraph.com/docs/developer-guides/project/content-workflows) configured in your project
- At least one content model with fields to target
- Sufficient [AI tokens](https://hygraph.com/docs/developer-guides/project/update-billing) for your billing period

## Permissions

Agents respect your project's existing role and permission configuration.

| Permission name  | Default role |
|-----------------|------------------|
| Create a new agent config | Admin |
| Update an agent config | Admin |
| Read agent config | Admin |
| Trigger an agent run | All roles |

## Step 1 - Choose an agent type

1. Go to **AI Hub > Agents**.
2. Click **Add Agent**.
3. Select one of the following agent types:
   - **SEO & GEO Expert**: Reviews entry fields and posts a structured SEO & GEO report as a comment. Relation fields are excluded.
   - **Translator agent**: Translates content fields into one or more target locales. Relation fields are not translated.
   - **Content summarizer**: Generates concise summaries from source fields.
4. Click **Set up** to configure the agent.

## Step 2 - Configure agent details

All agent types share the same **Agent details** section.

1. Enter an **Agent name**.
2. Optionally, enter a **Description**.
3. Under **Guidelines to apply**, optionally select guidelines the agent must apply. The agent defaults to no guidelines if none are selected. If no guidelines exist yet, click **Create guidelines** to set them up first. See [AI Guidelines](//docs/hygraph-ai/ai-guidelines#create-a-guideline) for setup instructions.

## Step 3 - Set usage mode

The **Usage** section controls how the agent is triggered. Select one of the following options:
- **Use in Agent runs** (selected by default)
- **Use in workflows**

### Use in Agent runs

The agent is available for manual triggering from the content table for bulk updates and the content entry form for single entry updates.

Under **Models (scope)**, optionally select the models the agent can be used on. If no models are selected, the agent defaults to all models in the project.

Models that are already used in an active workflow appear as **Not available - used in a workflow** in the selector. If a model is added to a workflow after the agent is configured, it is removed from the agent's scope automatically for manual triggering.

### Use in workflows

The agent runs automatically when an entry moves through a configured workflow step.

- Under **Workflow**, select the workflow where the agent should operate.
- Under **Workflow step**, select the step where the agent should run, or select **Add a new AI Agent step** to create one:
  1. Under **Execute after step**, choose the preceding step.
  2. Enter a **Step API ID** and **Step Display Name**.

If no workflows exist in your project yet, you need to create one first. The agent cannot be saved in workflow mode until a workflow and step are selected.

## Step 4 - Configure agent-specific settings

### SEO & GEO Expert

No additional configuration is required. Click **Add Agent**.

### Translator agent

1. Under **Languages to translate**, select one or more target locales.
2. Optionally, under **Custom instructions**, provide translation guidance, for example:
   - "Use formal tone for business audiences"
   - "Keep product names untranslated"
3. Click **Add Agent**.

**Note:**
  When the Translator agent runs, it overwrites all existing content for the selected locales, including fields that have not changed. This applies to both agent runs and workflow triggers. Review the localized content after each run to ensure no previously translated fields were unintentionally overwritten.

### Content summarizer

The Content summarizer has a **Configuration** section labelled "Configured when launching the agent." Source fields, target fields, and other summarizer settings are set each time the agent is launched, not during setup.

1. Optionally, under **Custom instructions**, provide output guidance, for example:
    - "Summarize in 2–3 sentences"
    - "Focus only on key benefits"
2. If you are configuring the agent for **Use in workflows**, configure the following fields. These settings are not required for **Use in Agent runs**. Instead, they are configured at runtime. See [Configure a Content summarizer agent run](#configure-a-content-summarizer-agent-run).
    - Under **Content Model**, select the model containing the fields to summarize.
    - Under **Input Fields**, select the source fields containing the content to summarize.
    - Under **Output Field**, select the field where the generated summary will be stored.
    - Under **Tone**, choose the style or tone for the generated summaries.
3. Click **Add Agent**.

#### Configure a Content summarizer agent run

When you trigger a Content summarizer agent manually, a configuration panel appears before the run starts.

1. Under **Input fields**, select the source fields containing the content to summarize.
2. Under **Entries**, review the content entries whose source fields will be summarized. This field is read-only.
3. Under **Output field**, select the field where the generated summary will be written.
4. Under **Tone**, choose the tone for the generated summary.
5. Confirm to start the run.

For bulk runs from the content table, the same configuration applies to all selected entries.

## Trigger an agent

**Warning:**
  Only one agent run can be active per entry at a time. If an entry already has an active run, or has a completed run awaiting review, it cannot be triggered again until the review is completed.

### Bulk updates in the content table

This applies only to agents configured for **Use in Agent runs**.

1. Go to the **Content** tab and open a view of a content model that has the agent configured for **Use in Agent runs**.
2. Select one or more entries using the checkboxes in the content table.
3. In the action bar at the bottom of the screen, click **Agents** and select the agent you want to run.

The agent runs on all selected entries, up to a maximum of 50 entries per run. The selected content entries become read-only while the agent runs.

### Single entry updates in the content entry form

This applies only to agents configured for **Use in Agent runs**.

1. Open any entry for a model that has the agent configured for **Use in Agent runs**.
2. In the right sidebar, locate the **Agents** panel.
3. Select the agent you want to run and confirm.

The content entry form becomes read-only while the agent runs.

### Workflows

This applies only to agents configured for **Use in workflows**.

An agent configured to run through workflows runs automatically when an entry moves through a configured workflow step.

## Review agent output

The content table shows agent status so you can see entries that need action without opening each one individually.

| Agent status | Description |
|---|---|
| **Pending** | Entries where an agent run is queued or in progress |
| **Ready for review** | Entries where a completed run is awaiting your review |
| **Failure** | Entries where the agent run did not complete successfully |

When an entry shows **Ready for review**, open it to check what the agent changed and approve or revert changes field by field.

When an agent run completes, the entry displays a **Ready for review** status and the content entry form remains read-only until the review is complete.

1. Open the entry that shows **Ready for review**.
2. The review screen shows a side-by-side diff of the original content and the agent's output.
3. Review each field. Approve changes you want to keep, or revert any you don't.
4. If you revert all fields, the entry returns to its exact pre-agent state.
5. Once all fields are reviewed, the entry exits read-only state and is editable again.

## Manage agents

After creating agents, you can manage and monitor them from **AI Hub → Agents**.

Each agent card displays:
- **Agent name**
- **Agent type** - SEO & GEO Expert, Translator, or Content summarizer
- Target where it runs: Workflow or content table, content entry form
- **Agent configuration** details
- **Agent status**

You can perform the following tasks:

**Edit an agent:** Click the pencil icon on the agent card to update the name, description, usage mode, guidelines, or agent-specific settings.

**Enable or disable an agent:** Use the toggle on the agent card to turn the agent on or off. Disabling an agent pauses it without removing its configuration. This is useful when you want to temporarily stop an agent without losing its settings, for example during content freezes or workflow changes. Any runs already in progress when an agent is disabled will complete normally.

**Delete an agent:** Click the three-dot context menu on the agent card, then click **Delete**. Deleting an agent removes it from all workflows, and any queued or pending runs are automatically canceled. Deleting an agent is irreversible.

## Monitor agent performance
 
The **KPIs** page in **AI Hub → KPIs** gives you a real-time view of how your agents are performing. You can filter by agent and date range to focus on a specific agent or time period.

![AI Agents - KPIs](https://hygraph.com/images/docs/hygraph-ai/ai-agents-kpis.png)
 
Each agent displays the following summary metrics:
 
| Metric            | Description                                                    |
|-------------------|----------------------------------------------------------------|
| **Runs**          | Total number of times the agent has run in the selected period |
| **Success rate**  | Percentage of runs that completed without errors               |
| **Last run**      | Time elapsed since the most recent run                         |
| **Avg. duration** | Average time taken to complete a run                           |
| **AI tokens**     | Total number of AI tokens consumed in the selected period      |
 
Below the summary metrics, the **AI Tokens Trend** chart shows token consumption over time. Switch to the **Duration** tab to view run duration trends instead.
 
The **Workflow Runs** table lists individual runs with their status, result, duration, and start date. Use this to investigate specific runs that failed or produced unexpected output. Click each workflow run to view additional details.

## Troubleshooting

### Agent does not run

- Confirm the agent is active in **AI Hub > Agents**.
- For workflow agents, confirm the entry is moving through the exact workflow and step where the agent is configured.
- Verify that sufficient AI tokens remain in your billing period on the [**Billing** page](https://hygraph.com/docs/developer-guides/project/update-billing).

### Agent runs but output is unchanged

- For workflow agents, check the step order. If the agent step runs before content is populated, it has nothing to process.

### SEO report does not appear

- Check the comment section on the entry, not the fields.
- Confirm the entry completed the configured workflow step after the agent was added.

### Translation output is missing or incorrect

- Verify the target locale is enabled in your project.
- Confirm source fields contain content when the agent runs.
- Review custom instructions for conflicting or ambiguous guidance.

### Summary written to wrong field

- Open the agent configuration and confirm the target field is set correctly.
- Confirm no other agent is writing to the same target field.

### Model no longer appears in agent run scope

- The model was added to a workflow after the agent was configured. Models used in active workflows are not available for agent runs.
- Select a different model or reconfigure the workflow.

## What's next

- [Workflows](https://hygraph.com/docs/developer-guides/project/content-workflows): Learn more about workflow configuration.
- [MCP server](https://hygraph.com/docs/hygraph-ai/mcp-server): Explore the MCP server for direct AI assistant integration with your Hygraph project.