Agent Overview

In cliq, every phase runs as an independent agent process. When the orchestrator reaches a phase, it spawns the assigned agent in its own tmux pane, passes the phase context via the SDK protocol, and waits for completion. This isolation means phases can run different LLMs, CLI tools, or connectors without interfering with each other.

How Agents Are Resolved

When the orchestrator needs to run a phase, it resolves the agent name through a two-layer lookup (highest priority first):

Team agents — agents declared in .cliq/agents.json (generated by cliq assemble from team.yml)
Installed agents — agents in ~/.cliqrc/agents/ (built-in agents extracted by cliq setup, plus any user-installed agents)

Within the team layer, agents declared in team.yml under agents: take priority. This means a team can shadow a built-in agent by registering a custom agent with the same name.

If a phase doesn’t specify an agent: field, cliq uses the default agent from settings.json (which defaults to cursor).

Resolution Example

team.yml declares: agents.curl → agents/custom-curl/index.js
~/.cliqrc/agents/curl/manifest.json → built-in curl

Phase uses: agent: curl
Resolved to: agents/custom-curl/index.js (team wins)

How Custom Agents Shadow Builtins

To override a built-in agent, declare an agent with the same name in your team.yml:

agents:
    curl:
        entry: agents/custom-curl/index.js

Every phase that uses agent: curl now runs your custom implementation. The built-in curl agent is still available to other teams that don’t shadow it. To revert, remove the agents.curl entry from team.yml and re-assemble.

The `default` Agent Setting

Set in settings.json under default_agent:

{
    "default_agent": "claude-code"
}

Every phase without an explicit agent: field uses this value. The factory default is cursor.

The `agent:` Field on Phases

Override the agent for any phase in your workflow YAML:

phases:
    - name: implement
      agent: claude-code
      role: developer

    - name: review
      agent: gemini-api
      model: gemini-2.5-pro
      role: reviewer

    - name: fetch-tickets
      agent: jira
      action: get_issue
      sources:
          - name: ticket.json
            ref: PROJ-123

Validation

Every agent ships a manifest.json that declares its requirements — settings keys, capabilities, and schema for phase YAML fields. Cliq validates these at multiple points:

cliq assemble — validates phase YAML against the agent’s manifest schema and checks settings requirements.
cliq doctor agent <name> — reports the agent’s version, source, capabilities, and missing settings.
Orchestrator (at spawn time) — checks all manifest.settings.required keys are configured before spawning the agent.

Run validation for a specific agent:

cliq doctor agent <name>

Or validate all agents used by a team:

cliq doctor <team-ref>

The doctor command reads each agent’s manifest and reports version, source (team/installed/builtin), capabilities, and any missing prerequisites.

Built-in Agent Categories

CLI Agents

Wrap interactive coding CLI tools. Each spawns a binary, passes a prompt, and captures output.

Agent	Binary	Env Var	Description
`cursor`	`agent`	`CURSOR_API_KEY`	Cursor IDE coding agent
`claude-code`	`claude`	`ANTHROPIC_API_KEY`	Claude Code CLI agent
`gemini`	`gemini`	`GOOGLE_API_KEY`	Gemini CLI agent
`codex`	`codex`	`OPENAI_API_KEY`	OpenAI Codex CLI agent

LLM API Agents

Call LLM APIs directly — no CLI binary needed. Support tool use, multi-turn conversation, and the model field on phases.

Agent	Default Model	Env Var	Description
`gemini-api`	`gemini-2.5-flash`	`GEMINI_API_KEY`	Gemini API (direct)
`claude-api`	`claude-sonnet-4-20250514`	`ANTHROPIC_API_KEY`	Claude API (direct)
`openai-api`	`gpt-4o`	`OPENAI_API_KEY`	OpenAI API (direct)

Connector Agents

Fetch data from external services or deliver results to them. Use sources, target_entries, and action fields.

Agent	Env Vars	Description
`git`	(see settings)	Git provider integration (GitHub / Bitbucket PRs)
`curl`	(none)	Generic HTTP request agent
`jira`	`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`	Jira issue tracker
`zendesk`	`ZENDESK_SUBDOMAIN`, `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN`	Zendesk support tickets
`datadog`	`DATADOG_API_KEY`, `DATADOG_APP_KEY`	Datadog monitoring
`hubspot`	`HUBSPOT_ACCESS_TOKEN`	HubSpot CRM
`confluence`	`CONFLUENCE_BASE_URL`, `CONFLUENCE_EMAIL`, `CONFLUENCE_API_TOKEN`	Confluence wiki
`gdrive`	`GOOGLE_CREDENTIALS`	Google Drive docs/sheets
`s3`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	AWS S3 objects
`slack`	(see settings)	Slack notification agent — posts to webhook channels. Notify-only.
`email`	(see settings)	Email notification agent — sends via SMTP. Notify-only.

Special-Purpose Agents

Agent	Env Vars	Description
`exec`	(none)	Shell command executor
`mesh`	`SVANTIC_URL`, `SVANTIC_CLIENT_ID`, `SVANTIC_CLIENT_SECRET`	Svantic mesh reasoning agent

Handoff Envelopes

Every agent — CLI, LLM API, connector, or special — produces a handoff envelope when it completes. The envelope is a JSON file (handoff.json) written to the output channel directory, and it always has two parts:

Field	Purpose	Who consumes it
`text`	Natural language summary of what the agent did	Downstream LLM agents — injected directly into their prompt
`data`	Structured payload with machine-readable results	Template variables `$(handoff.<phase>.<path>)`, custom SDK agents, and LLM prompts (rendered as formatted JSON)

Both fields are optional, but in practice every agent produces at least one. The SDK renders both into downstream prompts automatically — workflow authors don’t need to wire anything for LLM-to-LLM handoffs.

What `data` looks like

The shape of data varies by agent type:

LLM and CLI agents — data contains whatever structured information the agent chose to include (file lists, metrics, decisions). The text field is the agent’s natural language output.

Connector agents — data follows a consistent pattern with name-keyed maps of sources and targets. Each entry includes metadata like URLs, file paths, sizes, and agent-specific fields:

{
    "action": "get_issue",
    "sources": {
        "ticket.json": {
            "ref": "PROJ-123",
            "url": "https://myco.atlassian.net/browse/PROJ-123",
            "type": "issue",
            "key": "PROJ-123",
            "summary": "Fix login timeout",
            "status": "In Progress",
            "file": ".cliq/files/fetch-ticket/ticket.json"
        }
    },
    "targets": {}
}

Gate agents — data contains the verdict, check results, and iteration info. The text field explains the decision.

Using handoff data in workflows

Wire structured data from upstream phases directly into downstream YAML — no agent interpretation needed:

- name: notify
  agent: curl
  target_entries:
      - name: slack
        url: "https://hooks.slack.com/services/..."
        body: '{"text": "Issue $(handoff.fetch-ticket.sources.ticket_json.key): $(handoff.fetch-ticket.sources.ticket_json.summary)"}'

See each agent’s page for the complete handoff structure with JSON examples.