LLM Overview

Call a model from a step with action: chat.completion, and go further from there: let the completion call workflows as functions, let a model decide which step runs next, run a full coding agent as a step, or let an external AI operate Dagu.

Where a model fits

• A model call inside a step: action: chat.completion sends a prompt or message list; the response streams to stdout. This page.
• Workflows as functions: a completion with tools can call your DAGs, with arguments derived from their params. See Tool Calling.
• A model deciding what runs: type: agent inverts control; steps become a catalog and the model picks one or more independent actions per turn until the goals are met. See Agent DAGs and the Agent DAG examples.
• Typed answers instead of prose: action: decision.evaluate asks a model several questions about the same material and returns a selected option, a score, or a probability, each with its own confidence. See Decision Steps.
• A coding agent as a step: harness.run launches supported coding-agent CLIs such as Claude Code, Codex, Gemini CLI, Cursor, or DeepSeek Harness inside a workflow. See Harness.
• AI operating Dagu: the MCP server is the inverse relationship; an external AI client inspects workflows, starts runs, and reads results.

The examples below run as-is with an OPENROUTER_API_KEY exported; swap the llm block for any configured provider.

First completion

secrets:
  - name: OPENROUTER_API_KEY
    provider: env
    key: OPENROUTER_API_KEY

llm:
  provider: openrouter
  model: deepseek/deepseek-v4-flash

steps:
  - id: ask
    action: chat.completion
    with:
      prompt: |
        What is 2+2? Reply with just the number.
    output: ANSWER

  - id: use_answer
    run: echo "The model said ${ANSWER}"
    depends: ask

Three things carry this example:

• The secrets entry reads the key from the Dagu process environment and masks it in logs. Exporting the variable alone is not enough, because only a small set of environment variables passes through to workflows.
• The DAG-level llm block is inherited by every chat step that sets no LLM fields of its own, so steps stay small.
• output: ANSWER captures the response for any dependent step as ${ANSWER}. Object-form output namespaces it to the step instead (response: { from: stdout }, read as ${ask.output.response}), and a large response can stream straight to an artifact.

Messages and system prompts

Use messages when the request needs an explicit conversation, and system to set the role:

steps:
  - id: diagnose
    action: chat.completion
    with:
      provider: openrouter
      model: deepseek/deepseek-v4-flash
      system: |
        Answer as a concise operations runbook author.
      messages:
        - role: user
          content: |
            Explain how to diagnose a saturated connection pool.
            Keep it under 80 words.

Specify either prompt or messages; prompt is converted to one user message and takes precedence when both are present. Roles can be system, user, or assistant.

Note the explicit provider and model here: when an action sets any LLM field under with (even just system), its configuration replaces the complete DAG-level llm block rather than merging with it.

What a completion can do

Each capability below is one field away. Snippets show the shape; the AI examples page has full runnable versions of each.

Multi-turn sessions. Chat steps inherit the conversation from the steps they depend on:

  - id: follow_up
    action: chat.completion
    with:
      prompt: Multiply that by 3.
    depends: ask

See Sessions.

Call workflows as tools. Names in tools expose DAGs as functions; each call is a real child run:

    with:
      tools:
        - calculator
      prompt: What is 15 times 23? Use the calculator tool.

See Tool Calling.

Typed answers. A step-level output_schema makes the model answer in that shape, and each listed property becomes a step output:

  - id: classify
    action: chat.completion
    with:
      prompt: "Classify this note: ${params.note}"
    output_schema:
      type: object
      properties:
        category: {type: string, enum: [refund, complaint, question]}
      required: [category]

See Structured output.

Route on the answer. Ask for a label, then branch with router.route:

  - id: route_request
    depends: [classify_request]
    action: router.route
    with:
      value: ${REQUEST_TYPE}
      routes:
        bug: [handle_bug]
        feature: [handle_feature]

Constrain the model to known labels and keep an explicit fallback route; a response that matches no route runs no handler. See Router.

When the answer is a label rather than prose, decision.evaluate does this without the hand-constraining: the options are declared as criteria, the answer is always one of them, and it comes back with a confidence you can gate on with a numeric comparison.

Extended reasoning. thinking maps to the provider's reasoning controls:

    with:
      thinking:
        enabled: true
        effort: low

See Reasoning.

Model fallback. An ordered model list tries the next entry after retries are exhausted:

    with:
      model:
        - provider: openrouter
          name: deepseek/deepseek-v4
        - provider: openrouter
          name: deepseek/deepseek-v4-flash

See Reliability.

