Gemini API Agent

The gemini-api agent calls the Google Gemini API directly to generate text responses within your workflow. Unlike the CLI-based gemini 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: summarize
  agent: gemini-api
  role: analyst
  model: gemini-2.5-pro
  depends_on: [fetch-data]

---

Phase Configuration

The gemini-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 "gemini-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: "gemini-2.5-flash"

The model field is specified on the phase declaration and overrides the default model (gemini-2.5-flash) for that phase only.

---

Settings

Configure under agents.gemini-api via cliq settings:

Key	Required	Default	Description
agents.gemini-api.api_key	Yes	—	Google Gemini API key

---

Output

Handoff Structure

The gemini-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: Summarize upstream work in CI

Run a headless summarization step after an implementation phase — no CLI tooling required on the build agent.

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

    - name: summarize
      agent: gemini-api
      role: summarizer
      depends_on: [implement]

Example: Gate review with model override

Use a more capable model for a quality gate that decides whether code passes review.

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

    - name: quality-gate
      type: gate
      agent: gemini-api
      role: reviewer
      model: gemini-2.5-pro
      depends_on: [implement]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [quality-gate]

Example: Headless CI/CD pipeline

A fully headless pipeline suitable for GitHub Actions or similar — no local binaries needed.

phases:
    - name: analyze
      agent: gemini-api
      role: analyst

    - name: draft-response
      agent: gemini-api
      role: writer
      depends_on: [analyze]

    - name: review
      type: gate
      agent: gemini-api
      role: reviewer
      depends_on: [draft-response]

---

Setup

1. Go to https://aistudio.google.com/apikey
2. Click Create API key and select your Google Cloud project
3. Copy the generated key

echo $GOOGLE_API_KEY | cliq settings agents.gemini-api.api_key --stdin --global
cliq doctor agent gemini-api

cliq doctor agent gemini-api checks:

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

---

See Also

• Agent Overview