Claude API Agent

The claude-api agent calls the Anthropic Claude API directly to generate text responses within your workflow. Unlike the CLI-based claude-code agent, it requires no local binary — just an API key. This makes it ideal for CI/CD pipelines, headless servers, and environments where installing CLI tools isn’t practical.

The agent supports both standard and gate phases. In standard phases it produces a natural-language response based on the role prompt and upstream context. In gate phases it evaluates the pipeline state and produces a verdict (PASS, ROUTE, or ESCALATE).

---

Sample Phase

- name: review
  type: gate
  agent: claude-api
  role: reviewer
  depends_on: [implement]

---

Phase Configuration

The claude-api agent supports two phase types:

Phase Type	Description
standard	Generates a text response from the role prompt and upstream handoff context
gate	Evaluates pipeline state and produces a verdict: PASS, ROUTE, or ESCALATE

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	"standard" (default) or "gate"
agent	string	Yes	Must be "claude-api"
role	string	Yes	Role file name (without .md) from .cliq/roles/
depends_on	string[]	No	Upstream phases that must complete before this phase runs
model	string	No	Model override. Default: "claude-sonnet-4-20250514"

The model field is specified on the phase declaration and overrides the default model (claude-sonnet-4-20250514) for that phase only.

---

Settings

Configure under agents.claude-api via cliq settings:

Key	Required	Default	Description
agents.claude-api.api_key	Yes	—	Anthropic API key

---

Output

Handoff Structure

The claude-api agent produces a minimal handoff envelope with the LLM response as text:

{
    "data": null,
    "text": "The agent's natural language response and summary of work performed."
}

The data field is always null — all meaningful output is in the text field, which contains the model’s complete response shaped by the role prompt and upstream context.

Gate Verdicts

In gate phases, the agent’s text output is parsed for a verdict:

Verdict	Meaning
PASS	Pipeline continues to the next phase
ROUTE	Pipeline branches to a specified alternative phase
ESCALATE	Pipeline halts and requests human intervention

---

Examples

Example: Code review gate in CI

Use Claude as a headless reviewer that gates whether code proceeds to PR creation.

phases:
    - name: implement
      agent: cursor
      role: developer

    - name: review
      type: gate
      agent: claude-api
      role: reviewer
      depends_on: [implement]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Multi-model pipeline with Opus upgrade

Use the default Sonnet model for drafting and upgrade to Opus for a critical review step.

phases:
    - name: draft
      agent: claude-api
      role: writer

    - name: critique
      type: gate
      agent: claude-api
      role: critic
      model: claude-opus-4-20250514
      depends_on: [draft]

    - name: revise
      agent: claude-api
      role: writer
      depends_on: [critique]

Example: Headless documentation pipeline

A fully headless pipeline for generating and reviewing documentation — runs anywhere with an API key.

phases:
    - name: analyze-code
      agent: claude-api
      role: analyst

    - name: write-docs
      agent: claude-api
      role: technical-writer
      depends_on: [analyze-code]

    - name: quality-check
      type: gate
      agent: claude-api
      role: editor
      depends_on: [write-docs]

---

Setup

1. Go to https://console.anthropic.com/settings/keys
2. Click Create Key and name it (e.g., cliq)
3. Copy the generated key

echo $ANTHROPIC_API_KEY | cliq settings agents.claude-api.api_key --stdin --global
cliq doctor agent claude-api

cliq doctor agent claude-api checks:

• agents.claude-api.api_key is configured in settings
• The API key can authenticate against the Anthropic API

---

See Also

• Agent Overview