Web search. Provider-integrated search grounds the answer in current results:

    with:
      web_search:
        enabled: true
        max_uses: 3

See Web Search.

Structured output

Set output_schema on the step, next to with, when later steps need values rather than prose:

steps:
  - id: classify
    action: chat.completion
    with:
      prompt: |
        Classify this customer note and extract the amount:
        I was charged twice, please refund the extra 12.50 EUR.
    output_schema:
      type: object
      properties:
        category:
          type: string
          enum: [refund, complaint, question]
        amount:
          type: number
        currency:
          type: string
      required: [category]

  - id: record
    depends: classify
    run: echo "${steps.classify.outputs.category} ${steps.classify.outputs.amount}"

• The model answers by calling a respond tool whose parameters are the schema, and the request requires a tool call. A reply that is a JSON object in plain text is accepted too.
• Properties the schema does not list are dropped, and the rest is validated against the schema. Stdout is one JSON object, and each listed property becomes ${steps.<id>.outputs.<name>}. Referencing a name the schema does not list is reported as unknown when the DAG loads.
• An answer that does not match gets one correction, sent with the reason. If it still does not match, the next entry of a model list is tried. When no model answers, the step fails with the model gave no answer that matches output_schema; the step's stderr shows each rejected answer and why.
• The schema must declare type: object, list at least one property, and list every required name under properties. It cannot be combined with web_search or with a tool named respond.
• With tools, the tool workflows are offered next to respond, and the loop ends when the model calls respond. Reaching max_tool_iterations without an answer counts as that model failing: the next entry of a model list starts over, running the tools again, and the step fails when no model is left.
• The answer is never streamed.

Validation checks the shape of the answer, not whether it is true. For extraction, leave a field out of required when the input may not contain it: a required field makes the model invent a value rather than leave it out.

Some models refuse a forced tool call: Claude models while thinking is enabled, and Claude 5 models always. For those, Dagu asks for the tool without forcing it and relies on the instruction, the validation, and the correction.

Sessions

The completed session is saved with the DAG run, including the provider, model, and token usage reported for assistant messages. A chat step also inherits conversation history from the steps in its depends list, which is what makes the multi-turn pattern above work:

• History is transitive: every chat step saves its inherited messages, its own messages, and the response.
• Histories from multiple dependencies are merged in the order listed in depends.
• Only the first system message is kept when inherited histories contain several.
• Retries continue with the session already attached to the DAG run.

When approval push-back or human-task push-back re-executes a chat step, Dagu restores the previous conversation and appends the reviewer feedback as the next user message; the workflow does not need to wire ${FEEDBACK} itself.

Configuration

All action-specific fields belong under with, except output_schema, which sits on the step; see Structured output.

Field	Type	Default	Description
prompt	string	-	A non-empty user prompt. Required when messages is omitted.
messages	array	-	A non-empty list of {role, content} messages. Required when prompt is omitted.
provider	string	inherited	LLM provider. Required for a string model unless inherited; omit it when every fallback model entry has its own provider.
model	string or array	inherited	Model identifier, or an ordered list of model configurations for fallback. Inherited only when the action sets no LLM configuration fields.
system	string	-	Default system prompt. An explicit system message in messages takes precedence.
temperature	number	provider default	Sampling randomness from 0.0 to 2.0.
max_tokens	integer	provider default	Maximum number of tokens to generate.
top_p	number	provider default	Nucleus sampling value from 0.0 to 1.0.
base_url	string	provider default	Base URL for a custom or OpenAI-compatible endpoint.
api_key_name	string	provider default	Environment variable that contains the API key.
stream	boolean	true	Stream response tokens to stdout as they arrive.
thinking	object	disabled	Provider-specific extended reasoning.
tools	array	-	DAG names exposed to the model as callable tools.
max_tool_iterations	integer	10	Maximum tool-calling rounds.
web_search	object	disabled	Built-in web-search integration settings.

messages[].content, system, and base_url support scoped value references such as ${params.TOPIC} and ${env.LLM_BASE_URL}.

Security

Values registered as Dagu secrets are masked before messages are sent to the provider. The run's saved session retains the resolved message content, so avoid placing unnecessary secrets in prompts and restrict access to run history.

Next Steps

• AI Examples for runnable copy-paste versions of every capability above
• Providers & Endpoints for credentials, custom endpoints, and shared defaults
• Agent DAGs & Completions for the step-by-step path from one completion to LLM-directed workflows
• Agent DAGs when the order of the work is itself the model's decision
• Harness for running external coding agents as steps
• Chat & LLM for choosing between the shapes at a glance