docs: say saved ai agents also run on their own as a one-step flow (#12308)

* docs: say saved ai agents also run on their own as a one-step flow

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: agent runs drop saved history inputs on every run; the editor chat is a preview

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F4rzFpemqD4pqLnAp4qRqF

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
hugocasa
2026-11-10 18:19:42 +01:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 7ec64ab33a
commit f9a7972812
3 changed files with 28 additions and 2 deletions
+3
View File
@@ -53,6 +53,9 @@ Open-source platform for internal tools, workflows, API integrations, background
- **Operator builder rights**: `docs/operator-builder-rights.md` — the workspace settings that let
operators compose flows, AI agents and full-code apps, what the composition check must cover, which
raw-app endpoint stays closed on purpose, and why either right costs a full seat
- **AI agents**: `docs/reusable-ai-agents.md` — saved agents, linked from flow steps and also run
on their own (page, API, Slack, apps) as a one-step flow, so flow and chat-flow behaviour
reaches them too; memory, approvals and questions
- **Auth surface**: `docs/auth-surface.md` — credential precedence, session/cache invalidation
scope, which token labels email their owner at expiry, how OAuth login matches `login_type`, and
that every superadmin route refuses `$WM_TOKEN`. Read before designing anything that creates
+8 -2
View File
@@ -39,9 +39,15 @@ _Avoid_: JS field, code input
### Flow chat
**Agent**:
A saved AI agent: an `ai_agent` resource holding a model, prompt and tools. Flow steps link to
it, and it also runs on its own (its page, the API, Slack, apps) as a one-step flow, so it has
conversations of its own. See `docs/reusable-ai-agents.md`.
_Avoid_: bot, assistant
**Conversation**:
One thread of messages against one chat-enabled flow, with its own agent memory. A flow has
many; the chat shows one at a time.
One thread of messages against one chat-enabled flow or one agent, with its own agent memory.
Each has many; the chat shows one at a time.
_Avoid_: thread, session (that names an AI session, a different thing), chat (that names the surface)
**Turn**:
+17
View File
@@ -8,6 +8,23 @@ agent, and edits to the agent propagate to every linked step.
The `ai_agent` resource type is defined in the hub (windmill-integrations) and synced into
every workspace via the standard cached-resource-type sync, like other built-in types.
## Running an agent on its own
A saved agent also runs without any flow of the author's: from its deployed page, through
`POST /w/{workspace}/jobs/run/agent/{path}` (scope `jobs:run:agents:<path>`), from a Slack channel
it is shared in, from a full-code app, and from the AI session's run tools. All of them go through
`windmill-api/src/agent_runs.rs`, which reads the agent and runs it as a **one-step flow**
(`agent_step_flow`, step id `__wm_agent_root`). Every run drops the agent's saved `memory_id` and
`previous_messages` step inputs: the message, attachments and any `previous_messages` come from
the run's input. A run with a `memory_id` is a turn of a conversation, filed under `<path>.chat`
and run with chat input enabled. The agent editor's chat is different: it previews the draft as a
flow preview of the same one step (`agentChatFlow`), not through `agent_runs.rs`.
Since the run is a flow, everything written for flow runs and chat flows applies to it as well:
conversations, the running-turn check, approvals and questions. A change to one of those paths
must keep working for this one-step shape, and can be tested from the agent's deployed page as
well as from a flow.
## Rigid linking
`FlowModuleValue::AIAgent` has an optional `agent` field holding the resource path, plus a