Zendesk Agent

The zendesk agent connects to Zendesk Support via the REST API v2. It uses email/token authentication to fetch tickets, retrieve comments, search across your helpdesk, add replies, and update ticket status. Source data is written as JSON to the workspace. Target operations read content from workspace files and push it to Zendesk.

Use this agent to integrate support workflows into your pipeline — pull ticket context for an AI agent to analyze, auto-reply to tickets after processing, or update status based on pipeline outcomes.

---

Sample Phase

- name: fetch-ticket
  agent: zendesk
  action: get_ticket
  sources:
      - name: ticket.json
        ref: "12345"

---

Phase Configuration

The zendesk agent uses phase:standard capability. Every phase declaration requires an action field that determines what operation to perform.

Actions

Action	Direction	Description
get_ticket	Source	Fetch a single ticket by ID
get_comments	Source	Fetch all comments on a ticket
search	Source	Run a Zendesk search query
add_comment	Target	Post a comment to a ticket
update_status	Target	Change a ticket’s status

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "zendesk"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
action	string	Yes	One of: get_ticket, get_comments, search, add_comment, update_status
sources	SourceEntry[]	For fetch actions	Entries to fetch from Zendesk
target_entries	TargetEntry[]	For write actions	Entries to deliver to Zendesk

Source Entry Fields

Field	Type	Required	Description
name	string	Yes	Output filename written to .cliq/files/{phase}/
ref	string	Yes	Ticket ID (number) for get_ticket/get_comments, or search query string for search

Target Entry Fields

Field	Type	Required	Description
name	string	Yes	Identifier for the operation
ref	string	Yes	Ticket ID to act on
file	string	Yes	Workspace file containing comment text (add_comment) or status value (update_status)

---

Settings

Key	Required	Default	Description
agents.zendesk.subdomain	Yes	—	Zendesk subdomain (e.g., mycompany for mycompany.zendesk.com)
agents.zendesk.email	Yes	—	Zendesk account email for API authentication
agents.zendesk.api_token	Yes	—	Zendesk API token

---

Output

Handoff Structure

Source operation — get_ticket:

{
    "data": {
        "action": "get_ticket",
        "sources": {
            "ticket.json": {
                "ref": "12345",
                "ticket_id": 12345,
                "subject": "Cannot login to dashboard",
                "status": "open"
            }
        },
        "targets": {}
    },
    "text": "## Zendesk Results\n\n✓ Fetched ticket.json — #12345: Cannot login to dashboard (open)"
}

Source operation — search:

{
    "data": {
        "action": "search",
        "sources": {
            "results.json": {
                "ref": "status:open type:ticket",
                "count": 7
            }
        },
        "targets": {}
    },
    "text": "## Zendesk Results\n\n✓ Searched results.json — 7 tickets matched"
}

Target operation — add_comment:

{
    "data": {
        "action": "add_comment",
        "sources": {},
        "targets": {
            "reply": {
                "ref": "12345",
                "ticket_id": 12345,
                "comment_id": "98765",
                "status": "ok"
            }
        }
    },
    "text": "## Zendesk Results\n\n✓ Commented on ticket #12345"
}

Field Reference

Field	Location	Description
ref	data.sources.*, data.targets.*	Original ref value (ticket ID or search query)
ticket_id	data.sources.*, data.targets.*	Numeric ticket ID
subject	data.sources.*	Ticket subject line (present on get_ticket)
status	data.sources.*, data.targets.*	Ticket status or operation status
count	data.sources.*	Number of results (present on search, get_comments)
comment_id	data.targets.*	ID of created comment (present on add_comment)

Files Written

Source responses are saved to .cliq/files/{phase}/{source.name} as JSON. Ticket data includes all Zendesk fields (requester, assignee, tags, custom fields, etc.).

Downstream Access

Reference ticket data in downstream phases:

commands:
    - name: check-status
      run: 'echo "Ticket status: $(handoff.fetch-ticket.sources.ticket.json.status)"'

---

Examples

Example: Fetch a ticket and draft a response

Pull a support ticket into the workspace, then have an AI agent draft a reply.

phases:
    - name: fetch-ticket
      agent: zendesk
      action: get_ticket
      sources:
          - name: ticket.json
            ref: "12345"

    - name: draft-reply
      agent: cursor
      role: support-agent
      depends_on: [fetch-ticket]

Example: Search open tickets and triage

Search for unresolved tickets, then process them with an analyst agent.

phases:
    - name: search-open
      agent: zendesk
      action: search
      sources:
          - name: open-tickets.json
            ref: "status:open type:ticket group:engineering"

    - name: triage
      agent: cursor
      role: triage-analyst
      depends_on: [search-open]

Example: Post an automated reply

After a processing phase generates a response, post it back to the ticket.

phases:
    - name: draft-reply
      agent: cursor
      role: support-agent

    - name: post-reply
      agent: zendesk
      action: add_comment
      depends_on: [draft-reply]
      target_entries:
          - name: reply
            ref: "12345"
            file: reply.txt

Example: Close a ticket after resolution

Update a ticket’s status to solved once a pipeline confirms the issue is resolved.

phases:
    - name: verify-fix
      agent: exec
      commands:
          - name: test
            run: ./scripts/verify-fix.sh

    - name: close-ticket
      agent: zendesk
      action: update_status
      depends_on: [verify-fix]
      target_entries:
          - name: resolve
            ref: "12345"
            file: status.txt

The status.txt file should contain the target status value (e.g., solved).

---

Setup

1. In your Zendesk admin panel, go to Apps and Integrations → Zendesk API
2. Enable Token Access and generate an API token
3. Note your subdomain (the part before .zendesk.com)

cliq settings agents.zendesk.subdomain mycompany --global
cliq settings agents.zendesk.email [email protected] --global
echo $ZENDESK_TOKEN | cliq settings agents.zendesk.api_token --stdin --global
cliq doctor agent zendesk

---

See Also

• Agent Overview
• Agent SDK