> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Built-in agents, agent types, and where to find the connector action API reference.

An **agent** is a registered runtime the daemon invokes for a phase (`agent: <name>` in the team manifest). Built-ins ship with the platform and are classified by **`agent_type`**.

For how agents fit into teams and when **roles** apply, see [Concepts](/concepts). To run a team end-to-end, see [Running teams](/running-teams).

Configure credentials with `cliq setup` or:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq settings set agents.<name>.<key> <value>
```

List what the daemon can resolve, and register custom agents on Hub:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq agent list
cliq agent list --check-reg
cliq agent register my-linter
```

Custom agents live on the local agents path (`CLIQ_AGENTS_PATH` or `agents.path`; `~/.cliqrc/agents` is always last). Hub stores catalog metadata only — binaries are not pulled from Hub. See [CLI → Agents](/cli#agents) and [Hub Agents](/hub-api/overview#agents).

### Creating a custom agent

Use **`@getcliqio/cliq-sdk`** from [GitHub Packages](https://github.com/getcliqio/cliq-sdk/pkgs/npm/cliq-sdk):

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# ~/.npmrc — scope + token (PAT with read:packages)
@getcliqio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

mkdir -p ~/.cliqrc/agents/my-agent && cd ~/.cliqrc/agents/my-agent
npm init -y
npm install @getcliqio/cliq-sdk
```

Implement `CliqAgent` handlers, add a `manifest.json`, then:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq agent info my-agent
cliq agent register my-agent
```

Step-by-step guide: [Building Agents](/building-agents).

***

## Agent types

| Type | Role? | Typical inputs | Used for |
| - | :-: | - | - |
| **`llm`** | Yes | `role`, `model`, … | Model / coding-CLI work and LLM gates |
| **`exec`** | No | `commands` | Deterministic shell steps |
| **`connector`** | No | `action`, `sources`, `target_entries` | External systems |
| **`gate`** | Special | Gate / review config | `hug`, `auto-gate` |
| **`notify`** | No | notify channel wiring | Slack, email, … |
| **`meta`** | No | `team` | Nested team launch |

***

## LLM agents

Shared phase inputs (all `agent_type: llm`):

| Input | Required | Default | Description |
| - | :-: | - | - |
| `role` | yes | — | Specialist brief for this phase (prompt text) |
| `model` | no | per agent | Model id |
| `temperature` | no | — | Sampling temperature |
| `max_turns` | no | — | Max conversation turns |
| `needs_filesystem` | no | varies | Whether the coding tool may use the workspace |
| `task` | no | runtime | Requirement / instruction (often from run inputs) |

Capabilities: `phase:standard`, `phase:gate` (unless noted).

| Agent | Settings (required) | Default model | Notes |
| - | - | - | - |
| `cursor` | `api_key` | `claude-sonnet-4-20250514` | Coding CLI (`agent` binary); `needs_filesystem` default `true` |
| `claude-code` | `api_key` | `claude-sonnet-4-20250514` | Coding CLI (`claude`); `needs_filesystem` default `true` |
| `gemini` | `api_key` | `gemini-2.5-pro` | Coding CLI (`gemini`); `needs_filesystem` default `true` |
| `codex` | `api_key` | `gpt-4.1` | Coding CLI (`codex`); `needs_filesystem` default `true` |
| `claude-api` | `api_key` | `claude-sonnet-4-20250514` | Anthropic REST API |
| `gemini-api` | `api_key` | `gemini-3.8-flash` | Google API |
| `openai-api` | `api_key` | `gpt-4o` | OpenAI API |

Example phase:

```yaml theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
- name: implement
  type: standard
  agent: cursor
  depends_on: [plan]
```

Role text for the phase is supplied when the team is assembled / run (LLM phases only). Model overrides can be set on the phase payload where the team author allows it.

***

## Exec agents

| Agent | Inputs | Description |
| - | - | - |
| `exec` | `commands` (`command[]`, **required**) — each `{ run: string }` | Run shell commands in order |
| `echo` | *(none)* | Echo upstream data (test / plumbing) |

```yaml theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
- name: greet
  type: standard
  agent: exec
  commands:
    - run: echo "hello from exec"
```

***

## Connector agents

Connectors talk to external systems. They do **not** use roles.

Full action reference is in the left nav under **Agents** (one agent per subgroup, one action per operation) — generated from [`openapi/agents.yaml`](/openapi/agents.yaml).

**How required params work**

1. **Settings** (`agents.<name>.*`) — credentials; required before the daemon will spawn the agent.
2. **Phase inputs** — fields on the phase in `team.yml` (`action`, `sources`, `target_entries`, …).
3. **Per-action entry fields** — each item inside `sources` / `target_entries` must include the required fields for that `action`.

Source of truth: `cliq-agents/<name>/manifest.json` → `inputs` + `actions`.

> Regenerated from manifests. Full action reference: Docs left nav → **Agents** — powered by [`openapi/agents.yaml`](/openapi/agents.yaml).

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
node documentation/scripts/sync_agent_capability_docs.mjs
```

```yaml theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
- name: fetch-docs
  agent: gdrive
  sources:
    - url: "{{inputs.gdrive_folder}}"
      name: research-sources
```

***

## Gate agents

Team phases use `type: gate`. The phase agent is usually an **`llm`** agent (verdict in the model response). Specialized gate agents:

| Agent | Settings | Inputs | Description |
| - | - | - | - |
| `hug` | `server_url` (**required**); optional `token`, chat/UI knobs | `role` (**required**), `review` (**required** object) | Human-in-the-loop review |
| `auto-gate` | — | *(none)* | Deterministic auto gate |

LLM gates also support phase `commands` + `max_iterations` on the phase itself (orchestrator loop), not as agent manifest inputs.

***

## Notify agents

Used for lifecycle notifications (`notify` capability), not as normal work phases.

| Agent | Settings (required) | Inputs |
| - | - | - |
| `slack` | `channels` (channel → webhook map) | optional `notify` (`string[]`) |
| `email` | `smtp_host`, `channels` (channel → address); optional SMTP user/pass/port/tls/`from_address` | notify wiring |

***

## Meta agents

| Agent | Inputs | Description |
| - | - | - |
| `team` | Driven by phase `team` + `args` | Nested team launch for `type: team` and each `type: map` iteration |

```yaml theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
- name: call-universe
  type: team
  team: "@cliq/hello-universe"
  depends_on: [greet]
  args:
    task: "{{inputs.task}}"

- name: implement
  type: map
  team: "{{item.team}}"
  over_file: lld.json
  over_field: implement
  key: "{{item.slug}}"
  concurrency: 1
  args:
    slug: "{{item.slug}}"
```

Map details: [Workflows & phases](/workflows).

***

## Choosing an agent

| You need… | Prefer |
| - | - |
| Write / edit code with a coding tool | `cursor`, `claude-code`, `codex`, `gemini` |
| Pure LLM call without a coding CLI | `claude-api`, `gemini-api`, `openai-api` |
| Shell checks or scripts | `exec` |
| Fetch/push to SaaS or object storage | connector for that system |
| Human approval | `type: gate` + `agent: hug` |
| Nested pipeline (once) | `type: team` + `team: @scope/slug` |
| Nested pipeline over a list | `type: map` + `over` / `over_file` |

List what your daemon has registered:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq agent list
cliq agent list --check-reg
cliq agent info <name>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.