Skip to main content
This document covers zendesk_read_ticket, the native Zendesk ticket-read tool exposed through the Agents Platform.

​
Authentication & enablement

Zendesk tools use a per-workspace Zendesk connection created in Settings → Integrations → Zendesk. Pick one of two auth methods when connecting:
  • API token — enter your Zendesk URL (e.g. https://acme.zendesk.com), the agent email, and an API token (Admin Center → Apps and integrations → APIs → Zendesk API → add token). Calls authenticate with HTTP Basic {email}/token:{api_token}.
  • OAuth — create an OAuth client in your own Zendesk (Admin Center → Apps and integrations → APIs → OAuth clients; client kind Confidential, redirect URL = the platform’s OAuth callback), then when connecting enter your Zendesk URL plus that client’s client ID and client secret and click through Zendesk’s authorization page (use this if your account has API tokens disabled). Calls authenticate with Bearer <access_token>, refreshed automatically. The OAuth app is per-workspace — there is no shared server-side Zendesk app — so it works for any Zendesk subdomain without a Zendesk “global” client.
Either way, the credentials are injected into the tool at run time from the connected integration and are never visible to the model. Both Zendesk tools are off by default — add them to an agent explicitly.

​
zendesk_read_ticket

Reads a Zendesk ticket by its numeric id. It does not modify the ticket, but it is not free of side effects: it copies the ticket’s intake attachments into platform file storage (see Output) so they can be previewed and processed downstream.

​
Inputs

Required:
  • ticket_id: the numeric Zendesk ticket id (e.g. "12345").
url, email, and api_token are injected from the connected integration — the agent does not supply them.

​
Output

  • description is the ticket’s first-comment body.
  • attachments are the first comment’s attachments (the ticket’s intake files); empty if none — fall back to description. The rest of the conversation’s attachments are out of scope here — a future zendesk_list_comments tool would cover those.
  • Each attachment (≤ 50 MB, and at most the first 20 per read) is copied into platform file storage at read time. Two references are returned: file_id (so the UI can preview it in the app — our own storage is same-origin/CORS-open, unlike the raw content_url) and file_url (a value the agent can pass straight to structured_data_extraction or other file tools to read the contents — a ${VAR_N} ref that resolves to the stored file’s S3 URL, or the raw S3 URL for CodeAct tasks). Best-effort: if the copy fails — or the attachment is over 50 MB or beyond the 20-per-read cap — both refs are omitted and only content_url is returned. Storing is skipped entirely when file storage isn’t wired (e.g. schema-only mode).
  • custom_fields maps field id (as a string) → value.
  • is_assigned is a convenience for deciding whether to write back.
  • ticket_url is the ticket’s Zendesk web URL (omitted if the connection URL can’t be normalized).

​
Limits & errors

  • Fetches the ticket plus its first comment (for attachments); the comment fetch is best-effort, so a failure there still returns the ticket (without attachments).
  • HTTP 404 → check the ticket_id.
  • HTTP 401/403 → the workspace’s Zendesk credentials are invalid; reconnect the integration.
  • “Zendesk is not connected…” → no active Zendesk integration exists for the workspace.

​
Agent Instruction Guidance

Call this before zendesk_write_ticket whenever you need the ticket’s current state — for example to implement a “skip if already assigned” rule: read the ticket, check is_assigned, and only write when it is false. The write tool intentionally does not enforce that guard, so the decision lives here in the agent.