Build agents

Agent manifests support prompt chains, conditions, loops, tools, approvals, webhooks, code steps, and sub-runs. The examples use the same manifest format for CLI, embedded, and remote execution.

Setup

Create a project and install the CLI:

mkdir agent-runtime-examples
cd agent-runtime-examples
npm init -y
npm install --save-dev @clearideas/agent-runtime-cli
export OPENAI_API_KEY="..."

Use this model reference in the examples:

model:
  provider: openai
  model: gpt-5.6

Replace this model with a model profile or local model as needed.

Agent building blocks

Agent manifests combine these building blocks:

Building block	Manifest feature
Model calls	prompt steps
Run state	variables and outputVariable
Decisions	when conditions
Repetition	collection and goal loop steps
External capabilities	tools, approvals, webhooks, code, and sub-runs

Variables store run state

Variables are available to later steps, included in checkpoints, and restored when a run resumes.

Prompt chaining

Prompt chains pass one step's output to a later model call.

Draft
Create

→

Review
Evaluate

→

Revise
Finalize

schemaVersion: '1.0'
id: prompt-chain
name: Prompt chain

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: topic
    type: string
    value: durable agent execution

steps:
  - id: draft
    type: prompt
    systemPrompt: Write concise technical explanations.
    prompt: Explain {{ topic }}.
    outputVariable: articleDraft

  - id: review
    type: prompt
    systemPrompt: Identify unsupported claims and unclear language.
    prompt: |-
      Review this draft:

      {{ articleDraft }}
    outputVariable: articleReview

  - id: revise
    type: prompt
    prompt: >-
      Revise the draft using the review.

      Draft: {{ articleDraft }}

      Review: {{ articleReview }}
    outputVariable: articleFinal
    includeInFinalOutput: true

Save the example as prompt-chain.agent.yaml, then run it:

npx agent-runtime run \
  ./prompt-chain.agent.yaml \
  --stream

Each completed step updates state and creates a checkpoint.

Conditional routing

Conditions select steps using the current variable state.

Classify

→

Question
or request or feedback

→

Result

schemaVersion: '1.0'
id: conditional-routing
name: Conditional routing

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: input
    type: string
    value: How does checkpoint recovery prevent duplicate execution?

steps:
  - id: classify
    type: prompt
    prompt: |-
      Classify this input:

      {{ input }}
    outputSchema:
      type: object
      additionalProperties: false
      required: [route]
      properties:
        route:
          type: string
          enum: [question, request, feedback]
    outputVariable: classification

  - id: answer-question
    type: prompt
    when: classification.route == "question"
    prompt: |-
      Answer the question accurately:

      {{ input }}
    includeInFinalOutput: true

  - id: handle-request
    type: prompt
    when: classification.route == "request"
    prompt: |-
      Respond to this request with clear next steps:

      {{ input }}
    includeInFinalOutput: true

  - id: acknowledge-feedback
    type: prompt
    when: classification.route == "feedback"
    prompt: |-
      Acknowledge this feedback and summarize it:

      {{ input }}
    includeInFinalOutput: true

Skipped branches still advance the checkpoint. Completed steps marked includeInFinalOutput contribute to the final output.

Collection loops

Collection loops apply the same child steps to each item in an array or delimited string.

Items

→

One item
Sequential child steps

→

Results

schemaVersion: '1.0'
id: collection-loop
name: Collection loop

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: items
    type: array
    value:
      - Checkpoint after every committed step
      - Fence stale resume attempts
      - Stream ordered lifecycle events

steps:
  - id: summarize-items
    type: loop
    outputVariable: summaries
    includeInFinalOutput: true
    loop:
      source: items
      itemVariable: current
      indexVariable: index
      outputMode: array
      maxIterations: 20
    steps:
      - id: summarize
        type: prompt
        prompt: |-
          Summarize item {{ index }} in one sentence:

          {{ current }}

Nested progress is checkpointed. Recovery resumes after the last committed child instead of repeating the full loop.

Evaluator-optimizer loops

An evaluator-optimizer loop generates a candidate, evaluates it as structured data, and stops when the goal expression becomes true.

Generate

→

Evaluate

↺

Goal met

schemaVersion: '1.0'
id: evaluator-optimizer
name: Evaluator optimizer

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: topic
    type: string
    value: attempt fencing
  - key: review
    type: object
    value:
      feedback: No prior review.

steps:
  - id: refine
    type: loop
    includeInFinalOutput: true
    loop:
      goal: review.approved == true
      maxIterations: 4
      outputMode: final
      resultVariable: candidate
    steps:
      - id: improve
        type: prompt
        prompt: >-
          Produce the best concise explanation of {{ topic }}.
          Address this prior review: {{ review.feedback }}
        outputVariable: candidate

      - id: evaluate
        type: prompt
        prompt: |-
          Evaluate this explanation:

          {{ candidate }}
        outputSchema:
          type: object
          additionalProperties: false
          required: [approved, feedback]
          properties:
            approved:
              type: boolean
            feedback:
              type: string
        outputVariable: review

Set maxIterations to bound the loop when the goal condition is not reached.

Tool-using agents

Tools let a model retrieve data or perform host-authorized actions.

Model

→

Tool call

→

Tool result

→

Model

Bind a host connection and declare the question used by the prompt:

schemaVersion: '1.0'
id: tool-agent
name: Tool-using agent

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: question
    type: string
    value: Which documents describe checkpoint recovery?

connections:
  - ref: documents
    alias: docs
    mode: read
    tools: [search, read]

steps:
  - id: answer
    type: prompt
    systemPrompt: Use connected documents. Do not invent missing facts.
    prompt: Answer {{ question }}.
    tools: [docs__search, docs__read]
    outputVariable: answer
    includeInFinalOutput: true

The agent manifest can narrow a connection but cannot add tools or elevate its configured access. Tool calls execute in model order. See Connections and tools.

Human approval

An approval step delegates the decision to the host's ApprovalAdapter.

schemaVersion: '1.0'
id: approval
name: Approval flow

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: request
    type: string
    value: Explain the planned release to customers.

steps:
  - id: prepare
    type: prompt
    prompt: Prepare the proposed response to {{ request }}.
    outputVariable: proposal

  - id: approve
    type: approval
    prompt: Approve the proposed response?
    action: pause

  - id: finalize
    type: prompt
    prompt: |-
      Return the approved proposal:

      {{ proposal }}
    outputVariable: response
    includeInFinalOutput: true

The adapter can resolve immediately or suspend the run and release compute. Resume continues from the durable checkpoint.

Step scheduling

Agent runs are sequential by default. Set execution.mode: parallel in the agent run manifest to fan out adjacent prompt steps that do not depend on one another:

execution:
  mode: parallel
  maxConcurrency: 4

Dependencies come from outputVariable writes and variable references in prompt templates, system prompts, and when conditions. A consumer waits for its producer, while independent prompts can share one execution wave. Results, state patches, transcript items, artifacts, and final outputs commit in manifest order.

Tool-enabled prompts and stateful step types are execution barriers. Loops and tool calls remain sequential.

Next steps

• Learn manifest behavior in the Manifest guide.
• See every supported field in the Contract reference.
• Configure hosted and local models in Models and providers.
• Stream updates to an interface with Events and streaming.
• Add Agent Runtime to an application with Embed Agent Runtime.