Skip to main content

Zendesk Advanced AI Agent

warning

Do not test against your live ("production") Zendesk agent. Zendesk cannot tell test queries from real customer queries and may bill you the Automated Resolution price for every test query. Always test against a Zendesk sandbox. See Testing with a Zendesk sandbox.

Zendesk sells two kinds of AI agent, and Spec27 has a registry integration for each:

Your Zendesk setupUse this integration
Advanced AI agent, routed by conversation metadataZendesk Advanced AI Agent (this page)
Essential AI agent on the legacy Answer Bot and flow pathZendesk Essential AI Agent (Legacy)

Both remain supported. Pick the one that matches how your agent is configured in Zendesk.

This integration opens one Zendesk conversation and keeps it for every turn of an evaluation. It sets your routing value in the conversation metadata, hands control to the Advanced AI agent, then returns what the agent posts back.

Required secrets​

SecretWhat it is
ZENDESK_SUBDOMAINZendesk subdomain without .zendesk.com.
ZENDESK_APP_IDZendesk Conversations API app ID.
ZENDESK_KEY_IDZendesk Conversations API key ID.
ZENDESK_SECRETZendesk Conversations API secret.
ZENDESK_SDK_APP_IDZendesk app ID used by the Web SDK bootstrap endpoint.
ZENDESK_SDK_INTEGRATIONZendesk Web integration ID used for conversation bootstrap and Advanced AI Agent execution.
ZENDESK_TARGET_AGENTRouting value that selects your Advanced AI agent. See below.

The first six come from your Zendesk Sunshine Conversations configuration: the API key ID and secret from your API key, the app IDs and Web integration ID from your integration settings, and your account subdomain. Store each as a project secret.

Where to get ZENDESK_TARGET_AGENT​

ZENDESK_TARGET_AGENT is different from the other six. Zendesk does not generate it for you to copy out of a settings page. It is the routing value that you chose when you set up metadata-based routing for your Advanced AI agent, and both sides have to use the same string.

The adapter sends it on the conversation like this:

{ "metadata": { "spec27_target_agent": "<ZENDESK_TARGET_AGENT>" } }

The metadata key spec27_target_agent is fixed and you cannot change it. Only the value is yours to set.

To find the right value:

  1. Open the routing rule for the Advanced AI agent you want to evaluate in Zendesk.
  2. Read the metadata condition it matches on. The rule listens for the spec27_target_agent key and compares its value.
  3. Copy that value exactly, including case and any underscores.

If nobody has configured routing yet, choose a value first, add a rule that routes conversations carrying that spec27_target_agent value to your Advanced AI agent, then store the same value as the secret. A short lowercase identifier works well, for example billing_support_v1.

The value must be 1 to 128 characters, start with a letter or digit, and use only letters, digits, and the characters _, ., :, and -. The agent fails at startup if the secret is missing or does not match that shape.

To confirm you got it right, preview the agent and send one question. If the value does not match a routing rule, Zendesk leaves the conversation with your default responder, so the reply comes back from the wrong agent instead of failing outright. Check which agent answered before you trust a passing preview.

What the agent returns​

An Advanced AI agent usually answers in several messages. It greets you, says it is looking something up, then posts the answer.

This integration returns all of them, in order, separated by blank lines. A single turn can therefore come back looking like this:

Hi there!

Give me a moment while I retrieve the plan details.

Premium includes 24/7 coverage.

Write your specifications against that whole sequence rather than the final message alone. Greetings and progress updates never end a turn on their own, so the agent keeps waiting for a real answer even when filler arrives first.

Turn support​

Multi-turn. One conversation is preserved across every turn of a run, which suits multi-turn evaluation. Control returns to the Advanced AI agent before each new turn, because Zendesk can move a conversation elsewhere after a reply.

Limitations and notes​

  • All seven secrets are required. The agent will not connect on a partial configuration.
  • The input is one non-empty question string. This integration does not accept the JSON input modes that the legacy fixture supports.
  • If a message is submitted and the outcome is unclear, the agent stops the run instead of sending it again. A repeat could trigger the same Zendesk tool calls twice, so no message is ever resent.

Set it up​

  1. Set up a Zendesk sandbox for testing. See Testing with a Zendesk sandbox. Do not test against your production agent.
  2. Confirm your Advanced AI agent has a routing rule that matches on spec27_target_agent, and note its value.
  3. Copy this integration from the registry. See Registry integrations.
  4. Create the seven project secrets above. See Project secrets.
  5. Preview the agent and confirm the reply came from the agent you expected.