diff --git a/AGENTS.md b/AGENTS.md index b3d13d1466..a06bc3676f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CONTEXT.md b/CONTEXT.md index 054960607c..ed3ebd9010 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -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**: diff --git a/docs/reusable-ai-agents.md b/docs/reusable-ai-agents.md index 3d3163470f..83b8b48800 100644 --- a/docs/reusable-ai-agents.md +++ b/docs/reusable-ai-agents.md @@ -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:`), 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 `.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