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.

#Prerequisites

Before you begin, ensure you have:

#Permissions reference

Agents respect your project's existing role and permission configuration. Only users with permission to manage Content Workflows can create or edit agents.

#Step 1 - Open AI Agents configuration

1. In your Hygraph project, go to AI Hub → Agents.
2. Click Add Agent.

AI Agents - KPIs

#Step 2 - Choose an agent type

Select the agent that matches the workflow you want to automate:

Proceed to the section below that matches your chosen agent type.

#Step 3 - Configure the agent

#SEO expert

The SEO expert reviews all entry fields automatically, including nested components, and posts an SEO report as a comment on the entry. Relation fields are excluded.

1. Click Add Agent, and select Set up next to the SEO expert.
2. Provide a name for the agent, and optionally add a description.
3. Under Number of seats, specify how many agent instances can run concurrently.
4. Select the Workflow where the agent should operate. The agent is triggered only for entries that move through this workflow.
5. Choose the Workflow step where the agent should run:
   • Select an existing step, or
   • Select Add a new AI Agent step to create one:
     1. Under Execute after step, choose the step after which this SEO step should run.
     2. Provide a Step API ID and a Step Display Name.
6. Click Add agent.

Once added, the SEO expert runs automatically at the configured workflow step and posts an SEO report as a comment on the entry.

#Translation agent

The Translation agent translates content between locales while preserving tone, structure, and meaning. This helps teams scale multilingual content creation and ensures consistent messaging across all supported languages.

1. Click Add Agent, and select Set up next to the Translation agent.
2. Provide a name for the agent, and optionally add a description.
3. Under Number of seats, specify how many agent instances can run concurrently.
4. Select the Workflow where the agent should operate.
5. Choose the Workflow step where the agent should run:
   • Select an existing step, or
   • Select Add a new AI Agent step to create one:
     1. Under Execute after step, choose the step after which this translation step should run.
     2. Provide a Step API ID and a Step Display Name.
6. Under Select languages, choose one or more target locales to translate into.
7. Under Custom instructions, optionally provide translation guidance, for example:
   • Use formal tone for business audiences
   • Keep product names untranslated
8. Click Add agent.

Once added, the Translation agent runs automatically at the configured step. It translates content into the target locales while preserving structure, tone, and meaning according to your custom instructions.

#Content summarizer

The Content summarizer generates concise summaries from one or more source fields and writes the output to a target field. This helps teams create consistent excerpts, overviews, or meta descriptions across entries, saving time while maintaining quality and tone.

1. Click Add Agent, and select Set up next to the Content summarizer.
2. Provide a name for the agent, and optionally add a description.
3. Under Number of seats, specify how many agent instances can run concurrently.
4. Select the Workflow where the agent should operate.
5. Choose the Workflow step where the agent should run:
   • Select an existing step, or
   • Select Add a new AI Agent step to create one:
     1. Under Execute after step, choose the step after which this summarization step should run.
     2. Provide a Step API ID and a Step Display Name.
6. Under Content Model, select the model containing the fields to summarize.
7. Under Source Fields, select one or more fields that contain the content to summarize.
8. Under Target Field, select the field where the generated summary will be stored.
9. Under Tone, choose the style or tone for the generated summaries.
10. Under Custom instructions, optionally provide output guidance, for example:
    • Summarize in 2–3 sentences
    • Focus only on key benefits
11. Click Add agent.

Once added, the Content summarizer runs automatically at the configured step. It generates short, context-aware summaries for the selected entries in the specified target field while maintaining the specified tone and following your custom instructions.

#Start using AI Agents

Once your agents are configured, verify they are working by moving an entry through the relevant workflow and confirming the agent runs automatically.

Verify in Hygraph Studio

• For the SEO expert, open the entry and check the SEO report is available as a comment on the entry.
• For the Translation agent, confirm translated content appears in the localized fields.
• For the Content summarizer, open the target field on the entry and confirm the summary was written correctly.

Check the Recent activity panel on the agent card to confirm the run completed without errors. If the agent card shows an error or the expected output is missing, see Troubleshooting.

#Manage agents

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

Each agent card displays:

• Agent type — SEO expert, Translation, or Content summarizer
• Workflow and workflow step where it runs
• Number of seats
• Agent configuration details
• **Agent status

View activity logs: Click Recent activity on the agent card to see a log of recent agent runs. Use this to monitor agent performance and catch unexpected output.

Edit an agent: Click the pencil icon on the agent card. You can update the name, description, number of seats, workflow or workflow step, and any tone, locale, or custom instruction fields depending on the agent type.

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.

#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

Each agent displays the following summary metrics:

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 at the bottom lists individual runs with their status, result, duration, and startast run date. Use this to investigate specific runs that failed or produced unexpected output. Click each workflow run to view additional details.

#Best practices

• Set the number of seats based on your expected content volume to avoid bottlenecks during high-throughput periods.
• Monitor AI token usage on the Billing page to stay within your plan limits. Avoid configuring agents on high-volume workflows without first estimating token consumption.
• Always validate AI-generated content for accuracy, tone, and alignment before publishing. Set up your workflow with a human review step after agent steps in sensitive or regulated content.
• Review agent configurations periodically to ensure custom instructions remain accurate and up to date.
• Position your agents strategically in workflows. Run these agents during the Pre-publish or Optimization steps so they run on finalized content and produce the most accurate, high-quality results.
• For multilingual projects, pair the SEO expert with a Translation agent to provide feedback on localized SEO metadata.

#Troubleshooting

#Agent does not run

• Confirm the agent status is active in AI Hub → Agents.
• Confirm the entry is moving through the exact workflow and workflow step where the agent is configured.
• Verify that sufficient AI tokens remain in your billing period on the Billing page.

#Agent runs but content is unchanged

• Confirm the workflow step order. If the agent step runs before content is populated, it has nothing to process.
• Check recent activity logs on the agent card for error messages.

#SEO report does not appear

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

#Translation output is missing or incorrect

• Verify that the target locale is enabled in your Hygraph project.
• Check that the source fields contain content at the time the agent runs.
• Review your custom instructions for conflicting or ambiguous guidance.

#Summary written to wrong field

• Open the agent configuration and confirm the target field is set correctly.
• Ensure no other agent is writing to the same target field, which could cause overwrite conflicts.

#Next steps

• Monitor agent runs and token consumption on the KPIs page in AI Hub.
• Learn more about workflow configuration in Content Workflows.
• Explore the MCP server for direct AI assistant integration with your Hygraph project..