mirror of
https://github.com/tiennm99/DocsGPT.git
synced 2026-10-13 08:15:43 +00:00
Alex
23e249fca1
Workflows ship two expression languages in adjacent fields. Agent
`prompt_template` and end `output_template` are Jinja2, so `{{query}}` is
correct there. State and condition `expression` fields are bare CEL,
where the same string is a parse error.
Nothing told users this. docs/content/Agents/nodes.mdx documented the
pre-CEL Set State node with `{{variable_name}}` examples and Set /
Increment / Append operations that no longer exist — "CEL" appeared
nowhere in the docs. The builder's own placeholder was `input.foo + 1`,
referencing an `input` namespace that is not in workflow state, while the
panel beside it advertised `{{ agent.variable }}`.
There was also no validation anywhere: neither validateWorkflow nor
validate_workflow_structure looked at state nodes at all, and conditions
were only checked for a non-empty string. A workflow containing
`{{query}}` saved and published clean, then aborted on the first message
with a bare caret dump that sanitize_api_error collapsed into "An error
occurred … please try again later" — advice that sends the user round the
same loop, which is what the 2026-08-01 report shows.
Adds validate_cel_expression (compile-only, since state is built at run
time and unresolved names are not knowable when saving) and wires it into
the workflow save path for both node types, plus the half-configured
state operations the engine silently skips. `{{ }}` gets a targeted hint,
raised only after compilation has already failed so valid CEL that
contains braces — `x == "{{y}}"`, or a nested map literal — is not
rejected.
celpy errors are now summarized: undeclared-reference messages embed a
repr of the entire activation, thousands of characters including the
user's own query, and others interpolate the offending state value.
Quoted fragments that are not bare identifiers are redacted, since
config errors now bypass sanitize_api_error to reach the user, and a
shared agent's runner is not its owner.
Docs rewritten with a table of which field takes which syntax, CEL
examples for Set State, and the Condition node section that basics.mdx
has been linking to all along.
147 lines
6.6 KiB
Plaintext
147 lines
6.6 KiB
Plaintext
# Workflow Nodes
|
|
|
|
DocsGPT workflows are composed of **Nodes** that are connected to form a processing graph. These nodes interact with a **Shared State**—a global dictionary of variables that persists throughout the execution of the workflow.
|
|
|
|
## The Shared State
|
|
|
|
Every workflow run maintains a state object (a JSON-like dictionary).
|
|
- **Initial State**: Contains the user's input query (`query`) and chat history (`chat_history`).
|
|
- **Modifying State**: Nodes read from this state and write their outputs back to it.
|
|
- **Node Outputs**: Each node writes its result to `node_<node_id>_output`.
|
|
|
|
### Two ways to reference state
|
|
|
|
Which syntax a field takes depends on the field, so check this table before
|
|
typing `{{ }}` anywhere:
|
|
|
|
| Field | Node | Syntax |
|
|
| --- | --- | --- |
|
|
| Prompt Template | AI Agent | Template — `{{variable_name}}` |
|
|
| Output Template | End | Template — `{{variable_name}}` |
|
|
| Expression | Set State | [CEL](https://cel.dev/) — bare `variable_name` |
|
|
| Expression | Condition | [CEL](https://cel.dev/) — bare `variable_name` |
|
|
|
|
**Template fields** substitute `{{variable_name}}` into surrounding text, so
|
|
`Analysis: {{analysis_result}}` produces a string.
|
|
|
|
**Expression fields** are evaluated as [Common Expression
|
|
Language](https://cel.dev/), where a bare name *is* the variable. Write
|
|
`query`, not `{{query}}` — the braces are a syntax error there, and saving a
|
|
workflow that contains one is rejected with the correction.
|
|
|
|
---
|
|
|
|
## AI Agent Node
|
|
|
|
The **AI Agent Node** is the core processing unit. It uses a Large Language Model (LLM) to generate text, answer questions, or perform tasks using tools.
|
|
|
|
### Inputs (Template Variables)
|
|
|
|
The primary input is the **Prompt Template**. This field supports variable substitution.
|
|
|
|
- **Prompt Template**: The text sent to the model.
|
|
- *Example*: `"Summarize the following text: {{user_input_text}}"`
|
|
- If left empty, it defaults to the initial user query (`{{query}}`).
|
|
- **System Prompt**: Instructions that define the agent's persona and constraints.
|
|
- **Tools**: A list of tools the agent can use (e.g., search, calculator).
|
|
- **LLM Settings**: Specific provider, model name, and parameters.
|
|
|
|
### Outputs (Emissions)
|
|
|
|
When the agent completes its task, it stores the result in the shared state.
|
|
|
|
- **Output Variable**: The name of the variable where the result will be saved.
|
|
- *Default*: If not specified, it is saved as `node_{node_id}_output`.
|
|
- *Custom*: You can set this to something meaningful, like `summary` or `translated_text`.
|
|
- **Streaming**: If "Stream to user" is enabled, the output is sent to the user in real-time as it is generated, in addition to being saved to the state.
|
|
|
|
### Documents
|
|
|
|
An agent node can receive documents as inputs. Choose which documents the node sees:
|
|
|
|
- **All**: every document attached to the run.
|
|
- **None**: no documents.
|
|
- **Choose**: a specific set that you select.
|
|
|
|
For how a chosen document reaches the model, the node can pass it natively (send the file to a model that accepts files) or extract it to text first. The default picks automatically based on the model and the file type.
|
|
|
|
---
|
|
|
|
## Set State Node
|
|
|
|
The **Set State Node** allows you to manipulate variables within the shared state directly without calling an LLM. This is useful for initialization, formatting, or control flow logic.
|
|
|
|
### Operations
|
|
|
|
You can define multiple operations in a single node. Each operation has two
|
|
parts:
|
|
|
|
- **Target Variable**: the state key to write to.
|
|
- **Expression**: a [CEL](https://cel.dev/) expression evaluated against the
|
|
current state. Its result becomes the variable's value.
|
|
|
|
Reference state variables by bare name. `{{ }}` is template syntax and does
|
|
**not** work here — an operation must supply both parts, or it is rejected
|
|
when you save.
|
|
|
|
| Goal | Target Variable | Expression |
|
|
| --- | --- | --- |
|
|
| Initialize a counter | `retry_count` | `0` |
|
|
| Increment a counter | `retry_count` | `retry_count + 1` |
|
|
| Copy a node's output to a stable name | `context` | `node_search_1_output` |
|
|
| Build a string | `formatted_response` | `"Analysis: " + analysis_result` |
|
|
| Append to a list | `history_list` | `history_list + [last_result]` |
|
|
| Derive a boolean | `needs_review` | `size(context) < 100` |
|
|
|
|
CEL supports arithmetic, string concatenation with `+`, comparisons,
|
|
`&&`/`||`, ternaries (`cond ? a : b`), and built-ins such as `size()`,
|
|
`startsWith()`, and `contains()`.
|
|
|
|
### Usage Examples
|
|
|
|
- **Loop Counters**: Initialize `retry_count` to `0` before a loop, then set it
|
|
to `retry_count + 1` inside the loop.
|
|
- **Accumulators**: Collect results across branches with
|
|
`history_list + [last_result]`.
|
|
- **Renaming**: Copy a previous node's output to a generic name (target
|
|
`context`, expression `node_search_1_output`) so later nodes can use one
|
|
standard variable.
|
|
|
|
---
|
|
|
|
## Condition Node
|
|
|
|
The **Condition Node** branches the workflow. Each case pairs a
|
|
[CEL](https://cel.dev/) **Expression** with an outgoing branch; the first case
|
|
whose expression is true wins, and execution follows that branch.
|
|
|
|
- Expressions use the same syntax as the Set State node: reference state by
|
|
bare name, not `{{ }}`.
|
|
- Every condition node needs an **else** branch, which is taken when no case
|
|
matches.
|
|
- Each case with an expression must have an outgoing edge, and every branch
|
|
must eventually reach an end node.
|
|
|
|
| Goal | Expression |
|
|
| --- | --- |
|
|
| Route on a previous answer | `node_classify_1_output == "refund"` |
|
|
| Guard on retrieved context | `size(context) > 0` |
|
|
| Combine checks | `needs_review && retry_count < 3` |
|
|
| Match text | `query.contains("invoice")` |
|
|
|
|
A case whose expression fails to evaluate at run time is skipped and the next
|
|
case is tried, so a workflow that always lands on **else** usually means an
|
|
expression is referencing a variable that no earlier node writes.
|
|
|
|
---
|
|
|
|
## Code Node
|
|
|
|
The **Code Node** runs a script in a sandboxed session bound to the workflow run. Use it to transform data, parse files, cross-check documents, or build a report that later nodes consume.
|
|
|
|
- **Code**: the script to run. The workflow state is available to the script as data, so it can read variables, compute, and write results back.
|
|
- **Inputs**: documents or artifacts to place in the workspace before the script runs. Each input accepts a produced artifact reference, a full artifact id, or an attached file.
|
|
- **Outputs**: any files the script writes are captured as artifacts and surfaced in the run view. Write a small JSON value back to the state to pass a decision or summary to later nodes.
|
|
|
|
Runs are sandboxed and have a fixed time limit, so keep each step focused. See [Artifacts and Code Execution](/Tools/artifacts-and-code-execution) for the sandbox backends and configuration.
|