Agents ====== Agent components use an LLM to reason and act. They range from general-purpose autonomous agents to specialised routing and delivery agents. ---- .. _component-ref-agent: Agent ----- A general-purpose autonomous agent that uses an LLM with tools and knowledge bases to reason and act over multiple steps. **Use in a flow** 1. Add an **Agent** node to the canvas. 2. Select **Model Provider** and **Model ID**. 3. Write **Agent Instructions** (system prompt). 4. Optionally connect **Tools**, select a **Knowledge Base**, and wire **Input** from **Input** or upstream components. 5. Connect **Selected Output** to **Output** or the next step. .. code-block:: text Input ──► Agent ◄── Tools / MCP Client Knowledge Base (dropdown) ──► Agent Agent (Selected Output) ──► Output The agent can call connected tools, retrieve knowledge base context, use memory, and run guardrails before returning a response. **Parameters — Model and instructions** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Model Provider - — - No - LLM provider for the agent. * - Model ID - — - No - Model to use. Refresh to load available models. * - Region Name - — - No - Region where the selected model is available. * - Agent Instructions - — - No - System prompt that guides agent behavior. * - Input - — - No - User message or task for the agent to process. **Parameters — Tools and knowledge** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Tools - — - No - Connected tool components the agent can call. * - Knowledge Base - — - No - Optional knowledge base for retrieval-augmented responses. Refresh to load options. * - Fallback Knowledge Base - — - Yes - KB used when the user lacks access to the primary KB. * - Assume Policy - — - No - Access policy limiting which resources this agent can use. **Parameters — Memory and behavior** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - STM Retrieval Limit - 10 - Yes - Recent conversation turns from short-term memory. * - LTM Retrieval Limit - 10 - Yes - Records from long-term memory via semantic search. * - User Level LTM - false - Yes - Scope long-term memory per user instead of shared agent namespace. * - Current Date - false - Yes - Add a tool that returns the current date. * - Max Iterations - 15 - Yes - Maximum reasoning steps before the agent stops. * - Handle Parse Errors - true - Yes - Recover from input parsing errors. * - Verbose - true - Yes - Detailed agent logging during execution. **Parameters — Delivery and personalization** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Enable File Deliverables - false - No - Let the agent register files for delivery to channels. * - Enable Channel Delivery - false - No - Inform the agent that a downstream Channel Agent handles outbound delivery. * - Post-HITL Instructions - — - Yes - Custom instructions after Human In The Loop approval. * - Enable Personalization - false - No - Inject user personalization preferences into the prompt. **Parameters — Structured output** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Enable Structured Output - false - No - Return JSON matching a defined schema. * - Output Schema - — - No - Table of field names, types, and descriptions. Appears when structured output is enabled. * - Output Field - response - No - Which field to expose on **Selected Output** when structured output is enabled. * - Schema Name - OutputModel - Yes - Name for the output schema model. * - Format Instructions - — - Yes - Instructions for formatting structured output. **Parameters — Guardrails** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Enable Input Guardrail - false - No - Validate input before agent execution. * - Input Guardrails - — - Yes - Guardrails to apply on input. Appears when enabled. * - Enable Output Guardrail - false - No - Validate agent output after execution. * - Output Guardrails - — - Yes - Guardrails to apply on output. Appears when enabled. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Selected Output - Agent response message, or a specific structured output field. * - Language Model - The built language model instance (for wiring to other components). **Limitations** - **Model required** — A model must be selected before the agent can run. - **Tool mode** — When used as a tool by another agent, the deprecated **Agent Description** applies. - **Knowledge base** — Retrieval uses the selected KB's embedding model and search settings internally. ---- .. _component-ref-intent-classification-agent: Intent Classification Agent *(Beta)* ------------------------------------- Classifies the user's intent and returns a structured output with the classified category. **Use in a flow** 1. Add an **Intent Classification Agent (Beta)** node to the canvas. 2. Select **Model Provider** and **Model ID**. 3. Define **Agent Instructions** and an **Output Schema** (for example, an ``intent`` string field). 4. Connect **Input** from **Input** or an upstream message. 5. Connect **Structured Output** downstream (for example, a conditional router or **Agent**). .. code-block:: text Input ──► Intent Classification Agent ──► Router / Agent **Parameters** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Model Provider - — - No - LLM provider for classification. * - Model ID - — - No - Model to use. * - Region Name - — - No - Region where the model is available. * - Agent Instructions - helpful classifier prompt - No - System prompt guiding intent classification. * - Input - — - No - User query to classify. * - Output Schema - intent field - No - Fields to return (name, description, type). * - Output Field - structured_output - No - ``structured_output`` for full JSON, or a specific schema field name. * - Enable Streaming - false - No - Run classification in streaming mode. * - Schema Name - — - Yes - Name for the output schema model. * - Model Kwargs - — - Yes - Extra keyword arguments for the model. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Structured Output - Classified intent as a message. Returns full JSON or a single field value based on **Output Field**. **Limitations** - **Beta** — Behavior may change. - **Schema required** — **Output Schema** must define at least one field. - **Structured output** — Uses native structured output when the model supports it; otherwise falls back to prompt-based parsing. ---- .. _component-ref-human-in-the-loop: Human In The Loop *(Beta)* --------------------------- Pauses the flow and sends an approval request to configured delivery targets. The flow resumes once approved or rejected. **Use in a flow** 1. Add a **Human In The Loop (Beta)** node after an upstream **Agent** (or any component that produces a bot response). 2. Wire **User Query** and **Bot Response** from upstream steps. 3. Configure **Approval Delivery Targets** (channel, recipient, event type). 4. Connect **Response** downstream. .. code-block:: text Input ──► Agent ──► Human In The Loop ──► Channel Agent / Output On first run, the component sends an approval card to the configured channels and pauses execution. When a human approves or rejects, the flow resumes with the action result. **Parameters** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - User Query - — - No - Original user message for approval context. * - Bot Response - — - No - Generated answer included in the approval request. Required. * - Approval Title - Action Required - No - Title on the approval card. * - Approval Description - default text - No - Description explaining what needs approval. * - Approval Delivery Targets - — - No - Where to send approval requests (channel, event type, recipient). Refresh to load routes. * - Send Reply to Original Channel - true - No - Send confirmation back to the incoming channel after dispatching the approval. * - Attach Incoming Files - false - No - Attach session-uploaded files to the approval card. * - Post-Approval Instructions - — - No - Custom instructions injected into the main agent after approval. * - Timeout (seconds) - 86400 - Yes - Maximum wait time for approval. * - Auto-reject on Timeout - false - Yes - Reject automatically when timeout is reached. * - Context Data (JSON) - {} - Yes - Extra context shown on the approval card. * - Assume Policy - — - No - Access policy for channel and resource access. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Response - On pause: JSON with ``awaiting_approval`` status. On resume: approval or rejection message. **Limitations** - **Beta** — Behavior may change. - **Delivery targets required** — At least one complete row in **Approval Delivery Targets** (channel, event type, recipient). - **Flow pause** — Execution stops until a human responds or timeout occurs. - **Event type** — Approval targets use the ``hitl_approval`` event type automatically. ---- .. _component-ref-channel-agent: Channel Agent *(Beta)* ----------------------- An agent wired to a communication channel. Handles inbound messages and routes outbound replies to configured delivery targets. **Use in a flow** 1. Add a **Channel Agent (Beta)** node after an upstream **Agent** that generates the message content. 2. Wire **User Query** and **Bot Response**. 3. Configure **Outbound Routes** or **Delivery Targets**. 4. Connect **Response** downstream. .. code-block:: text Input ──► Agent ──► Channel Agent ──► Output The Channel Agent resolves the correct channel and recipient from the user query and delivers the bot response. Fully configured delivery targets are sent automatically; partial rows are resolved by the LLM at runtime. **Parameters** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - User Query - — - No - Original user query — used to determine channel, recipient, and event type. * - Bot Response - — - No - Content from an upstream agent to deliver. Required. * - Model Provider - — - No - LLM provider for routing decisions. * - Model ID - — - No - Model used to resolve delivery targets. * - Agent Instructions - auto - No - Base system prompt. ``auto`` generates routing instructions from configured routes. * - Additional Instructions - — - No - Extra routing or delivery overrides appended to the prompt. * - Outbound Routes - — - No - Channels this agent can deliver to. Refresh to load routes. * - Delivery Targets - — - No - Table of outbound targets (channel, event type, recipient, invocation). Empty fields are resolved by the LLM. * - Send Reply to Original Channel - true - No - Send confirmation back to the incoming channel after delivery. * - Max Iterations - 10 - Yes - Maximum agent reasoning steps. * - Handle Parsing Errors - true - Yes - Recover from tool parsing errors. * - Verbose - false - Yes - Detailed agent logging. * - Model Kwargs - — - Yes - Extra keyword arguments for the model. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Response - Delivery result message from the channel agent. **Limitations** - **Beta** — Behavior may change. - **Routes required** — At least one **Outbound Route** or **Delivery Target** must be configured. - **Bot response required** — Upstream content must be wired to **Bot Response**. - **Automatic targets** — Targets marked automatic must have channel, event type, and recipient fully configured. ---- .. _component-ref-flow-agent: Flow Agent ---------- Calls another Agentic Flow as a sub-flow and returns its output into the current flow. **Use in a flow** 1. Add a **Flow Agent** node to the canvas. 2. Select **Workspace** and **Flow Agent** (refresh to load options). 3. Wire **Input** from an upstream message or component. 4. Optionally set **Tweaks** to override sub-flow parameters. 5. Connect **Response** or **Full Response** downstream. .. code-block:: text Input ──► Flow Agent ──► Output / Agent Agent ──► Flow Agent (as a tool) **Parameters** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Input - — - No - Input message or data for the sub-flow. * - Workspace - — - No - Workspace containing the target flow. Refresh to load. * - Flow Agent - — - No - Agentic flow to execute. Refresh after selecting a workspace. * - Conversation history - — - No - Optional conversation history passed to the sub-flow. * - Session ID - — - No - Session ID for conversation continuity. * - Output Component - — - No - Specific output component to retrieve from the sub-flow. * - Tweaks - — - No - Key-value parameter overrides for the sub-flow. Auto-populated from the selected flow. * - Enable Retry - — - Yes - Retry failed API requests. * - Max Retries - — - Yes - Maximum retry attempts. * - Save Output as Variable - — - Yes - Store output as a named flow variable. * - Variable Name - — - No - Name for the flow state variable. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Response - Main text output from the sub-flow execution. * - Full Response - Complete API response including metadata and all output data. **Limitations** - **Workspace and flow required** — Both must be selected before execution. - **Authorization** — Runs using the flow's authorization context; sub-flow must be accessible to the caller. - **Session continuity** — Pass **Session ID** to maintain conversation context across parent and child flows. - **Tweaks** — Values support ``{{variable}}`` placeholders resolved from flow context. ---- .. _component-ref-voice-agent-call: Voice Agent Call ---------------- Triggers a Voice Agent call and returns the call response. **Use in a flow** 1. Add a **Voice Agent Call** node to the canvas. 2. Select **Workspace** and **Voice Agent** (refresh to load options). 3. Fill in **Call Parameters** (auto-populated when a voice agent is selected). 4. Connect **Call Response** or **Status** downstream. .. code-block:: text Flow trigger ──► Voice Agent Call ──► Output / Agent **Parameters** .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Workspace - — - No - Workspace containing the voice agent. Refresh to load. * - Voice Agent - — - No - Voice agent to trigger. Refresh after selecting a workspace. * - Call Parameters - — - No - Parameter table auto-populated from the selected voice agent. Fill in values for each parameter. * - Enable Retry - — - Yes - Retry failed API requests. * - Max Retries - — - Yes - Maximum retry attempts. * - Save Output as Variable - — - Yes - Store output as a named flow variable. * - Variable Name - — - No - Name for the flow state variable. **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Call Response - API response from the voice call (result, status code, raw data). * - Status - HTTP status code from the last call attempt. **Limitations** - **Workspace and voice agent required** — Both must be selected before triggering a call. - **Call parameters** — Required parameters depend on the selected voice agent configuration. - **Authorization** — Requires valid authorization to call the voice backend service. ---- .. _component-ref-break-agent: Break Agent ----------- Immediately terminates the current flow execution with an optional break reason and instruction. **Use in a flow** 1. Add a **Break Agent** node where you want to pause execution after processing. 2. Configure it like a standard **Agent** (model, instructions, tools, input). 3. Optionally set **Break Instruction** and **Break Reason**. 4. Connect **Selected Output** to **Output** so the response is delivered before the pause. .. code-block:: text Input ──► Agent steps ──► Break Agent ──► Output The agent processes the input, streams the response downstream, then pauses the flow. On resume, it runs as a normal agent without breaking again. **Parameters** Break Agent includes all :ref:`Agent ` parameters plus the following: .. list-table:: :widths: 30 10 10 50 :header-rows: 1 * - Parameter - Default - Hidden - Description * - Break Instruction - execution state summary prompt - No - Instruction injected when breaking. The agent summarizes execution state. * - Should Break - true - Yes - When ``false``, behaves like a normal Agent without pausing. * - Break Reason - agent_break - Yes - Reason logged for the break (for debugging). **Outputs** .. list-table:: :widths: 25 75 :header-rows: 1 * - Output - Description * - Selected Output - Agent response message before the break is set. **Limitations** - **Pause after response** — The response is sent to downstream components before execution pauses. - **Resume behavior** — On resume (``is_resume`` in flow context), the agent does not break again. - **Execution ID** — Flow can be resumed later using the execution ID stored in flow context. - **Should Break off** — Set **Should Break** to ``false`` to use as a standard Agent without pausing.