OpenAI API Agent

The openai-api agent calls the OpenAI API directly to generate text responses within your workflow. 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: triage
  agent: openai-api
  role: classifier
  model: gpt-4o
  depends_on: [fetch-ticket]

Phase Configuration

The openai-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 `"openai-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: `"gpt-4o"`

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

Settings

Configure under agents.openai-api via cliq settings:

Key	Required	Default	Description
`agents.openai-api.api_key`	Yes	—	OpenAI API key

Output

Handoff Structure

The openai-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: Fast triage in a support pipeline

Use GPT-4o to quickly classify and route incoming requests before handing off to a specialized agent.

phases:
    - name: triage
      type: gate
      agent: openai-api
      role: triage-router

    - name: handle-bug
      agent: cursor
      role: developer
      depends_on: [triage]

    - name: handle-question
      agent: openai-api
      role: support-responder
      depends_on: [triage]

Example: Reasoning upgrade with o3

Use the default GPT-4o for fast drafting and upgrade to o3 for complex reasoning steps.

phases:
    - name: research
      agent: openai-api
      role: researcher

    - name: synthesize
      agent: openai-api
      role: analyst
      model: o3
      depends_on: [research]

    - name: review
      type: gate
      agent: openai-api
      role: reviewer
      depends_on: [synthesize]

Example: Headless CI validation pipeline

A lightweight validation pipeline that runs entirely via API calls — suitable for GitHub Actions or any CI system.

phases:
    - name: check-conventions
      agent: openai-api
      role: linter

    - name: check-security
      agent: openai-api
      role: security-reviewer
      depends_on: [check-conventions]

    - name: approve
      type: gate
      agent: openai-api
      role: approver
      depends_on: [check-security]

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

Setup

Go to https://platform.openai.com/api-keys
Click Create new secret key and name it (e.g., cliq)
Copy the generated key

echo $OPENAI_API_KEY | cliq settings agents.openai-api.api_key --stdin --global
cliq doctor agent openai-api

cliq doctor agent openai-api checks:

agents.openai-api.api_key is configured in settings
The API key can authenticate against the OpenAI API