# Enterprise Connections Source: https://docs.vectorshift.ai/account/organizations/enterprise-connections Connect your Organization to your existing enterprise authentication system ## Setting up SSO with Okta ### Part 1: Okta Setup Reference Documentation: [Link](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/okta#create-okta-workforce-enterprise-connection-in-auth0) 1. Sign into Okta and go to Admin console from top right. 2. Select Applications from the left and click on **Create an Application Integration**. 3. In the create application wizard, select: **OIDC** and **Web Application**. 4. Add [https://auth.vectorshift.ai/login/callback](https://auth.vectorshift.ai/login/callback) as the **login callback URI** and hit save. 5. Copy the **client ID** and **client secret** from the new window that opens up. Also copy the okta domain from the drop down on top right (may end with `.okta.com` or `.oktapreview.com`). 6. Go to Directory and assign the newly created Application to people/groups (Can also be done from Application page → Assignments). ### Part 2: VectorShift Setup 1. Go to your organization account with Enterprise permissions. 2. Click account from top-left and select Organization Overview. 3. Select Enterprise Connections and pull down Okta. 4. Paste Okta domain that we copied in Step 5 of Okta Setup. 5. Paste the client ID and secret copied at Step 5 of Okta Setup in the enterprise form. 6. Add email suffix in domain alias (example: vectorshift.ai). All logins from emails with this suffix will redirect to your Okta account for verification. In case there are more than one, add all entries separated by commas (no spaces in between) - example: `vectorshift1.ai`, `vectorshif2.ai`. 7. Hit save and you’re done. # Overview Source: https://docs.vectorshift.ai/account/organizations/overview Collaborate with your team in real-time with fine-grained access controls Organizations allow teams to share Workflows across more users and consolidate user management / billing. Relative to Personal accounts, Organizations receive the following features: * Zero data retention agreements with LLM model providers * Centralized billing and user licensing ## Create a new Organization To create a new Organization, take the following steps: 1. Click on the VectorShift logo in the top-left. 2. Hover over "Switch Organization", and click "Create Organization" at the bottom of the new dropdown menu. 3. Fill out the required fields and click "Create". The Organization Name will be used to identify users and workflows within the Organization, and the Display Name will be shown to users under the VectorShift logo at the top-left of the platform interface. ## Invite Users to your Organization 1. Click on the VectorShift logo in the top-left, and click "Manage Members". 2. Click the "+" button in the top-right corner of the Members section. 3. Enter the email addresses of the users you would like to invite, and click "Invite". ## Update Organization Settings 1. Click on the VectorShift logo in the top-left, and click "Organization Overview". 2. Make any changes as desired, and click "Save Changes". # Profile Source: https://docs.vectorshift.ai/account/profile Manage your personal account settings Your profile includes areas to view/update your username, update your picture and name, and create new Organizations. You can reach your profile by clicking on the VectorShift logo in the top-left and selecting "Profile" from the dropdown menu. Profile From this section, you can view/change some of the account details, including: * Username, required to make an API call to execute a workflow. The username is editable. * Name and Profile picture. * User ID, this ID is assigned to each account by default and cannot be changed. * Change Password. * Notifications, list of each workflow execution with status and timestamps. # Organization Subscriptions Source: https://docs.vectorshift.ai/account/subscriptions/organization Manage organization-level subscriptions and billing ## Manage your Organization Subscription 1. Click on the VectorShift logo in the top-left, and click "Profile". 2. Click on the "Subscription" tab on the left. # Overview Source: https://docs.vectorshift.ai/account/subscriptions/overview Enhance VectorShift's capabilities with a subscription Subscriptions come in two forms: Personal and Organization. You can learn more about VectorShift's Subscription plans on our [Pricing Page](https://www.vectorshift.ai/pricing). Manage your subscription for your personal account Manage organization-level subscriptions and billing # Personal Subscriptions Source: https://docs.vectorshift.ai/account/subscriptions/personal Manage your subscription for your personal account ## Manage your Personal Subscription 1. Click on the VectorShift logo in the top-left, and click "Profile". 2. Click on the "Subscription" tab on the left. # Create a new chatbot Source: https://docs.vectorshift.ai/api-reference/chatbots/create api-reference/chatbots/chatbot.json POST /chatbot # Delete a chatbot Source: https://docs.vectorshift.ai/api-reference/chatbots/delete api-reference/chatbots/chatbot.json DELETE /chatbot/{id} # Fetch an existing chatbot Source: https://docs.vectorshift.ai/api-reference/chatbots/fetch api-reference/chatbots/chatbot.json GET /chatbot # List all available chatbots Source: https://docs.vectorshift.ai/api-reference/chatbots/list api-reference/chatbots/chatbot.json GET /chatbots # Run a chatbot Source: https://docs.vectorshift.ai/api-reference/chatbots/run api-reference/chatbots/chatbot.json POST /chatbot/{id}/run # Terminate a chatbot session Source: https://docs.vectorshift.ai/api-reference/chatbots/terminate api-reference/chatbots/chatbot.json POST /chatbot/{id}/terminate # Upload files to a chatbot Source: https://docs.vectorshift.ai/api-reference/chatbots/upload api-reference/chatbots/chatbot.json POST /chatbot/{id}/upload # Create a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/create api-reference/knowledge-bases/knowledge_base.json POST /knowledge-base # Delete a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/delete api-reference/knowledge-bases/knowledge_base.json DELETE /knowledge-base/{id} # Delete documents from a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/delete-documents api-reference/knowledge-bases/knowledge_base.json DELETE /knowledge-base/{id}/documents # Fetch an existing knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/fetch api-reference/knowledge-bases/knowledge_base.json GET /knowledge-base # Find documents in a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/find-documents api-reference/knowledge-bases/knowledge_base.json GET /knowledge-base/{id}/documents # Add data to a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/index api-reference/knowledge-bases/knowledge_base.json POST /knowledge-base/{id}/index # List all available knowledge bases Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/list api-reference/knowledge-bases/knowledge_base.json GET /knowledge-bases # Query a knowledge base Source: https://docs.vectorshift.ai/api-reference/knowledge-bases/query api-reference/knowledge-bases/knowledge_base.json POST /knowledge-base/{id}/query # Overview Source: https://docs.vectorshift.ai/api-reference/overview Get started with the VectorShift API This API documentation is currently in beta and is primarily intended for developer preview. While the core functionality is stable, specific aspects including error codes, response formats, and endpoint behaviors may be refined or modified in future releases. We encourage developers to provide feedback, but recommend not using this version in production environments without understanding that breaking changes may occur. We will strive to communicate significant changes through our developer channels. ## API Keys You view your API keys and generate new ones by navigating to the API Keys page in your settings. To access this page: 1. Click on the VectorShift logo in the top-left corner of the page, and click "Profile". 2. Click the "API Keys" tab on the left. Here, you can view your existing API keys, and you can generate new ones by clicking the "+" button in the top-right corner of the section. ## Endpoints Run and manage your pipelines programmatically Create, update, and manage data in your knowledge bases Interact with your chatbots directly, without the need for a UI Run arbitrary code in VectorShift's isolated execution environment # Run a pipeline in bulk Source: https://docs.vectorshift.ai/api-reference/pipelines/bulk-run api-reference/pipelines/pipeline.json POST /pipeline/{id}/bulk_run Execute multiple instances of the same pipeline in parallel # Create a new pipeline Source: https://docs.vectorshift.ai/api-reference/pipelines/create api-reference/pipelines/pipeline.json POST /pipeline Create a new pipeline with the specified configuration # Delete a pipeline Source: https://docs.vectorshift.ai/api-reference/pipelines/delete api-reference/pipelines/pipeline.json DELETE /pipeline/{id} Delete a pipeline by ID # Fetch an existing pipeline Source: https://docs.vectorshift.ai/api-reference/pipelines/fetch api-reference/pipelines/pipeline.json GET /pipeline Retrieve a pipeline by ID or name # List all available pipelines Source: https://docs.vectorshift.ai/api-reference/pipelines/list api-reference/pipelines/pipeline.json GET /pipelines # Pause a pipeline run Source: https://docs.vectorshift.ai/api-reference/pipelines/pause api-reference/pipelines/pipeline.json POST /pipeline/{id}/pause Pause a currently running pipeline instance # Resume a paused pipeline run Source: https://docs.vectorshift.ai/api-reference/pipelines/resume api-reference/pipelines/pipeline.json POST /pipeline/{id}/resume Resume one or more paused pipeline instances # Run a pipeline Source: https://docs.vectorshift.ai/api-reference/pipelines/run api-reference/pipelines/pipeline.json POST /pipeline/{id}/run Execute a pipeline with the specified inputs and configuration # Terminate a pipeline run Source: https://docs.vectorshift.ai/api-reference/pipelines/terminate api-reference/pipelines/pipeline.json POST /pipeline/{id}/terminate Stop a currently running pipeline instance # Create a new transformation Source: https://docs.vectorshift.ai/api-reference/transformations/create api-reference/transformations/transformation.json POST /transformation # Delete a transformation Source: https://docs.vectorshift.ai/api-reference/transformations/delete api-reference/transformations/transformation.json DELETE /transformation/{id} # Fetch an existing transformation Source: https://docs.vectorshift.ai/api-reference/transformations/fetch api-reference/transformations/transformation.json GET /transformation # List all available transformations Source: https://docs.vectorshift.ai/api-reference/transformations/list api-reference/transformations/transformation.json GET /transformations # Run a transformation Source: https://docs.vectorshift.ai/api-reference/transformations/run api-reference/transformations/transformation.json POST /transformation/{id}/run # Introduction Source: https://docs.vectorshift.ai/introduction Build generative AI apps and workflow automations in minutes Learn VectorShift's core concepts and get started with your first workflow Build custom AI workflows using powerful modular components Connect and integrate your data into a centralized knowledge base Deploy chatbots, search engines, and more to your users Collaborate with your team in real-time with fine-grained access controls Access VectorShift through any programming language # Agent Node Source: https://docs.vectorshift.ai/nodes/agent/overview Run an existing agent as a sub-agent within your workflows or as a tool inside another agent. Add it in Python with `pipeline.add(name="...").agent(...)`. See the SDK reference. The Agent node lets you embed a fully configured agent inside a workflow or use it as a tool within another agent. This enables multi-agent orchestration — for example, you can build a primary agent that delegates research tasks to a specialized sub-agent, or create a workflow that routes customer inquiries through a domain-specific agent before returning a final response. ## Core Functionality * Run any existing **Workflow**-type agent as a sub-agent within a workflow or another agent * Dynamically pass inputs to the sub-agent and receive its outputs for downstream use * Configure the sub-agent inline with custom inputs, outputs, provider, model, and system prompt — or simply reference an already-built agent * Set up agent dependencies so that one sub-agent can call another in a defined execution order ## Tool Inputs * `Use Existing Agent` — **Required** · Boolean · Default: `false` (Workflows), `true` (Agents) · When enabled, select a pre-built agent to run. When disabled, configure the agent inline directly on the node. * `Agent` \* — **Required** · Agent selector · The agent to execute. Only **Workflow**-type agents are supported in workflows and as sub-agents; **Conversational** agents are deployed directly to chat interfaces. * `Provider` — Optional · Dropdown · Default: `OpenAI` · Select the LLM provider for the agent. Available when configuring inline (Use Existing Agent is off). *(Advanced setting)* * `Model` — Optional · Dropdown · Default: `gpt-4.1` · Select the LLM model for the agent. Available when configuring inline. *(Advanced setting)* * `Agent Config` — Optional · Object · The complete agent configuration including instructions, tools, inputs, and outputs. Available when configuring inline. * Dynamic inputs — When an existing agent is selected, its defined input fields appear automatically on the node for you to connect or fill in. \* indicates a required field. ## Tool Outputs * Dynamic outputs — The outputs defined by the selected agent are exposed as output handles on the node. The names and types mirror whatever was configured on the referenced agent's output nodes. ## Overview When added as a tool inside an agent, the Agent tool allows your primary agent to delegate tasks to a specialized sub-agent during a conversation. The primary agent decides when to invoke the sub-agent based on the conversation context, passes the relevant inputs, and incorporates the sub-agent's response into its own reply. This is ideal for building multi-agent systems where each agent handles a distinct domain. ## Use Cases * **Portfolio rebalancing assistant** — A primary financial advisor agent delegates detailed asset allocation calculations to a specialized portfolio optimization sub-agent. * **Compliance review workflow** — A client-facing agent routes regulatory questions to a compliance-specialist sub-agent trained on the latest SEC guidelines. * **Multi-market research** — A head analyst agent dispatches research queries to region-specific sub-agents (e.g., APAC equities, EU fixed income) and synthesizes the results. * **Risk scoring delegation** — A loan processing agent calls a credit-risk sub-agent to evaluate borrower profiles and return a risk score before proceeding. * **Earnings call summarizer** — An investment research agent invokes a sub-agent that specializes in parsing and summarizing earnings call transcripts. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **VectorShift** category. Select **Agent** to add it as a tool. Agent tool panel showing the VectorShift category with Run Agent tool highlighted 2. **Select the agent** — In the tool configuration, use the `Agent` dropdown to choose the existing agent you want to run as a sub-agent. 3. **Configure input fields** — Each input defined on the sub-agent appears as a configurable field. You can either leave a field open so the primary agent fills it automatically based on conversation context, or lock it to a fixed value by entering one directly. Click the sparkle icon to switch a field between dynamic (agent-determined) and static (fixed) mode. Run Agent tool configuration panel showing Agent field with sparkle icon to toggle between dynamic and static values To select a specific agent manually, click the sparkle icon on the Agent field and choose from the dropdown. Run Agent tool configuration with Agent field set to static mode, showing agent selection dropdown 4. **Write a Tool Description** — The Tool Description tells the primary agent what this tool does and when to use it. A good description is specific and action-oriented — for example: *"Use this tool to run a portfolio optimization analysis. Provide the client's risk tolerance and current holdings."* Avoid vague descriptions; the agent relies on this text to decide when to invoke the tool. 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — The agent invokes the sub-agent immediately without user intervention. * **Require User Approval** — The agent pauses and asks the user for confirmation before running the sub-agent. * **Let Agent Decide** — The agent determines at runtime whether to ask for approval or run automatically, based on context. 6. **Test the tool** — Use the chat interface to send a message that should trigger the sub-agent. Verify that the primary agent correctly delegates, the sub-agent processes the request, and the response is incorporated into the conversation. ## Settings * `Agent` — Agent selector · Default: none · The sub-agent to execute. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the primary agent. Drives when and how the agent decides to invoke it. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior (Auto Run, Require User Approval, Let Agent Decide). **Advanced Settings:** * `Max Turns` — Integer · Default: varies · Maximum number of conversation turns the sub-agent can take before returning. * `Model` — Dropdown · Default: inherited from agent · Override the LLM model used by the sub-agent. * `Temperature` — Float · Default: model default · Controls randomness in the sub-agent's responses. * `Top P` — Float · Default: model default · Nucleus sampling parameter for response generation. * `Max Output Tokens` — Integer · Default: model default · Maximum number of tokens in the sub-agent's response. * `Tool Input Behavior` — Dropdown · Default: varies · Controls how tool inputs are handled by the sub-agent. ## Best Practices * **Keep sub-agents focused** — Each sub-agent should handle a single domain (e.g., tax calculations, market data retrieval) rather than being a generalist. This improves accuracy and makes the system easier to debug. * **Write precise tool descriptions** — The primary agent uses the description to decide when to call the sub-agent. Include the specific scenarios, required inputs, and expected output format. * **Use fixed values for sensitive parameters** — For fields like account IDs or compliance thresholds, lock them to fixed values rather than letting the agent fill them dynamically. * **Set appropriate auto-run policies** — Use "Require User Approval" for high-stakes financial actions (e.g., trade execution) and "Auto Run" for read-only operations (e.g., fetching market data). * **Limit max turns** — In financial workflows, set a reasonable max turns value to prevent the sub-agent from entering long loops when processing complex queries. ## Related Templates Matches organizations or individuals to relevant grants based on their profile and eligibility criteria. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Drafts and reviews investment committee memos using deal data and internal templates. Handles common customer inquiries and support tickets through conversational AI. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Agent node lets you embed a complete agent execution step within your workflow. The node accepts inputs from upstream nodes, runs the selected agent, and passes the agent's outputs to downstream nodes. This is useful for adding conversational AI capabilities, complex reasoning, or multi-step tool use into an otherwise deterministic workflow. ## Use Cases * **Automated financial report generation** — A workflow collects raw data from multiple sources, passes it to an Agent node that synthesizes the information into a narrative report, and outputs a formatted document. * **Invoice processing workflow** — Documents flow through extraction nodes, then an Agent node validates and categorizes each invoice using reasoning and tool calls before writing results to a table. * **Client onboarding workflow** — An Agent node handles the conversational portion of KYC verification while the surrounding workflow manages document storage and compliance checks. * **Trading signal enrichment** — Market data feeds into an Agent node that applies fundamental and technical analysis reasoning, then outputs buy/hold/sell signals for downstream processing. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **VectorShift** category. Drag the **Agent** node onto the canvas. Node palette showing the VectorShift category with Agent node being dragged onto the canvas You can also drag the **Agent (Select)** variant, which lets you pick an existing agent directly. Node palette showing the Agent (Select) node being dragged onto the canvas 2. **Choose existing or inline** — Toggle `Use Existing Agent` on to select a pre-built agent, or leave it off to configure the agent directly on the node. The standard workflow view defaults to inline configuration. To access the `Use Existing Agent` toggle, open the workflow from your dashboard in the **console view** — the toggle appears at the top of the Agent node's configuration panel. 3. **Select or configure the agent**: * **Existing agent**: Choose the agent from the dropdown. Its inputs and outputs automatically appear as handles on the node. * **Inline configuration**: Define input names and types (Text, File, List of Files, Audio, Image, Number, Boolean, Integer, DataFrame, etc.), output names and types, select a Provider and Model, and write the system prompt. 4. **Connect inputs** — Wire upstream node outputs into the Agent node's input handles. Each input corresponds to a field the agent expects. Agent node connected to upstream and downstream nodes on the canvas For Agent (Select) nodes, the connection pattern is similar: Agent (Select) node connected to upstream and downstream nodes on the canvas 5. **Configure dependencies** *(optional)* — Use the Dependencies tab to add agent dependencies. This lets you define execution order when multiple sub-agents need to coordinate. 6. **Connect outputs** — Wire the Agent node's output handles to downstream nodes for further processing. 7. **Run the workflow** — Execute the workflow. The Agent node runs the agent with the provided inputs and passes results downstream. ## Settings * `Use Existing Agent` — Boolean · Default: `false` · Toggle between selecting an existing agent or configuring one inline. Access this setting by opening the workflow from your dashboard in the console view. * `Agent` — Agent selector · Default: none · The agent to run. Only Workflow-type agents are supported. **Inline configuration settings (when Use Existing Agent is off):** * `Inputs` — Dynamic · Name and Type pairs defining what the agent accepts. Supported types: Text, File, List of Files, Audio, Image, Number, Boolean, Integer, DataFrame. * `Outputs` — Dynamic · Name and Type pairs defining what the agent returns. * `Provider` — Dropdown · Default: `OpenAI` · The LLM provider. *(Advanced setting)* * `Model` — Dropdown · Default: `gpt-4.1` · The LLM model. *(Advanced setting)* * `System Prompt` — Text area · Default: pre-filled with a general-purpose assistant prompt · Instructions that define the agent's behavior, personality, and constraints. * `Dependencies` — List · Default: none · Other agents that this agent depends on or can call during execution. ## Best Practices * **Use Workflow-type agents only** — Conversational agents cannot be used in workflows. Ensure the agent you select or configure is set to Workflow mode. * **Define explicit input/output types** — Match input and output types precisely to avoid type-mismatch errors when connecting to other nodes. * **Keep system prompts domain-specific** — For financial workflows, include relevant constraints (e.g., "Always cite data sources", "Use ISO currency codes", "Do not provide investment advice without disclaimers"). * **Use dependencies for multi-agent coordination** — When your workflow requires multiple agents that need to share context or execute in order, use the Dependencies tab rather than chaining Agent nodes sequentially. * **Test with representative data** — Before deploying, run the workflow with realistic financial data to verify the agent handles edge cases (missing fields, unusual formats, large datasets). ## Related Templates Matches organizations or individuals to relevant grants based on their profile and eligibility criteria. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Drafts and reviews investment committee memos using deal data and internal templates. Handles common customer inquiries and support tickets through conversational AI. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # AI Routing Source: https://docs.vectorshift.ai/nodes/ai-routing/overview Route execution flow to different paths using AI-powered message classification. Add it in Python with `pipeline.add(name="...").ai_routing(...)`. See the SDK reference. The AI Routing node uses an LLM to classify an incoming message and route execution to the matching path. Use it to build intelligent branching workflows — for example, directing customer inquiries to different processing workflows based on intent, or routing financial documents to the correct extraction workflow based on document type. ## Core Functionality * Classifies an input message using a configurable LLM provider and model * Routes execution to one of multiple user-defined paths based on the classification result * Supports any number of paths, each with a natural-language description the LLM uses to decide the match * Does not produce data outputs — downstream nodes reference previous nodes' output fields directly ## Tool Inputs * `Message` \* — The text the AI router will classify to determine which path to execute. Required. Text. * `Shared Memory` — Additional context the AI uses when determining the routing. Text. Use this to pass conversation history or other background information that helps the model make a more accurate classification. * `Provider` — The LLM provider to use for classification. Dropdown, default: `OpenAI`.- `Model` — The specific model to use for classification. Dropdown, default: `gpt-4o`.- `Temperature` — Controls randomness in the model's classification. Decimal, default: `0.7`. Lower values produce more deterministic routing.- `Max Tokens` — The maximum number of tokens the model can generate. Integer, default: `2048`.- `Top P` — Nucleus sampling parameter. Decimal, default: `1.0`.- `Path Descriptions` — Each path has a natural-language description (e.g., "Customer is asking about billing" or "Document is a tax form"). The LLM reads these descriptions to decide which path matches the input message. \* *Required field* ## Tool Outputs The AI Routing node does not produce data outputs. It evaluates which path to execute based on the classification. To access data in downstream nodes, reference the output fields of nodes that ran before the AI Routing node. *** ### Overview In workflows, the AI Routing node sits between upstream data-producing nodes and multiple downstream branches. It reads the `Message` input, uses the configured LLM to classify it against the path descriptions, and activates the matching branch. Use it when you need intelligent, content-aware branching that goes beyond simple string matching — for example, routing support tickets by intent or dispatching financial documents to the right extraction workflow. ### Use Cases * Route incoming customer messages to billing, technical support, or sales workflows based on intent classification * Direct financial documents (invoices, tax forms, contracts) to specialized extraction workflows based on document type * Classify transaction descriptions and route to the appropriate categorization or compliance review path * Triage risk alerts by severity and route to escalation or standard processing branches * Sort incoming emails by topic and forward to the correct department workflow ### How It Works #### Step 1: Add the AI Routing Node In the workflow canvas, click the **Logic** tab in the node palette and click **AI Routing**. Drag it onto the canvas. Workflow node palette showing the Logic tab with AI Routing highlighted #### Step 2: Write the Message Input In the `Message` field, type the text the AI should classify, or connect it from an upstream node's output. This field is required — the node displays a validation error if left empty. #### Step 3: Define Paths Each path has a description field. Write a clear, natural-language description of what qualifies a message for that path — for example, "The customer is asking about pricing or billing" or "The document is a quarterly earnings report." * **Path 1** comes pre-configured. Enter its description. * **Path 2** comes pre-configured. Enter its description. * Click **+ Add Path** at the bottom to add more paths as needed. Each path creates a separate output handle on the right side of the node that you connect to downstream nodes. #### Step 4: Configure the AI Model (Optional) The right side of the node exposes advanced model settings: * **`Provider`** — Select the LLM provider (default: OpenAI). * **`Model`** — Select the specific model (default: gpt-4o). * **`Temperature`** — Adjust classification randomness (default: 0.7). Use lower values for more consistent routing. * **`Max Tokens`** — Set the token limit (default: 2048). * **`Top P`** — Adjust nucleus sampling (default: 1.0). Optionally, fill in `Shared Memory` to give the model additional context for classification. #### Step 5: Connect Downstream Nodes Connect each path's output handle to the downstream nodes that should execute for that classification. Downstream nodes reference the output fields of nodes that ran *before* the AI Routing node — the AI Routing node itself does not pass data through. AI Routing node on canvas with paths connected to downstream node branches #### Step 6: Test the Workflow Click **Run** to test the workflow. Provide a sample message and verify that the AI routes it to the correct path. ### Settings | Setting | Type | Default | Description | | ------------------- | --------------- | ------- | ---------------------------------------------------------------------- | | `Message` | Text | — | The text to classify for routing. Required. | | `Shared Memory` | Text | — | Additional context for the AI classification. | | `Provider` | Dropdown | OpenAI | The LLM provider. **Advanced setting.** | | `Model` | Dropdown | gpt-4o | The specific model for classification. **Advanced setting.** | | `Temperature` | Decimal | 0.7 | Controls randomness. Lower = more deterministic. **Advanced setting.** | | `Max Tokens` | Integer | 2048 | Maximum tokens for classification. **Advanced setting.** | | `Top P` | Decimal | 1.0 | Nucleus sampling parameter. **Advanced setting.** | | `Path Descriptions` | Text (per path) | — | Natural-language description of each routing path. | ### Best Practices * **Write distinct path descriptions.** The LLM classifies based on descriptions — make them clearly distinguishable. Avoid overlapping language like "billing questions" and "payment questions" in separate paths. * **Use low temperature for critical routing.** In financial workflows where misrouting has consequences (e.g., compliance vs. general inquiries), set temperature to 0.1–0.3 for more deterministic classification. * **Add a catch-all path.** Include a final path with a description like "Any message that does not match the above categories" to handle edge cases. * **Leverage Shared Memory for context.** When routing depends on prior conversation history (e.g., a follow-up message about an earlier topic), pass the conversation context into `Shared Memory`. * **Keep path count manageable.** More paths increase the chance of misclassification. If you need many branches, consider cascading AI Routing nodes — first route by broad category, then sub-route within each branch. ### Related Templates Automatically categorizes and tags incoming documents based on content and type. Assesses risk levels in incoming applications using scoring models and policy rules. Reviews and routes refund or expense requests based on policy rules and approval thresholds. Classifies capital expenditure items against accounting standards and internal policies. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Anthropic LLM Source: https://docs.vectorshift.ai/nodes/anthropic/overview Generate text responses using Anthropic's Claude models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Anthropic LLM node connects your workflows to Anthropic's Claude family of language models. Use it to generate text responses, analyze documents, answer questions grounded in knowledge bases, or produce structured JSON outputs for downstream processing — for example, drafting client summaries from earnings transcripts, classifying support tickets by urgency, or extracting key figures from financial reports. ## Core Functionality * Generate text completions and conversational responses using Claude models * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `claude-sonnet-4-6`) Select from available Claude models. Click **Dropdown** to view all options * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own Anthropic API key instead of VectorShift's shared key * `Api Key` — (String) Your Anthropic API key. Only visible when `Use Personal Api Key` is enabled * `JSON Schema` — (String) JSON schema to enforce structured output format. Only visible when `JSON Response` is enabled in the settings panel \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Anthropic LLM node in workflows lets you place a Claude model directly on the canvas, wire inputs and outputs to other nodes, and configure model behavior through the settings panel. Responses can be streamed for real-time display or returned as a complete block for downstream processing. ## Use Cases * **Earnings call analysis** — Summarize quarterly earnings transcripts and extract key financial metrics like revenue, EPS, and guidance changes for analyst review. * **Regulatory document review** — Parse SEC filings or compliance documents, flagging sections that require legal attention or contain material disclosures. * **Client communication drafting** — Generate personalized portfolio update emails by combining market data with client-specific holdings and risk profiles. * **Financial data extraction** — Pull structured data from unstructured documents using JSON mode — extract line items from invoices or expense reports into a consistent schema. * **Risk assessment narratives** — Produce written risk summaries by combining quantitative model outputs with qualitative market context and historical patterns. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Anthropic** node onto the canvas. Anthropic node being dragged onto the canvas from the AI category 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. For example: *"Answer the question based on context in a professional manner."* 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. For example: `Question: {{input_0.text}} Context: {{knowledge_base_0.chunks}}`. 4. **Select a model.** Use the `Model` dropdown to choose a Claude model. Available options include `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-opus-4`, `claude-haiku-4-5`, `claude-3.7-sonnet`, `claude-3.5-haiku`, and others. Anthropic node showing the Model dropdown with available Claude models 5. **Enable streaming (optional).** Click the **Streaming** toggle on the node face to receive responses token-by-token. When streaming is enabled, the `response` output type changes to `Stream` — ensure any connected Output node is set to **Streamed Text**. 6. **Use a personal API key (optional).** Toggle `Use Personal Api Key` to **Yes** to use your own Anthropic API key. An `Api Key` field appears below — paste your key there. 7. **Open settings.** Click the **gear icon** (⚙) on the node to open the settings panel, where you can configure token limits, temperature, retry behavior, safety features, and more. Anthropic node settings panel 8. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes (e.g., an Output node, another LLM, or a Text node). Use `tokens_used`, `input_tokens`, `output_tokens`, and `credits_used` for monitoring and cost tracking. Anthropic node connected to upstream and downstream nodes 9. **Run your workflow.** Execute the workflow. The Anthropic node processes its inputs and returns the generated response along with usage metrics. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | --------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Provider` | Dropdown | Anthropic | The LLM provider. | | `Max Tokens` | Integer | 64096 | Maximum number of input + output tokens the model will process per run. Different models have different token limits — the workflow will error if the limit is exceeded. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning the model applies to its response. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values (toward 1.0) produce more diverse outputs; lower values (toward 0) produce more deterministic responses. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. | | `Stream` | Boolean | Off | Stream responses token-by-token instead of returning the full response at once. | | `JSON Response` | Boolean | Off | Return output as structured JSON. When enabled, a `JSON Schema` input appears for optional schema enforcement. | | `Show Sources` | Boolean | Off | Display source documents used for the response. Useful when combining with knowledge base inputs. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. If the model receives toxic content, it responds with a respectful message instead. | | `Web Search` | Boolean | Off | Enable web search capabilities for the model during generation. | | `Safety` | Toggle | On | Enable safety guardrails for content filtering. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window, preventing token-limit errors on variable-length inputs. | | `Max # of re-try` | Integer | 100 | Maximum number of retry attempts when execution fails. Visible when retry is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input before sending to the model. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `Credit Card Info` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Guardrail Status` | Dropdown | — | Controls whether guardrail status is included in the output. | ## Best Practices * **Start with a specific system prompt.** For financial workflows, include explicit instructions about the output format — e.g., "Respond with bullet points," "Include only numerical data," or "Cite the section of the filing." * **Use JSON mode for structured extraction.** When pulling financial metrics from documents, enable `JSON Response` and provide a schema to ensure consistent, machine-readable output across runs. * **Monitor token usage.** Connect `tokens_used` and `credits_used` outputs to tracking nodes, especially important for high-volume batch processing of financial documents. * **Enable Safe Context Token Window for variable-length inputs.** When processing documents of unpredictable size (like earnings transcripts), this prevents token-limit errors by automatically truncating inputs. * **Use streaming for client-facing interfaces.** If the Anthropic node powers a chatbot answering investor queries, enable streaming for a more responsive user experience. * **Apply PII detection for client data.** When processing client communications or personal financial data, enable the relevant PII detection toggles to prevent sensitive information from being sent to the model. ## Related Templates Matches organizations or individuals to relevant grants based on their profile and eligibility criteria. Drafts and reviews investment committee memos using deal data and internal templates. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # AWS Bedrock LLM Source: https://docs.vectorshift.ai/nodes/aws-bedrock/overview Generate text responses using AWS Bedrock models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The AWS Bedrock LLM node connects your workflows to Amazon Bedrock's managed model catalog. Use it to access foundation models from providers like Anthropic Claude, Amazon Titan, and Meta Llama through your AWS account — enabling use cases such as generating investment research summaries, extracting data from regulatory filings, or building compliant AI workflows that keep data within your AWS environment. ## Core Functionality * Generate text completions using models available through AWS Bedrock * Authenticate with your own AWS credentials for enterprise-grade access control * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `us.anthropic.claude-sonnet-4-5`) Select from available Bedrock models * `Use Personal AWS Credentials` — (Boolean, default: No) Toggle to authenticate with your own AWS credentials * `AWS Access Key ID` — (String) Your AWS access key. Only visible when `Use Personal AWS Credentials` is enabled * `AWS Secret Key` — (String) Your AWS secret key. Only visible when `Use Personal AWS Credentials` is enabled * `AWS Region` — (Dropdown, default: US East N. Virginia) The AWS region for Bedrock API calls. Only visible when `Use Personal AWS Credentials` is enabled * `JSON Schema` — (String) JSON schema to enforce structured output format. Only visible when `JSON Response` is enabled in the settings panel \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Bedrock LLM node in workflows lets you place an AWS Bedrock model directly on the canvas, optionally authenticate with your own AWS credentials, and configure model behavior through the settings panel. This is ideal for organizations that require data to stay within their AWS environment or need access to Bedrock-exclusive models. ## Use Cases * **Compliant document processing** — Process sensitive financial documents using models hosted within your AWS account, ensuring data residency and compliance requirements are met. * **Multi-model evaluation** — Compare outputs from different foundation models (Claude, Titan, Llama) available on Bedrock to find the best fit for your financial analysis tasks. * **Automated report generation** — Generate quarterly portfolio reports by combining market data with client holdings, using enterprise-grade AWS infrastructure. * **Regulatory filing extraction** — Parse and extract structured data from SEC filings or tax documents using JSON mode, keeping all data within your AWS boundary. * **Internal knowledge Q\&A** — Build internal chatbots that answer compliance questions by grounding responses in your organization's policy knowledge base. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **AWS** node onto the canvas. It appears as "Bedrock" on the node. 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. 4. **Select a model.** Use the `Model` dropdown to choose from available Bedrock models, including `us.anthropic.claude-sonnet-4-5` and other foundation models. AWS Bedrock node showing the Model dropdown 5. **Enable streaming (optional).** Click the **Streaming** toggle on the node face to receive responses token-by-token. When streaming is enabled, the `response` output type changes to `Stream`. 6. **Use personal AWS credentials (optional).** Toggle `Use Personal AWS Credentials` to enable authentication with your own AWS account. Three fields appear: * `AWS Access Key ID` — Your AWS access key * `AWS Secret Key` — Your AWS secret access key * `AWS Region` — Select your preferred AWS region (e.g., US East N. Virginia) 7. **Open settings.** Click the **gear icon** (⚙) on the node to open the settings panel, where you can configure token limits, temperature, retry behavior, safety features, and more. 8. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes. Use `tokens_used`, `input_tokens`, `output_tokens`, and `credits_used` for monitoring. AWS Bedrock node connected to upstream and downstream nodes 9. **Run your workflow.** Execute the workflow. The Bedrock node processes its inputs through AWS and returns the generated response along with usage metrics. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | Bedrock | The LLM provider. | | `Max Tokens` | Integer | 64000 | Maximum number of input + output tokens the model will process per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning the model applies to its response. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values produce more diverse outputs; lower values produce more deterministic responses. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. Range: 0–1. | | `Stream` | Boolean | Off | Stream responses token-by-token instead of returning the full response at once. | | `JSON Response` | Boolean | Off | Return output as structured JSON. When enabled, a `JSON Schema` input appears for optional schema enforcement. | | `Show Sources` | Boolean | Off | Display source documents used for the response. Useful when combining with knowledge base inputs. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. If the model receives toxic content, it responds with a respectful message instead. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max # of re-try` | Integer | — | Maximum number of retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input before sending to the model. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `SSN` | Boolean | Off | Detect and redact Social Security numbers from input. | | `Credit Card Info` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Guardrail Status` | Dropdown | — | Controls whether guardrail status is included in the output. | ## Best Practices * **Use personal AWS credentials for production workloads.** This ensures data stays within your AWS account and lets you leverage AWS IAM policies for fine-grained access control. * **Select the appropriate region.** Choose an AWS region close to your users or one that meets your data residency requirements for compliance-sensitive financial workflows. * **Use JSON mode for structured extraction.** When pulling financial metrics from documents, enable `JSON Response` and provide a schema for consistent, machine-readable output. * **Enable Safe Context Token Window for variable-length inputs.** Prevents token-limit errors when processing documents of unpredictable size like earnings transcripts or multi-page filings. * **Monitor token usage for cost management.** Bedrock charges per token — connect `tokens_used` and `credits_used` to tracking nodes to monitor spend across high-volume processing. * **Apply PII detection for regulated data.** When handling client financial data subject to regulatory requirements, enable PII toggles including SSN detection. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Browser Extension Source: https://docs.vectorshift.ai/nodes/browser-extension/overview Run a VectorShift workflow using the current page captured by the VectorShift Chrome Extension as input. Add it in Python with `pipeline.add(name="...").browser_extension(...)`. See the SDK reference. The Browser Extension node lets you run a VectorShift workflow directly from your browser using the content of the page you are currently viewing. Use it to build workflows that extract, summarize, or analyze any web page on demand — for example, pulling key data from a financial filing, summarizing a competitor's press release, or capturing a screenshot of a dashboard for downstream processing. ## Core Functionality * Captures the current browser page's content, URL, links, HTML, and screenshot via the VectorShift Chrome Extension * Feeds captured page data into a workflow as output fields that downstream nodes can consume * Requires the VectorShift Chrome Extension to be installed and the workflow to be deployed ## Tool Inputs This node has no configurable input fields. All data is captured automatically from the active browser page when the workflow is triggered via the Chrome Extension. * `Show on VectorShift Chrome Extension` — Toggle. Default: `on`. Controls whether this workflow appears in the VectorShift Chrome Extension after deployment. ## Tool Outputs * `page_content` — Text. The text content extracted from the current page. * `url` — Text. The URL of the current page. * `page_urls` — List\. All URLs (links) found on the current page. * `screenshot` — Image. A screenshot of the current page. * `page_html` — Text. The raw HTML source of the current page. *** ### Overview In workflows, the Browser Extension node acts as an entry point that captures live web page data when a user triggers the workflow from the Chrome Extension. It outputs the page's text content, URL, links, screenshot, and HTML — making it easy to build automations that process any page a user is viewing. Use it to power on-demand web research, document extraction, or monitoring workflows triggered directly from the browser. ### Use Cases * Extract key financial metrics from an earnings report page and route them into a structured spreadsheet workflow * Capture a screenshot of a live trading dashboard and send it to a Slack channel via a notification node * Summarize a lengthy regulatory filing or legal document open in the browser into a concise brief * Pull all outbound links from a competitor's product page for competitive intelligence analysis * Grab the HTML of a vendor invoice page and feed it into a data extraction workflow ### How It Works #### Step 1: Add the Browser Extension Node In the workflow canvas, click the **Start** tab in the node palette and click **Browser Extension**. Drag it onto the canvas. Browser Extension node being dragged onto the canvas from the Start tab #### Step 2: Review Settings The node has one setting: `Show on VectorShift Chrome Extension`. This toggle is on by default and controls whether the workflow is available in the Chrome Extension after deployment. Leave it on for the workflow to appear in the extension. #### Step 3: Connect Downstream Nodes Connect the output handles (`page_content`, `url`, `page_urls`, `screenshot`, `page_html`) to downstream nodes. For example, connect `page_content` to an LLM node for summarization, or `screenshot` to an image processing node. Browser Extension node connected to downstream nodes on the canvas #### Step 4: Deploy the Workflow The node displays a note: *"Please deploy the workflow to show on chrome extension."* Save and deploy the workflow so it becomes available in the Chrome Extension. #### Step 5: Trigger from the Browser Open the VectorShift Chrome Extension on any web page. Select the deployed workflow and run it. The node automatically captures the current page's data and passes it to the workflow. ### Settings | Setting | Type | Default | Description | | -------------------------------------- | ------ | ------- | ---------------------------------------------------------------------- | | `Show on VectorShift Chrome Extension` | Toggle | On | Whether the workflow appears in the Chrome Extension after deployment. | ### Best Practices * **Deploy before testing.** The Browser Extension node only works after the workflow is deployed — running it on the canvas without deployment will not capture browser data. * **Use `page_content` for text analysis.** For summarization, extraction, or classification tasks, `page_content` provides clean text without HTML markup. * **Use `page_html` for structured extraction.** When you need to parse specific elements (tables, forms, metadata), use the raw HTML output with a transformation or code node. * **Combine `screenshot` with image-to-text.** For pages that render content as images (charts, infographics), pipe the screenshot into an Image to Text node. * **Filter `page_urls` for targeted crawling.** Use a Filter List node downstream to narrow the captured URLs to specific domains or patterns before further processing. ### Related Templates Provides real-time customer support directly embedded within a website interface. Scans and evaluates webpage content for regulatory and legal compliance issues. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Chat File Reader Source: https://docs.vectorshift.ai/nodes/chat-file-reader/overview Allow document uploads within chatbots and process uploaded files into text for downstream use. Add it in Python with `pipeline.add(name="...").chat_file_reader(...)`. See the SDK reference. The Chat File Reader node enables document uploads within chatbot interfaces, processing uploaded files into text that downstream nodes can consume. Use it to let end users attach PDFs, Word documents, or other files during a chat conversation — for example, uploading a financial statement for the LLM to analyze, attaching a contract for clause extraction, or submitting an invoice for automated data entry. ## Core Functionality * Enables file upload capability in deployed chatbot interfaces * Processes uploaded documents into chunked text using configurable parsing settings * Supports multiple processing models including Default (standard OCR), Llama Parse (complex documents), Textract (advanced extraction), and Reducto * Outputs parsed document text as a list that can be connected to LLM or knowledge base nodes chat file reader connect with nodes chat file reader settings ## Tool Inputs This node has no user-facing input fields on the canvas. All configuration is done through the Settings panel. Documents are provided by the end user at runtime through the chatbot interface. ## Tool Outputs * `documents` — List\. The uploaded file(s) processed into text chunks. Each element contains a chunk of the parsed document content. *** ### Overview In workflows, the Chat File Reader node sits at the front of a chatbot workflow and provides the file upload capability in the deployed chat interface. When an end user uploads a document during a conversation, the node processes it into text chunks and passes them downstream — typically to an LLM node for analysis, summarization, or question answering over the uploaded content. ### Use Cases * Let users upload financial statements during a chat session and have an LLM summarize key metrics or flag anomalies * Accept contract PDFs in a chatbot and extract specific clauses, dates, or party names using downstream extraction nodes * Enable invoice uploads for automated line-item extraction and entry into an accounting workflow * Allow users to attach compliance documents for real-time regulatory review powered by an LLM * Support resume or application uploads in an HR chatbot for automated screening and scoring ### How It Works #### Step 1: Add the Chat File Reader Node In the workflow canvas, click the **Chat** tab in the node palette and click **Chat File Reader**. Drag it onto the canvas. chat file reader drag into canvas #### Step 2: Connect to an LLM Node Connect the `documents` output to an LLM node's input. This is the most common pattern — the LLM receives the parsed document text and can answer questions about it. #### Step 3: Configure Settings Click the settings icon on the node to open the Settings panel. Adjust the following as needed: * **`Max Chunks Per Query`** — The maximum number of chunks to retrieve for each query. Default: `10`. * **`Chunk Size`** — The number of tokens per chunk (1 token is approximately 4 characters). Default: `1000`. * **`Chunk Overlap`** — The number of overlapping tokens between consecutive chunks. Default: `200`. * **`Retrieval Unit`** — How results are returned. Options: `Chunks` (text content only), `Documents` (includes document metadata and relevant snippets), `Pages` (returns complete pages containing relevant content). Default: `Chunks`. * **`Processing Model`** — The parsing engine used to extract text from uploaded files. Options: `Default` (standard document parsing and OCR), `Llama Parse` (handles complex features like tables and charts — charged at 0.3 cents per page), `Textract` (most advanced data extraction — charged at 1.5 cents per page), `Reducto`. Default: `Default`. #### Step 4: Deploy and Test Deploy the workflow as a chatbot. In the chat interface, upload a file and send a message. The Chat File Reader processes the uploaded document and passes the text to connected downstream nodes. ### Settings | Setting | Type | Default | Description | | ------------------------------ | -------- | ------- | ----------------------------------------------------------- | | `Max Chunks Per Query` | Integer | 10 | Maximum number of chunks to retrieve per query. | | `Chunk Size` | Integer | 1000 | Tokens per chunk (1 token ≈ 4 characters). | | `Chunk Overlap` | Integer | 200 | Overlapping tokens between consecutive chunks. | | `Retrieval Unit` | Dropdown | Chunks | Return format: Chunks, Documents, or Pages. | | `Processing Model` | Dropdown | Default | Parsing engine: Default, Llama Parse, Textract, or Reducto. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. | ### Best Practices * **Match chunk size to your LLM's context window.** If using a model with a smaller context window, reduce chunk size to ensure each chunk fits comfortably within the token limit. * **Increase chunk overlap for dense documents.** For financial reports or legal contracts where context spans paragraph boundaries, increase overlap to 300–400 to avoid splitting critical information across chunks. * **Use Llama Parse or Textract for complex documents.** Standard OCR may struggle with tables, charts, or multi-column layouts common in financial statements and annual reports. Llama Parse and Textract handle these better at a per-page cost. * **Set retrieval unit to Pages for page-level context.** When users ask questions that require full-page context (e.g., "What's on page 3?"), use the Pages retrieval unit instead of Chunks. * **Keep Max Chunks Per Query reasonable.** Setting this too high can overwhelm the LLM with too much context. Start with 10 and adjust based on the complexity of user queries. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Automatically categorizes and tags incoming documents based on content and type. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Chat Memory Source: https://docs.vectorshift.ai/nodes/chat-memory/overview Give connected nodes access to conversation history for multi-turn chatbot interactions. Add it in Python with `pipeline.add(name="...").chat_memory(...)`. See the SDK reference. chat memory connect with nodes The Chat Memory node gives connected nodes access to conversation history, enabling multi-turn chatbot interactions where the LLM remembers what was said earlier. Use it to build chatbots that maintain context across messages — for example, a financial advisor bot that references earlier questions about a portfolio, a support agent that tracks the issue progression, or a research assistant that builds on prior analysis. ## Core Functionality * Stores and retrieves conversation history from deployed chatbot sessions * Supports multiple memory strategies: Token Buffer, Message Buffer, Full - Formatted, Full - Raw, and Vector Database * Outputs formatted conversation history as text that LLM nodes can consume as context * Configurable memory window to control how much history is retained chat memory settings ## Tool Inputs * `Memory Type` — Dropdown. Default: `Token Buffer`. The strategy used to store and retrieve conversation history. Options: * `Message Buffer` — Returns a set number of previous consecutive messages * `Token Buffer` — Returns previous consecutive messages up to a token limit * `Full - Formatted` — Returns all previous chat history as formatted text * `Full - Raw` — Returns all previous chat history as a structured list with type and message fields * `Vector Database` — Stores all messages in a vector database and returns the most similar messages based on the current user message * `Token Window` — Integer. The memory window size. Default varies by memory type: `2048` for Token Buffer, `10` for Message Buffer, `20` for Vector Database. Not shown for Full - Formatted or Full - Raw. chat memory select type ## Tool Outputs * `memory` — Text. The conversation history in the format of the selected memory type. *** ### Overview In workflows, the Chat Memory node connects to an LLM node to provide conversation context. When deployed as a chatbot, the node captures each exchange and feeds the relevant history back to the LLM on every turn — so the model can reference previous messages, follow up on earlier topics, and maintain a coherent conversation. The memory type you choose controls how history is formatted and how much is retained. ### Use Cases * Build a financial advisor chatbot that remembers earlier questions about portfolio allocations and references them in follow-up answers * Create a customer support bot that tracks the full issue progression across multiple messages without losing context * Power an onboarding assistant that guides users through a multi-step process and recalls answers from earlier steps * Enable a research chatbot that builds on prior analysis, referencing data points mentioned in previous turns * Implement a compliance Q\&A bot that remembers which regulations have already been discussed to avoid repetition ### How It Works #### Step 1: Add the Chat Memory Node In the workflow canvas, click the **Chat** tab in the node palette and click **Chat Memory**. Drag it onto the canvas. chat memory drag into canvas #### Step 2: Select a Memory Type Use the `Memory Type` dropdown on the node to choose how conversation history is stored and retrieved: * **Token Buffer** (default) — Best for most use cases. Keeps as many recent messages as fit within the token window. * **Message Buffer** — Returns a fixed number of recent messages. Use when you want a predictable history length. * **Full - Formatted** — Returns the entire conversation history. Use for short conversations where you want full context. * **Full - Raw** — Returns history as a structured list. Use when downstream processing needs raw message objects. * **Vector Database** — Returns semantically similar messages instead of recent ones. Use for long conversations where only relevant context matters. #### Step 3: Configure the Memory Window Click the settings icon to open the Settings panel. Adjust `Token Window` based on your memory type: * For **Token Buffer**: set the maximum number of tokens (default: 2048). The node returns messages from most recent backward until adding another would exceed this limit. * For **Message Buffer**: set the number of messages to keep (default: 10). * For **Vector Database**: set the number of similar messages to retrieve (default: 20). * **Full - Formatted** and **Full - Raw** do not use a memory window — they return everything. #### Step 4: Connect to an LLM Node Connect the `memory` output to the LLM node's `System` or `Chat History` input. The LLM receives the formatted conversation history and uses it as context for generating responses. #### Step 5: Deploy and Test Deploy the workflow as a chatbot. Send multiple messages and verify that the LLM's responses reflect awareness of previous turns. ### Settings | Setting | Type | Default | Description | | ------------------------------ | -------- | -------------- | ----------------------------------------------------------------------------------------- | | `Memory Type` | Dropdown | Token Buffer | The strategy for storing and retrieving conversation history. | | `Token Window` | Integer | Varies by type | Memory window size. 2048 for Token Buffer, 10 for Message Buffer, 20 for Vector Database. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. | ### Best Practices * **Use Token Buffer for most chatbots.** It automatically manages context size and prevents exceeding LLM token limits — ideal for financial advisor or support bots with unpredictable conversation lengths. * **Match Token Window to your LLM's context budget.** If your LLM has a 4096-token context and you need room for the system prompt and current message, set the memory window to 2048 or less. * **Use Vector Database for long-running sessions.** In conversations that may span dozens of turns (e.g., ongoing compliance reviews), Vector Database retrieves only the most relevant prior messages instead of recent ones. * **Use Full - Raw when you need structured parsing.** If downstream nodes need to process individual messages (e.g., counting user questions or extracting specific turns), Full - Raw provides a parseable list format. * **Avoid Full modes for long conversations.** Full - Formatted and Full - Raw return the entire history. For conversations that may grow long, this can exceed LLM context limits — use Token Buffer or Message Buffer instead. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Handles investor inquiries related to portfolios, statements, and fund performance. Answers employee questions about internal policies and flags potential compliance issues. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Code Source: https://docs.vectorshift.ai/nodes/code/overview Execute custom Python or JavaScript code with configurable inputs and outputs. Add it in Python with `pipeline.add(name="...").code_execution(...)`. See the SDK reference. The Code node lets you run custom Python or JavaScript code directly inside your workflow. Define your own inputs and outputs, write transformation logic, call libraries, and return structured results — all without leaving VectorShift. Use it to apply custom business logic to financial data, transform API responses into the exact format you need, or give an agent the ability to compute values on the fly during a conversation. ## Core Functionality * Executes custom Python or JavaScript code within a workflow * Supports user-defined inputs and outputs with configurable names and types * Includes a built-in code editor with boilerplate templates for each language * Available input/output types include Text, File, Image, and more * Works in both **Workflows** as a canvas node and **Agents** as the Code tool ## Tool Inputs * `Input Name` — A user-defined input parameter. You can add multiple inputs by clicking **+ Add**. Each input has a configurable name (e.g., `input_1`) and a type selected from a dropdown (e.g., `Text`, `File`, `Image`). * `Code` \* — The Python or JavaScript code to execute. Required. The code editor is pre-populated with boilerplate that shows how to access inputs and set the output variable. * `Language` — Toggle between `Python` and `JavaScript`. The code editor template updates to match the selected language. \* *Required field* ## Tool Outputs * `Output Name` — A user-defined output parameter. You can add multiple outputs by clicking **+ Add**. Each output has a configurable name (e.g., `output_1`) and a type selected from a dropdown (e.g., `Text`, `File`, `Image`). The code must assign a value to each defined output variable. *** ### Overview In agents, the Code tool lets the agent execute custom Python or JavaScript code during a conversation. You define the inputs, outputs, and code logic — the agent then invokes this tool when appropriate, passing in values from conversation context. Use it when you need the agent to perform calculations, data transformations, or any custom logic that goes beyond what built-in tools offer. ### Use Cases * Calculate compound interest or amortization schedules from user-provided loan parameters * Parse and transform raw JSON API responses into human-readable financial summaries * Run custom validation logic on portfolio allocation percentages before proceeding * Convert between currencies or units using custom formulas with live rates * Generate formatted reports by processing structured data from upstream tools * Compute weighted averages or custom scoring across multiple data points ### How It Works #### Step 1: Add the Code Tool From the agent editor, click **+ Add Tool**. Select the **Logic** category and click **+ Add** next to **Code**. Agent tool panel showing the Logic category with Code Interpreter tool highlighted #### Step 2: Open the Tool Configuration Click **Edit** on the Code tool in the tool list to open its configuration panel. Code Interpreter tool configuration panel showing Tool Description, Code, Input Files, and Knowledge Base fields #### Step 3: Select the Language Choose between **Python** and **JavaScript** using the language toggle at the top of the configuration panel. The code editor template updates automatically. #### Step 4: Define Inputs Add input parameters that your code will receive. For each input: * Set the **Input Name** (e.g., `input_1`, `principal`, `rate`). * Select the **Input Type** from the dropdown (e.g., `Text`). * Click **+ Add Input** to add additional inputs. Each input field can be filled automatically by the agent based on conversation context, or locked to a fixed value. Click the toggle icon next to a field to switch between these modes. #### Step 5: Write Your Code Write your logic in the code editor. The default template shows how to access inputs as variables and how to assign values to the output variable: **Python:** ```python theme={"languages":{}} # Access your inputs as variables (e.g., input_1) # Assign your result to the output variable output = input_1 ``` **JavaScript:** ```javascript theme={"languages":{}} // Access your inputs as variables (e.g., input_1) // Assign your result to the output variable output = input_1; ``` #### Step 6: Define Outputs Add output parameters that your code will return. For each output: * Set the **Output Name** (e.g., `output_1`, `result`). * Select the **Output Type** from the dropdown (e.g., `Text`). * Click **+ Add Output** to add additional outputs. Your code must assign a value to each output variable you define. #### Step 7: Write a Tool Description The **Tool Description** tells the agent when and how to use this tool. Customize it with specifics — for example: *"Use this tool to calculate compound interest. The user will provide the principal, rate, and number of periods."* #### Step 8: Set Auto Run Behavior Click the **Auto Run** dropdown to control execution: * **Auto Run** — The agent runs the code automatically without asking for confirmation. * **Require User Approval** — The agent pauses and asks the user before running the code. * **Let Agent Decide** — The agent uses its judgment to decide whether to confirm first. Code Interpreter tool requiring user approval, showing code, Knowledge Base, and Input Files fields in the approval dialog #### Step 9: Test the Tool In the agent chat panel, ask the agent to perform a calculation or transformation. The agent invokes the Code tool and returns the result. A **Code Interpreter** panel appears in the sidebar showing the executed code and its output. ### Settings | Setting | Type | Default | Description | | ------------- | ----------- | -------------------- | ---------------------------------------------------------- | | `Language` | Toggle | Python | Python or JavaScript. | | `Input Name` | Text | input\_1 | Name of each input parameter. Add more with + Add Input. | | `Input Type` | Dropdown | Text | Type of each input (Text, File, Image, etc.). | | `Code` | Code editor | Boilerplate template | The code to execute. Required. | | `Output Name` | Text | output\_1 | Name of each output parameter. Add more with + Add Output. | | `Output Type` | Dropdown | Text | Type of each output (Text, File, Image, etc.). | ### Best Practices * **Name inputs descriptively.** Use meaningful names like `principal`, `rate`, `periods` instead of `input_1`, `input_2` — this helps the agent understand what values to pass. * **Write a detailed tool description.** Explain what the code does, what inputs it expects, and what it returns. This guides the agent to invoke it correctly. * **Require user approval for irreversible operations.** If the code modifies data or calls external services, set Auto Run to **Require User Approval** so users can review before execution. * **Keep code focused.** Write code that does one thing well. For complex multi-step logic, use multiple Code tools chained together. * **Handle edge cases in the code.** Add input validation and error handling within your code to avoid silent failures. ### Related Templates Queries and interprets Snowflake data warehouse data to deliver actionable business insights. Analyzes earnings call transcripts for sentiment, key themes, and forward-looking signals. Identifies and analyzes foreign exchange arbitrage opportunities across markets and instruments. Processes and validates capital account statements for accuracy and investor reporting. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. ### Overview In workflows, the Code Execution node lets you write and run custom Python or JavaScript code on the canvas. Define typed inputs connected from upstream nodes, write your transformation logic, and output structured results to downstream nodes. Use it for any custom processing step — data transformations, calculations, format conversions, or business logic that isn't covered by built-in nodes. ### Use Cases * Transform raw API response JSON into a structured format for downstream processing * Calculate financial metrics (IRR, NPV, CAGR) from extracted spreadsheet values * Apply custom data validation rules before writing results to a database or file * Parse and reformat dates, currencies, or account numbers across different standards * Merge and deduplicate data from multiple upstream sources using custom logic ### How It Works #### Step 1: Add the Code Execution Node In the workflow canvas, click the **Logic** tab in the node palette and click **Code**. Drag it onto the canvas. Workflow node palette showing the Logic tab with Code option #### Step 2: Select the Language Use the language toggle at the top of the node to switch between **Python** and **JavaScript**. The code editor template updates to match. #### Step 3: Define Inputs Each input has a name and a type: * **Name** — Type a name in the text field (default: `input_1`). This becomes the variable name in your code. * **Type** — Select from the dropdown: `Text`, `File`, `Image`, and more. * Click **+ Add** to add more inputs. Click the red **−** button to remove an input. Connect each input's left-side handle to the output of an upstream node. #### Step 4: Write Your Code The code editor is pre-populated with boilerplate showing how to access inputs and set the output: ```python theme={"languages":{}} # Access your inputs as variables (e.g., input_1) # Use the 'output' variable to set the result output = input_1 ``` Replace the boilerplate with your custom logic. Your code can access all defined inputs as variables by name. #### Step 5: Define Outputs Each output has a name and a type: * **Name** — Type a name in the text field (default: `output_1`). Your code must assign a value to this variable. * **Type** — Select from the dropdown to match the data your code returns. * Click **+ Add** to add more outputs. Click the red **−** button to remove one. Connect each output's right-side handle to downstream nodes. Code node connected to input and output nodes in a workflow #### Step 6: Test the Workflow Click **Run** to execute the workflow. The Code Execution node runs your code with the upstream input values and passes the output to downstream nodes. ### Settings | Setting | Type | Default | Description | | ------------- | ----------- | -------------------- | --------------------------------------------------- | | `Language` | Toggle | Python | Python or JavaScript. | | `Input Name` | Text | input\_1 | Name of each input parameter. Add more with + Add. | | `Input Type` | Dropdown | Text | Type of each input (Text, File, Image, etc.). | | `Code` | Code editor | Boilerplate template | The Python or JavaScript code to execute. Required. | | `Output Name` | Text | output\_1 | Name of each output parameter. Add more with + Add. | | `Output Type` | Dropdown | Text | Type of each output (Text, File, Image, etc.). | ### Best Practices * **Match input/output types to connected nodes.** Ensure the types you select for inputs and outputs match what upstream nodes produce and downstream nodes expect. A type mismatch causes runtime errors. * **Use descriptive variable names.** Rename `input_1` to something meaningful like `raw_json` or `account_balance`. This makes the code more readable and the node connections easier to understand on the canvas. * **Test with small inputs first.** Before connecting a large data workflow, test your code with a simple hardcoded input to verify the logic works correctly. * **Return the correct output variable.** Your code must assign a value to the exact variable name defined in the output field. If your output is named `result`, your code must set `result = ...`. * **Keep external dependencies minimal.** Stick to standard library functions when possible. If your code requires external packages, verify they are available in the VectorShift execution environment. ### Related Templates Queries and interprets Snowflake data warehouse data to deliver actionable business insights. Analyzes earnings call transcripts for sentiment, key themes, and forward-looking signals. Identifies and analyzes foreign exchange arbitrage opportunities across markets and instruments. Processes and validates capital account statements for accuracy and investor reporting. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Cohere LLM Source: https://docs.vectorshift.ai/nodes/cohere/overview Generate text responses using Cohere's Command models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Cohere LLM node connects your workflows to Cohere's Command family of language models. Use it to generate text responses, summarize documents, or produce structured outputs — for example, condensing lengthy compliance reports into executive summaries, classifying transaction descriptions by category, or generating natural-language explanations of quantitative model outputs. ## Core Functionality * Generate text completions and conversational responses using Cohere Command models * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `command-r-06-2024`) Select from available Cohere models. Click **Dropdown** to view all options * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own Cohere API key instead of VectorShift's shared key * `Api Key` — (String) Your Cohere API key. Required when `Use Personal Api Key` is enabled — the node will show a validation error if left blank * `JSON Schema` — (String) JSON schema to enforce structured output format. Only visible when `JSON Response` is enabled in the settings panel \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Cohere LLM node in workflows lets you place a Command model directly on the canvas, wire inputs and outputs to other nodes, and configure model behavior through the settings panel. Cohere models are well-suited for retrieval-augmented generation (RAG) and enterprise search workflows. ## Use Cases * **Compliance report summarization** — Condense lengthy regulatory filings or audit reports into concise executive summaries, highlighting key findings and action items. * **Transaction categorization** — Classify financial transactions by type, merchant category, or risk level using natural language understanding. * **Client Q\&A from documents** — Build knowledge-grounded chatbots that answer client questions about portfolio performance, fund prospectuses, or policy documents. * **Data extraction from filings** — Extract structured fields from unstructured financial documents using JSON mode — for example, pulling key terms from loan agreements. * **Multilingual financial content** — Generate or translate financial communications across languages for global client bases using Cohere's multilingual capabilities. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Cohere** node onto the canvas. Cohere node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. 4. **Select a model.** Use the `Model` dropdown to choose a Cohere model. Available options include `command-r-06-2024`, `command-r-08-2024`, `command-r-plus-08-2024`, and `command-nightly`. Cohere node showing the Model dropdown 5. **Use a personal API key (optional).** Toggle `Use Personal Api Key` to **Yes** to use your own Cohere API key. An `Api Key` field appears — paste your key there. The node will display a validation error ("Api Key field is Required!") if the field is left blank. 6. **Open settings.** Click the **gear icon** (⚙) on the node to open the settings panel, where you can configure token limits, temperature, retry behavior, safety features, and more. Cohere node settings panel 7. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes. Use `tokens_used`, `input_tokens`, `output_tokens`, and `credits_used` for monitoring. Cohere node connected to upstream and downstream nodes 8. **Run your workflow.** Execute the workflow. The Cohere node processes its inputs and returns the generated response along with usage metrics. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | Cohere | The LLM provider. | | `Max Tokens` | Integer | 64096 | Maximum number of input + output tokens the model will process per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning the model applies to its response. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values produce more diverse outputs; lower values produce more deterministic responses. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. Range: 0–1. | | `Stream` | Boolean | Off | Stream responses token-by-token instead of returning the full response at once. | | `JSON Response` | Boolean | Off | Return output as structured JSON. When enabled, a `JSON Schema` input appears for optional schema enforcement. | | `Show Sources` | Boolean | Off | Display source documents used for the response. Useful when combining with knowledge base inputs. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. If the model receives toxic content, it responds with a respectful message instead. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max # of re-try` | Integer | — | Maximum number of retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input before sending to the model. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `SSN` | Boolean | Off | Detect and redact Social Security numbers from input. | | `Credit Card Info` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Guardrail Status` | Dropdown | — | Controls whether guardrail status is included in the output. | ## Best Practices * **Leverage Cohere for RAG workflows.** Cohere Command models are optimized for retrieval-augmented generation — pair the Cohere node with a Knowledge Base Reader for accurate, grounded responses to financial queries. * **Use JSON mode for structured extraction.** When pulling data from financial documents, enable `JSON Response` and provide a schema to ensure consistent output across runs. * **Monitor token usage.** Connect `tokens_used` and `credits_used` outputs to tracking nodes for cost visibility, especially when processing large document batches. * **Enable Safe Context Token Window for variable-length inputs.** Prevents token-limit errors when processing documents of unpredictable size. * **Apply PII detection for sensitive data.** Enable relevant PII toggles (including SSN) when processing client financial records or personal information. * **Use streaming for interactive interfaces.** Enable streaming when the Cohere node powers a client-facing chatbot for a more responsive user experience. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Condition Source: https://docs.vectorshift.ai/nodes/condition/overview Branch workflow execution based on conditional logic with support for multiple paths and operators. Add it in Python with `pipeline.add(name="...").condition(...)`. See the SDK reference. The Condition node lets you branch your workflow into different execution paths based on conditional logic. Define rules using operators like "contains," "equals," "is empty," and more — and route data to the correct downstream path based on whether those conditions are met. Use it to build decision trees in financial workflows, filter records by status, or apply different processing logic depending on input values. ## Core Functionality * Evaluates one or more conditions per path using configurable operators * Supports multiple paths — each path can have its own set of conditions * Conditions within a path can be combined with logical AND * Includes a default/fallback path for inputs that don't match any condition * Does not produce data outputs — downstream nodes reference previous nodes' output fields directly ## Tool Inputs * `Input` \* — The data source to evaluate. Select from a dropdown of available upstream node outputs. Required. * `Key` — The specific key or field within the input to evaluate. Text. Use this when the input is structured data (e.g., JSON) and you need to check a specific property. * `Operator` \* — The comparison operator to apply. Required. Dropdown with the following options: * `Check contains` — Input contains the specified value * `Check does not contain` — Input does not contain the specified value * `Check does not equal` — Input does not equal the specified value * `Check does not begin` — Input does not begin with the specified value * `Check does not end with` — Input does not end with the specified value * `Check is less than or equal` — Input is less than or equal to the value * `Check is less than` — Input is less than the value * `is True` — Input evaluates to true * `is False` — Input evaluates to false * `is Empty` — Input is empty or null * `is not Empty` — Input is not empty * `List does not contain` — A list input does not contain the specified value * `List contains list` — A list input contains all items in the specified list * `Value` — The value to compare against. Text. Not required for unary operators (`is True`, `is False`, `is Empty`, `is not Empty`). \* *Required field* ## Tool Outputs The Condition node does not produce data outputs. It evaluates which path to execute based on the conditions. To access data in downstream nodes, reference the output fields of nodes that ran before the Condition node. *** ### Overview In workflows, the Condition node sits between upstream data-producing nodes and multiple downstream branches. It evaluates each path's conditions in order and activates the first matching path. If no path matches, the default path executes. Use it to implement if/else logic — for example, routing approved transactions to one branch and flagged transactions to another. ### Use Cases * Route transactions above a threshold to a review workflow and below to auto-approval * Filter incoming documents by type (invoice vs. receipt vs. statement) for different extraction workflows * Check whether an API response contains an error field and branch to error handling * Validate that required fields are not empty before proceeding with data processing * Branch based on customer tier (premium vs. standard) to apply different pricing logic * Direct flagged compliance records to manual review and clean records to automated processing ### How It Works #### Step 1: Add the Condition Node In the workflow canvas, click the **Logic** tab in the node palette and click **Condition**. Drag it onto the canvas. Workflow node palette showing the Logic tab with Condition highlighted #### Step 2: Configure Path 0 Path 0 is the first condition path. Each row in a path defines one condition: 1. Select an **Input** from the dropdown — this connects to an upstream node's output. 2. Optionally enter a **Key** if the input is structured data and you want to check a specific field. 3. Choose an **Operator** from the dropdown (e.g., `Check contains`, `is Empty`, `Check is less than`). 4. Enter a **Value** to compare against (not needed for unary operators like `is True` or `is Empty`). To add more conditions within the same path, click **And** to add another condition row. All conditions in a path must be true for the path to activate (logical AND). Click **+ Add Clause** to add another condition row to the current path. #### Step 3: Configure Additional Paths **Path 1** serves as the default/fallback path (marked with **+ Not / Default**). It activates when no other path's conditions are met. You can also add conditions to Path 1 to make it conditional rather than a catch-all. Click **+ Add Path** at the bottom to add more paths (Path 2, Path 3, etc.). Each additional path gets its own set of condition rows. #### Step 4: Select Operators Click the **Operator** dropdown to see all available comparison operators. The full list includes string checks (contains, begins, ends), numeric comparisons (less than, less than or equal), boolean checks (is True, is False), emptiness checks (is Empty, is not Empty), and list operations (List does not contain, List contains list). #### Step 5: Connect Downstream Nodes Each path creates a separate output handle on the right side of the node. Connect each handle to the downstream nodes that should execute for that path. Downstream nodes reference the output fields of nodes that ran *before* the Condition node. Condition node on canvas with multiple paths connected to different downstream branches #### Step 6: Run the Workflow Click **Run** at the bottom of the node to test. The Condition node evaluates each path's conditions in order and activates the first match. ### Settings | Setting | Type | Default | Description | | -------------- | -------- | ------- | ---------------------------------------------------------------- | | `Input` | Dropdown | — | The upstream node output to evaluate. Required. | | `Key` | Text | — | The specific field within structured input to check. | | `Operator` | Dropdown | — | The comparison operator. Required. See full list in Tool Inputs. | | `Value` | Text | — | The value to compare against. Not needed for unary operators. | | `And` | Button | — | Adds a logical AND condition within the same path. | | `+ Add Clause` | Button | — | Adds another condition row to the current path. | | `+ Add Path` | Button | — | Adds a new path with its own conditions. | ### Best Practices * **Use Path 1 as a catch-all.** Keep the default path (Path 1 / Not / Default) as a fallback for any inputs that don't match your defined conditions. This prevents data from silently dropping out of the workflow. * **Order paths by priority.** The Condition node evaluates paths in order and activates the first match. Put your most specific conditions in Path 0 and broader conditions in later paths. * **Combine conditions with And for precision.** Use multiple conditions within a single path to create precise filters — for example, "amount is greater than 10000 AND status equals pending." * **Use is Empty / is not Empty for validation.** Before processing, check that required fields are not empty. This prevents downstream errors from missing data. * **Keep condition counts manageable.** If you need many conditions, consider chaining multiple Condition nodes or using AI Routing for intent-based classification instead of manual rules. ### Related Templates Classifies capital expenditure items against accounting standards and internal policies. Automatically categorizes and tags incoming documents based on content and type. Assesses risk levels in incoming applications using scoring models and policy rules. Reviews and routes refund or expense requests based on policy rules and approval thresholds. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Create Knowledge Base Source: https://docs.vectorshift.ai/nodes/create-knowledge-base/overview Dynamically create a new knowledge base with configured chunking, embedding, and processing options. Add it in Python with `pipeline.add(name="...").knowledge_base_create(...)`. See the SDK reference. The Create Knowledge Base node lets you programmatically provision a new knowledge base with full control over chunking strategy, embedding model, and document processing settings. Use it to automate knowledge base creation as part of onboarding workflows — for example, spinning up a dedicated knowledge base per client, or creating topic-specific knowledge bases from incoming document batches. ## Core Functionality * Create a new knowledge base on-the-fly with a specified name and configuration * Configure chunking parameters (size, overlap, splitter method, segmentation method) to control how documents are broken into retrievable segments * Select the embedding model and file processing model used for the knowledge base * Optionally enable hybrid mode, document analysis, and advanced parsing options * Return a knowledge base reference that downstream nodes or tools can use to load documents into ## Tool Inputs * `Name` \* — **Required** · Text · The name of the knowledge base to create. * `File Processing Model` — Dropdown · Default: `default` · The file processing implementation used for parsing documents (e.g., Docparser). *(Advanced setting)* * `Embedding Model` — Dropdown · Default: `voyageai/voyage-4-lite` · The embedding model used to generate vector representations. Format: `provider/model`. *(Advanced setting)* * `Chunk Size` — Integer · Default: `400` · Min: `1`, Max: `4096` · The size of text chunks stored in the knowledge base. *(Advanced setting)* * `Chunk Overlap` — Integer · Default: `0` · Min: `0`, Max: `4095` · The number of overlapping characters between consecutive chunks. *(Advanced setting)* * `Splitter Method` — Dropdown · Default: `Markdown` · Options: `Sentence`, `Markdown`, `Dynamic` · Strategy for grouping segmented text into final chunks. *(Advanced setting)* * `Segmentation Method` — Dropdown · Default: `Words` · Options: `Words`, `Sentences`, `Paragraphs` · The method used to break text into units before chunking. Appears when Splitter Method is set to `Dynamic`. *(Advanced setting)* * `Analyze Documents` — Boolean · Default: `false` · When enabled, analyzes document contents and enriches them during parsing. *(Advanced setting)* * `Hybrid Mode` — Boolean · Default: `false` · Whether to create a hybrid knowledge base that combines vector and keyword search. *(Advanced setting)* * `Apify Key` — Text · Optional · Apify API key for scraping URLs. *(Advanced setting)* \* indicates a required field. ## Tool Outputs * `knowledge_base` — Knowledge Base · A reference to the newly created knowledge base. Use this output to connect to downstream nodes such as Knowledge Base Loader or Sync Knowledge Base. ## Overview When added as a tool inside an agent, Create Knowledge Base allows the agent to provision new knowledge bases during a conversation. The agent can create knowledge bases on demand — for example, when a user requests a new project workspace or when incoming documents need to be organized into a fresh collection. ## Use Cases * **Client onboarding automation** — An agent creates a dedicated knowledge base for each new client, named after the client's account, ready to receive their compliance documents. * **Dynamic research collections** — A research agent spins up a new knowledge base per investment thesis or market sector when a user starts a new analysis project. * **Regulatory document organization** — An agent automatically creates separate knowledge bases for different regulatory frameworks (SEC, MiFID II, Basel III) as documents are classified. * **Portfolio-specific knowledge stores** — An agent creates a knowledge base per portfolio to store and retrieve relevant analyst reports, earnings transcripts, and market data. * **Audit trail setup** — A compliance agent creates timestamped knowledge bases for each audit cycle to maintain clean separation of evidence collections. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **Knowledge** category. Select **Create Knowledge Base** to add it as a tool. 2. **Configure the tool** — The primary field is `Knowledge Base Name`. You can either leave it open for the agent to fill dynamically based on conversation context, or lock it to a fixed value. Click the sparkle icon to switch fields between dynamic (agent-determined) and static (fixed) mode. Create Knowledge Base tool configuration panel showing fields with sparkle icon to toggle between dynamic and static values 3. **Configure advanced settings** — Optionally adjust `Chunk Size`, `Chunk Overlap`, `Splitter Method`, `File Processing Model`, `Embedding Model`, `Analyze Documents`, and `Hybrid Mode`. These are typically locked to fixed values since they represent technical configuration rather than conversational parameters. 4. **Write a Tool Description** — Describe when and why the agent should create a knowledge base. Example: *"Use this tool to create a new knowledge base when the user requests a new project workspace. Name it after the project."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Creates the knowledge base immediately without confirmation. * **Require User Approval** — Pauses for the user to confirm before creating. * **Let Agent Decide** — The agent determines whether to ask for approval based on context. Create Knowledge Base tool requiring user approval, showing the approval dialog with knowledge base configuration fields 6. **Test the tool** — In the chat interface, ask the agent to create a knowledge base and verify it appears in your knowledge base list. ## Settings * `Knowledge Base Name` — Text · Default: none · The name for the new knowledge base. Can be filled by the agent or locked to a fixed value. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. **Advanced Settings:** * `File Processing Model` — Dropdown · Default: `default` · Document parsing implementation. * `Embedding Model` — Dropdown · Default: `voyageai/voyage-4-lite` · Vector embedding model. * `Chunk Size` — Integer · Default: `400` · Text chunk size (1–4096). * `Chunk Overlap` — Integer · Default: `0` · Overlap between chunks (0–4095). * `Splitter Method` — Dropdown · Default: `Markdown` · Chunking strategy (Sentence, Markdown, Dynamic). * `Analyze Documents` — Boolean · Default: `false` · Enable document content analysis. * `Hybrid Mode` — Boolean · Default: `false` · Enable hybrid vector + keyword search. * `Apify Key` — Text · Optional · API key for URL scraping via Apify. ## Best Practices * **Use descriptive names** — Let the agent generate meaningful names that include client identifiers, dates, or project codes for easy retrieval later. * **Lock chunking parameters** — Set `Chunk Size`, `Chunk Overlap`, and `Splitter Method` to fixed values appropriate for your document types. Financial documents with tables work well with Markdown splitter. * **Require approval for production use** — Set Auto Run to "Require User Approval" when creating knowledge bases in production environments to prevent accidental proliferation. * **Pair with Knowledge Base Loader** — After creating a knowledge base, chain it with a Knowledge Base Loader tool to immediately populate it with documents. * **Match embedding models to your retrieval workflow** — Ensure the embedding model you select here matches what your downstream Semantic Search or Knowledge Base Reader nodes expect. ## Related Templates Centralized searchable repository of investment committee memos for quick reference. A configurable chatbot that connects to custom APIs to retrieve and present dynamic data. Answers employee questions about internal policies and flags potential compliance issues. Handles investor inquiries related to portfolios, statements, and fund performance. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Create Knowledge Base node provisions a new knowledge base as a workflow step. The node outputs a knowledge base reference that can be wired into downstream nodes — such as Knowledge Base Loader to populate it with documents, or Sync Knowledge Base to keep it updated. This is ideal for automated workflows that need to create and populate knowledge bases without manual intervention. ## Use Cases * **Batch client setup** — A workflow iterates over a list of new client records and creates a dedicated knowledge base for each, pre-configured with the appropriate chunking and embedding settings. * **Document ingestion workflow** — A workflow receives uploaded documents, creates a knowledge base named after the document batch, and immediately loads the documents into it. * **Scheduled knowledge refresh** — A triggered workflow creates a new knowledge base version on a schedule, loads updated documents, and swaps it in for the previous version. * **Multi-tenant data isolation** — A workflow creates isolated knowledge bases per tenant to ensure document separation in a multi-client environment. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Create Knowledge Base** onto the canvas. Node palette showing the Knowledge category with KB Actions submenu Create Knowledge Base node being dragged onto the canvas 2. **Set the name** — Enter a name for the knowledge base in the `Name` field. This field is required — the node will show a validation error if left empty. You can also connect a text input from an upstream node to set the name dynamically. 3. **Configure processing settings** — Expand the settings to configure `File Processing Model`, `Embedding Model`, `Chunk Size`, `Chunk Overlap`, `Splitter Method`, and other options as needed. Create Knowledge Base node settings panel showing Name, Chunk Size, Chunk Overlap, Splitter Method, and other configuration options 4. **Connect the output** — Wire the `knowledge_base` output to downstream nodes that need the new knowledge base reference (e.g., Knowledge Base Loader, Sync Knowledge Base). Create Knowledge Base node connected to upstream and downstream nodes on the canvas 5. **Run the workflow** — Execute the workflow. The node creates the knowledge base and passes the reference downstream. ## Settings * `Name` — Text · **Required** · The name of the knowledge base to create. **Advanced Settings:** * `File Processing Model` — Dropdown · Default: `default` · The document parsing implementation (e.g., Docparser). * `Embedding Model` — Dropdown · Default: `voyageai/voyage-4-lite` · The embedding model for vector generation. * `Vector DB Provider` — Text · Default: `qdrant` · The vector database backend. * `Collection Name` — Text · Default: `voyage-4-lite` · The collection name in the vector database. * `Embedding Provider` — Text · Default: `voyageai` · The embedding provider. * `Precision` — Text · Default: `Float16` · Vector precision setting. * `Sharded` — Boolean · Default: `true` · Whether to shard the knowledge base. * `Chunk Size` — Integer · Default: `400` · Text chunk size (1–4096). * `Chunk Overlap` — Integer · Default: `0` · Overlap between chunks (0–4095). * `Splitter Method` — Dropdown · Default: `Markdown` · Options: Sentence, Markdown, Dynamic. * `Segmentation Method` — Dropdown · Default: `Words` · Options: Words, Sentences, Paragraphs. Visible when Splitter Method is Dynamic. * `Analyze Documents` — Boolean · Default: `false` · Analyze and enrich document contents during parsing. * `Hybrid Mode` — Boolean · Default: `false` · Create a hybrid knowledge base combining vector and keyword search. * `Apify Key` — Text · Optional · Apify API key for URL scraping. ## Best Practices * **Always provide a name** — The `Name` field is required and the node will fail validation without it. Use upstream text nodes to generate dynamic names when creating multiple knowledge bases. * **Use consistent embedding models** — Ensure the embedding model matches your organization's standard so that cross-knowledge-base queries produce consistent results. * **Set chunk size based on content type** — For dense financial documents, smaller chunk sizes (200–400) improve retrieval precision. For narrative content, larger chunks (400–800) preserve context. * **Enable document analysis for complex PDFs** — Turn on `Analyze Documents` when working with financial reports that contain tables, charts, and mixed layouts. * **Chain with loader nodes** — Create Knowledge Base only provisions the empty knowledge base. Always follow it with a Knowledge Base Loader or file upload step to populate it. ## Related Templates Centralized searchable repository of investment committee memos for quick reference. A configurable chatbot that connects to custom APIs to retrieve and present dynamic data. Answers employee questions about internal policies and flags potential compliance issues. Handles investor inquiries related to portfolios, statements, and fund performance. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Create Session Source: https://docs.vectorshift.ai/nodes/create-session/overview Create a new session with an agent and participants from within a workflow. Add it in Python with `pipeline.add(name="...").create_session(...)`. See the SDK reference. create session select agent The Create Session node creates a new conversational session with a specified agent from within a workflow. Use it to programmatically spin up agent chat sessions — for example, initializing a client onboarding session when a new lead comes in, starting an automated compliance review conversation, or creating a support session that a human agent can later join. ## Core Functionality * Creates a new agent session programmatically from within a workflow * Links the session to a specific agent selected from your account * Returns a session ID that downstream nodes (Post Message, Read Messages) can use to interact with the session * Supports optional session naming for easier identification ## Tool Inputs * `Session Name` — Text. Optional. A human-readable name for the session. Placeholder: "Optional session name". * `Agent` \* — Agent. Required. The agent to use for the session. Select from existing agents in your account via a searchable dropdown, or switch to Variable mode to pass an agent reference dynamically. Includes a **+ New Agent** button to create a new agent inline. \* *Required field* ## Tool Outputs * `session_id` — Text. The unique identifier of the created session. Use this to post messages or read messages in downstream nodes. *** ### Overview In workflows, the Create Session node initializes a new agent conversation that other Chat nodes can interact with. It outputs a `session_id` that you pass to Post Message and Read Messages nodes to send messages to and receive responses from the agent. This enables workflows that orchestrate multi-turn agent conversations programmatically — useful for automated testing, batch processing, or triggering agent interactions from external events. ### Use Cases * Automatically create a client onboarding session when a new CRM record is created, then post introductory questions via Post Message * Spin up a compliance review session for each new transaction, feed the transaction details, and read the agent's assessment * Orchestrate automated QA testing of an agent by creating sessions and posting scripted test messages * Initialize a financial analysis session from a trigger node when new market data arrives, then read the agent's insights * Create named sessions for each department's weekly reporting workflow so conversations are easy to track and audit ### How It Works #### Step 1: Add the Create Session Node In the workflow canvas, click the **Chat** tab in the node palette and click **Create Session**. Drag it onto the canvas. create session drag into canvas #### Step 2: Select an Agent In the `Agent` field, use the searchable dropdown to select an existing agent from your account. This field is required — the node shows a validation error ("Agent field is required") if left empty. You can toggle between **Select** mode (pick from a dropdown) and **Variable** mode (pass an agent reference from an upstream node). The **+ New Agent** button lets you create a new agent directly from within the node. #### Step 3: Set a Session Name (Optional) Enter a name in the `Session Name` field to give the session a human-readable label. This is optional but helpful for tracking sessions in logs or dashboards. #### Step 4: Connect Downstream Nodes create session connect with nodes Connect the `session_id` output to downstream Post Message or Read Messages nodes. These nodes use the session ID to interact with the newly created agent session. #### Step 5: Test the Workflow Click **Run** to test. The node creates a session and outputs the session ID. Verify that downstream nodes can successfully post to and read from the session. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ----------- | ------- | --------------------------------------------------------------------------- | | `Session Name` | Text | — | Optional human-readable name for the session. | | `Agent` | Agent | — | The agent to use. Required. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. **Advanced setting.** | | `Dependencies` | List\ | — | Specify node dependencies to control execution order. **Advanced setting.** | ### Best Practices * **Name sessions descriptively.** Use session names that include context (e.g., client name, date, workflow type) so sessions are easy to find and audit later. * **Pair with Post Message and Read Messages.** Create Session alone only initializes the conversation — use Post Message to send input and Read Messages to retrieve the agent's responses. * **Use Variable mode for dynamic agent selection.** When building workflows that route to different agents based on conditions (e.g., different departments), switch the Agent field to Variable mode and connect it to upstream logic. * **Add dependencies for execution ordering.** If the session must be created after another node completes (e.g., after fetching client data), use the Dependencies advanced setting to enforce the correct order. * **Store session IDs for follow-up workflows.** If you need to continue a conversation later (e.g., in a subsequent workflow run), save the session ID output to a database or variable for reuse. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Handles investor inquiries related to portfolios, statements, and fund performance. Answers employee questions about internal policies and flags potential compliance issues. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Create Workspace Source: https://docs.vectorshift.ai/nodes/create-workspace/overview Create a new portal workspace, upload files, and share access with users. Add it in Python with `pipeline.add(name="...").create_workspace(...)`. See the SDK reference. The Create Workspace node creates a new workspace within a portal, optionally uploading files and sharing access with specified users via email. Use it to automate portal provisioning — for example, spinning up a client workspace with pre-loaded documents as part of an onboarding workflow, or creating project-specific workspaces that are shared with the relevant team members. ## Core Functionality * Create a new workspace within an existing portal * Upload files to the workspace at creation time * Share the workspace with users by email * Return workspace metadata for downstream reference ## Tool Inputs * `Portal` \* — **Required** · Portal selector · The portal to create the workspace in. * `Workspace Name` \* — **Required** · Text · The name of the new workspace. * `Files` — File list · Optional · Files to upload to the workspace. Use **+ Add Item** to add multiple files. * `Shared Emails` — Text list · Optional · Email addresses of users to share the workspace with. Use **+ Add Item** to add multiple emails. \* indicates a required field. ## Tool Outputs * Workspace metadata outputs including workspace identifiers and configuration details are available via the Outputs panel. ## Overview In workflows, the Create Workspace node provisions a new portal workspace as a workflow step. You can pre-load it with files and share it with users — all in a single automated operation. This is ideal for client onboarding workflows, project setup automations, or any workflow that needs to create isolated workspaces within a portal. ## Use Cases * **Client onboarding** — A workflow creates a dedicated workspace for a new client, uploads their initial documents, and shares access with the client's email address. * **Project provisioning** — A workflow creates a workspace per project, pre-loaded with templates and shared with team members. * **Automated workspace setup** — A triggered workflow creates workspaces on a schedule or in response to form submissions, with pre-configured files and access. * **Multi-tenant content delivery** — A workflow creates isolated workspaces for different users or teams, each with their own set of documents and permissions. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Create Workspace** onto the canvas. Create Workspace node being dragged onto the canvas 2. **Select the portal** — Use the `Portal` selector to choose the portal where the workspace will be created. This field is required. 3. **Set the workspace name** — Enter a name in the `Workspace Name` field or connect an upstream text node. This field is required. 4. **Add files** *(optional)* — Use **+ Add Item** to add files that should be uploaded to the workspace at creation time, or connect upstream file outputs. 5. **Add shared emails** *(optional)* — Use **+ Add Item** to specify email addresses of users who should receive access to the workspace. 6. **Configure dependencies** *(optional)* — Use the Dependencies tab if this node depends on other nodes completing first. 7. **Connect outputs** — Wire workspace outputs to downstream nodes if needed. Create Workspace node connected to upstream and downstream nodes on the canvas 8. **Run the workflow** — Execute the workflow. The node creates the workspace, uploads files, and shares access. ## Settings * `Portal` — Portal selector · **Required** · The target portal. * `Workspace Name` — Text · **Required** · The name for the new workspace. * `Files` — File list · Optional · Files to upload to the workspace. * `Shared Emails` — Text list · Optional · Email addresses for sharing access. ## Best Practices * **Use dynamic workspace names** — Connect upstream text nodes to generate unique workspace names that include client names, project IDs, or dates. * **Pre-load essential files** — Upload onboarding documents, templates, or reference materials at workspace creation time so users have everything they need immediately. * **Validate email addresses** — Ensure shared email addresses are valid before passing them to the node to avoid failed sharing operations. * **Use dependencies for ordered execution** — If the files to upload come from upstream processing steps, use the Dependencies tab to ensure those steps complete before workspace creation. ## Related Templates Handles common customer inquiries and support tickets through conversational AI. Answers employee questions about internal policies and flags potential compliance issues. Handles investor inquiries related to portfolios, statements, and fund performance. Assists banking customers with account inquiries, transactions, and product questions. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Custom LLM Source: https://docs.vectorshift.ai/nodes/custom/overview Connect to any OpenAI-compatible model provider or locally hosted LLM in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Custom LLM node lets you connect your workflows to any model provider that supports the OpenAI Chat API format, or to a locally hosted LLM. Use it to access specialized models from providers like Together AI, Replicate, or Fireworks — or connect to a local model running via LM Studio or Ollama — enabling use cases such as running proprietary fine-tuned models for financial analysis, evaluating open-source models for cost optimization, or prototyping with local models before scaling to production. ## Core Functionality * Connect to any LLM provider compatible with the OpenAI Chat API format * Access local models via LM Studio, Ollama, or other local serving frameworks * Specify a custom base URL, model name, and API key * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (String (Text input)) The model identifier to use. This is a free-text field — enter the exact model name as specified by your provider * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to provide your own API key * `Base URL` \* — (String) The base URL of your model provider (e.g., `https://api.together.xyz` or `http://localhost:1234/v1`) * `Api Key` — (String) Your API key for the model provider. Required when `Use Personal Api Key` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Custom LLM node in workflows lets you connect to any OpenAI-compatible model endpoint by specifying a base URL, model name, and API key. This provides maximum flexibility — you can use commercial API providers, privately hosted models, or local development servers, all within the same workflow canvas. ## Use Cases * **Fine-tuned model deployment** — Connect to a custom fine-tuned model hosted on Together AI or Replicate that's been trained on your organization's financial documents and terminology. * **Local model prototyping** — Test and iterate with locally hosted models via LM Studio or Ollama before committing to a cloud provider for production workloads. * **Cost-optimized batch processing** — Route high-volume, low-complexity tasks (like transaction tagging) to cost-effective open-source models while reserving premium models for complex analysis. * **Multi-provider evaluation** — Compare outputs from different model providers by swapping the base URL and model name to find the best quality-to-cost ratio for your financial workflows. * **Private infrastructure compliance** — Connect to models hosted within your organization's private infrastructure to meet data residency and security requirements. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Custom** node onto the canvas. Custom node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. 4. **Enter the model name.** In the `Model` field, type the exact model identifier as specified by your provider (e.g., `meta-llama/Llama-3-70b-chat-hf` for Together AI, or `local-model` for LM Studio). 5. **Set the Base URL.** Enter the base URL for your model provider in the `Base URL` field. Examples: * Together AI: `https://api.together.xyz` * Replicate: `https://api.replicate.com` * Local LM Studio: `http://localhost:1234/v1` 6. **Provide an API key (optional).** Toggle `Use Personal Api Key` to **Yes** and enter your provider's API key. For local models, you may use a placeholder key (e.g., `lm-studio`). 7. **Open settings.** Click the **gear icon** (⚙) on the node to configure token limits, temperature, retry behavior, and more. Custom node settings panel 8. **Connect outputs and run.** Wire the `response` output to downstream nodes. Execute the workflow to process inputs through your custom model endpoint. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | Custom | The LLM provider. | | `Max Tokens` | Integer | 128000 | Maximum number of input + output tokens the model will process per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning the model applies. Options: Default, Low, Medium, High. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values produce more diverse outputs; lower values produce more deterministic responses. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token instead of returning the full response at once. | | `Show Sources` | Boolean | Off | Display source documents used for the response. Useful when combining with knowledge base inputs. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. If the model receives toxic content, it responds with a respectful message instead. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max # of re-try` | Integer | — | Maximum number of retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input before sending to the model. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `Credit Card Info` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Guardrail Status` | Dropdown | — | Controls whether guardrail status is included in the output. | ## Best Practices * **Verify base URL format.** Ensure your base URL does not include a trailing slash and matches the provider's API documentation exactly. A common mistake is including extra path segments. * **Match model names precisely.** The model identifier must exactly match what the provider expects. Check your provider's model catalog for the correct string. * **Start with local models for prototyping.** Use LM Studio or Ollama during development to iterate quickly without incurring API costs, then swap to a cloud provider for production. * **Set appropriate Max Tokens.** Different custom models have vastly different context windows. Set `Max Tokens` to match your model's actual limit to avoid errors. * **Enable retry for unreliable endpoints.** If connecting to a self-hosted or development server, enable `Retry On Failure` with reasonable intervals to handle transient failures. * **Apply PII detection for client data.** Even when using private infrastructure, enable PII toggles as a defense-in-depth measure for workflows processing sensitive financial information. ## Related Templates A configurable chatbot that connects to custom APIs to retrieve and present dynamic data. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Data Collector Source: https://docs.vectorshift.ai/nodes/data-collector/overview Collect structured information from chatbot users by defining fields and auto-generating questions. Add it in Python with `pipeline.add(name="...").data_collector(...)`. See the SDK reference. The Data Collector node enables chatbots to gather structured information from users by asking targeted questions and extracting specific data fields from their responses. Use it to build intake forms within a conversation — for example, collecting client details for account opening, gathering incident information for a support ticket, or capturing financial data points for a loan application. ## Core Functionality * Defines a set of fields (with descriptions and examples) to collect from the user during a chat conversation * Uses an LLM to auto-generate contextual questions that guide the user through providing each field * Analyzes user responses against the defined fields to extract and validate collected data * Supports manual mode where collected data is passed to a downstream LLM for custom question generation ## Tool Inputs * `Query` \* — Text. Required. The user's message to be analyzed for data collection. Typically connected from the chatbot input. Supports variables via `{{}}` syntax. * `Auto Generate Questions` — Toggle. Default: `Yes` (on). When enabled, the node uses an LLM to automatically generate questions in successive order until all fields are collected. When disabled, the node outputs the collected data as a JSON-like object for a downstream LLM to handle question generation. * `Prompt` — Text. Optional. Specific instructions for how the LLM should collect the information. Supports variables via `{{}}` syntax. * `Field` — Text. The name of the data field to collect (e.g., "Name", "Email", "Account Number"). * `Description` — Text. A description of the field to help the LLM understand what to ask for. * `Example` — Text. An example value for the field to guide the LLM's question generation. data collector connect with nodes Fields are added as rows in a table. Click **+ Add Field** to add more fields. Each row can be deleted with the trash icon. \* *Required field* ## Tool Outputs * `question` — Text. The next question to be asked to the user. Only available when `Auto Generate Questions` is enabled. * `collected_data` — Text. The structured data collected so far. Only available when `Auto Generate Questions` is disabled. Format: `{'Field1': 'Collected_Data', 'Field2': 'Collected_Data'}`. *** ### Overview In workflows, the Data Collector node sits in a chatbot workflow and orchestrates a multi-turn data gathering flow. When Auto Generate Questions is enabled, it uses an LLM to ask the user for each defined field in sequence, analyzing their responses to determine what has been collected and what remains. The `question` output connects to the chatbot response, creating a guided conversation that collects all required information before proceeding. ### Use Cases * Collect client onboarding details (name, email, company, role) through a conversational chatbot before routing to account creation * Gather financial information (income, expenses, credit score range) for a loan pre-qualification chatbot * Build an IT support intake flow that collects incident type, severity, affected system, and description before creating a ticket * Capture trade details (instrument, quantity, price, counterparty) through a conversational interface for order entry * Collect KYC (Know Your Customer) information from clients through a guided chat experience ### How It Works #### Step 1: Add the Data Collector Node In the workflow canvas, click the **Chat** tab in the node palette and click **Data Collector**. Drag it onto the canvas. data collector drag into canvas #### Step 2: Connect the Query Input Connect the chatbot's user input to the `Query` field. This is the user's message that the node will analyze to extract data. This field is required — the node shows a validation error if left empty. #### Step 3: Define Fields to Collect In the fields table, add each piece of information you want to collect: * **`Field`** — The name of the data point (e.g., "Full Name"). * **`Description`** — What the field represents (e.g., "The user's legal full name"). * **`Example`** — A sample value (e.g., "John Smith"). Click **+ Add Field** to add more rows. Remove unwanted rows with the trash icon. #### Step 4: Configure Auto Generate Questions data collector settings Leave `Auto Generate Questions` toggled on (default) to let the node automatically generate and ask questions. If you prefer custom question logic, toggle it off and connect the `collected_data` output to a downstream LLM with your own prompting. #### Step 5: Add a Prompt (Optional) Use the `Prompt` field to give the LLM specific instructions on how to collect information — for example, "Be polite and professional. Ask one question at a time. If the user provides unclear information, ask for clarification." #### Step 6: Configure the LLM Provider (Optional) Click the settings icon to open the Settings panel. Adjust: * **`Provider`** — The LLM provider for question generation. Default: `OpenAI`. Options include OpenAI, Anthropic, Cohere, Perplexity, Google, Open Source, AWS, Azure, xAI, Groq, and Custom. * **`LLM model`** — The specific model to use. Default varies by provider. #### Step 7: Connect the Output Connect the `question` output to the chatbot's response output. When deployed, the chatbot will ask the auto-generated question, wait for the user's response, and loop back until all fields are collected. ### Settings | Setting | Type | Default | Description | | ------------------------------ | -------- | ------- | --------------------------------------------------------------------- | | `Query` | Text | — | The user's message to analyze. Required. | | `Auto Generate Questions` | Toggle | Yes | Automatically generate and ask questions for each field. | | `Prompt` | Text | — | Instructions for how the LLM should collect information. | | `Fields` | Table | — | Fields to collect with name, description, and example columns. | | `Provider` | Dropdown | OpenAI | The LLM provider for question generation. **Advanced setting.** | | `LLM model` | Dropdown | Varies | The specific model for question generation. **Advanced setting.** | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. **Advanced setting.** | ### Best Practices * **Write clear field descriptions and examples.** The LLM uses descriptions and examples to generate relevant questions — vague descriptions lead to vague questions. For a "Revenue" field, describe it as "Annual revenue in USD" with an example like "\$5,000,000". * **Use the Prompt field to set conversation tone.** For financial or compliance use cases, include instructions like "Maintain a professional tone" or "If the user declines to provide information, explain why it's needed." * **Limit fields to what's essential.** Long data collection flows increase drop-off. Collect only what's needed up front and gather optional details later. * **Pair with Chat Memory for context.** Connect a Chat Memory node upstream so the Data Collector's LLM can reference the full conversation when generating follow-up questions. * **Test with edge cases.** Try providing partial information, incorrect formats, or refusing to answer to verify that the LLM handles these gracefully. ### Related Templates Verifies customer identities and performs Know Your Customer checks for onboarding compliance. Handles common customer inquiries and support tickets through conversational AI. Auto-fills and reviews information security questionnaires using internal security documentation. Assists banking customers with account inquiries, transactions, and product questions. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Deep Research Source: https://docs.vectorshift.ai/nodes/deep-research/overview Perform advanced AI research and analysis with specialized deep research models. Add it in Python with `pipeline.add(name="...").deep_research(...)`. See the SDK reference. The Deep Research node performs in-depth AI research and analysis using specialized models with built-in web search and tool-use capabilities. Use it to conduct comprehensive research on complex topics — for example, compiling competitive landscape reports for investment due diligence, synthesizing regulatory developments across multiple jurisdictions, or producing detailed market analysis reports that would otherwise require hours of manual research. ## Core Functionality * Perform multi-step research using specialized deep research models with built-in web search * Process research queries and custom instructions for targeted analysis * Maintain conversation context across sequential research tasks * Stream research output in real time for long-running analyses * Track token usage and credit consumption per research run * Return structured metadata including response IDs, timestamps, and error details * Support multiple providers including OpenAI, Azure, Anthropic, and Google ## Tool Inputs * `Input` — (String) The research query or data to analyze. Accepts free text or references to other node outputs via `{{variable}}` syntax * `Instructions` — (String) Specific instructions for the research task — use this to guide the model's research focus, depth, and output format * `Model` \* — (Enum (Dropdown), default: `o3-deep-research`) Select from available deep research models. Options vary by provider * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own API key instead of VectorShift's shared key * `Api Key` — (String) Your API key. Only visible when `Use Personal Api Key` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The research output and findings * `conversation` — (String) The updated conversation including the research response — useful for chaining sequential research tasks * `id` — (String) The unique ID of the research response * `created_at` — (String) Timestamp when the research was completed * `incomplete_details` — (String) Details about any incomplete aspects of the research * `error` — (String) Error message if the research failed * `tokens_used` — (Integer) Total number of tokens consumed during research * `input_tokens` — (Integer) Number of input tokens used * `output_tokens` — (Integer) Number of output tokens generated * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Deep Research node in workflows lets you place a specialized research model on the canvas that can autonomously search the web, synthesize information from multiple sources, and produce comprehensive research reports. Unlike standard LLM nodes, this node is designed for complex, multi-step research tasks where the model needs to gather and analyze information before responding. ## Use Cases * **Investment due diligence** — Research a target company's financials, market position, competitive landscape, and regulatory history to produce a comprehensive due diligence report. * **Regulatory monitoring** — Track and synthesize recent regulatory developments across jurisdictions — for example, summarizing new SEC guidance, EU MiFID updates, or APAC compliance changes. * **Market analysis reports** — Generate detailed market analysis covering sector trends, key players, recent deals, and forward-looking indicators for portfolio strategy discussions. * **Competitive intelligence** — Research competitor product launches, pricing changes, partnership announcements, and financial performance to inform strategic planning. * **Incident research** — Investigate the background, timeline, and implications of market events (e.g., a flash crash, major earnings miss, or regulatory action) by synthesizing web sources. * **Thematic research** — Explore emerging themes like AI in fintech, ESG scoring methodologies, or digital asset regulation by aggregating insights from multiple sources. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Deep Research** node onto the canvas. It appears as "OpenAI Deep Research" by default. 2. **Enter your research query.** In the `Input` field, enter the research question or topic. You can type directly or reference outputs from upstream nodes using `{{variable}}` syntax — for example, `{{input_0.text}}`. 3. **Provide research instructions (optional).** In the `Instructions` field, specify how the model should conduct the research — for example, what sources to prioritize, what format to use for the output, or what aspects to focus on. 4. **Select a model.** Use the `Model` dropdown to choose a deep research model. The default is `o3-deep-research`. Other available models include `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.5`, `gpt-4.1`, and variants. 5. **Open settings.** Click the **gear icon** (⚙) to open the settings panel. Here you can change the provider, configure token limits, enable streaming. Deep Research node settings panel 6. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes for the research findings. Use `conversation` to chain sequential research tasks. Monitor costs with `tokens_used` and `credits_used`. Deep Research node connected to upstream and downstream nodes 7. **Run your workflow.** Execute the workflow. The Deep Research node processes the query, conducts web-based research, and returns comprehensive findings along with metadata and usage metrics. ## Settings Settings are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ------------------ | ----------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | OpenAI | The provider for the deep research model. Options include OpenAI, Azure, Anthropic, and Google. | | `Model` | Dropdown | `o3-deep-research` | The deep research model to use. Available models vary by provider. | | `Use Personal Api Key` | Boolean | No | Toggle to use your own API key for the selected provider. | | `Max Output Tokens` | Integer | 128000 | Maximum number of tokens in the research output. | | `Stream Response` | Boolean | No | Stream the research response in real time instead of returning it all at once. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports on the node. | ## Best Practices * **Write specific research instructions.** The more targeted your `Instructions` field, the more relevant the research output. Instead of "Research Company X," try "Research Company X's Q4 2025 earnings, focusing on revenue growth, margin trends, and management guidance for 2026." * **Chain research tasks with conversation output.** Wire the `conversation` output of one Deep Research node into the input of another to build cumulative research across multiple steps — useful for multi-phase due diligence workflows. * **Monitor token usage carefully.** Deep research tasks can consume significantly more tokens than standard LLM calls due to multi-step reasoning and web search. Connect `tokens_used` and `credits_used` to monitoring nodes. * **Use the error and incomplete\_details outputs.** Wire these outputs to conditional logic nodes to handle cases where research is incomplete or encounters errors — important for production workflows that need reliability. * **Select the right model for the task.** Use `o3-deep-research` for comprehensive research tasks. For faster, lighter research, consider `gpt-5-mini` or `gpt-4.1` variants when available through your provider. * **Enable streaming for long research tasks.** Deep research can take longer than standard LLM calls. Enable streaming so users see incremental progress rather than waiting for the full result. ## Related Templates Identifies and analyzes foreign exchange arbitrage opportunities across markets and instruments. Analyzes earnings call transcripts for sentiment, key themes, and forward-looking signals. Matches organizations or individuals to relevant grants based on their profile and eligibility criteria. Automatically generates structured investment memos from deal data and research inputs. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # File Save Source: https://docs.vectorshift.ai/nodes/file-save/overview Save files to the VectorShift platform's Files tab for persistent storage. Add it in Python with `pipeline.add(name="...").file_save(...)`. See the SDK reference. The File Save node saves one or more files to the VectorShift platform, storing them under the Files tab. Use it to persist generated outputs — for example, saving a PDF report produced by your workflow, archiving processed documents for later retrieval, or storing exported CSV data files that users can download from the platform. ## Core Functionality * Save one or more files to the VectorShift platform's Files tab * Specify a custom file name for the saved file * Accept file inputs from any upstream node that outputs files * Return the saved file name(s) as output for downstream reference ## Tool Inputs * `File Name` \* — **Required** · Text · The name to save the file as on the platform. * `Files` \* — **Required** · List of Files · The file(s) to save. \* indicates a required field. ## Tool Outputs * `file_name` — List of Text · The name(s) of the saved file(s). ## Overview When added as a tool inside an agent, File Save allows the agent to persist files to the VectorShift platform during a conversation. The agent can save generated reports, processed documents, or any file output from other tools to the platform's Files tab, making them available for later access. ## Use Cases * **Report archival** — An agent generates a financial analysis report and saves it to the platform so the user can download it later. * **Document processing output** — An agent processes and transforms uploaded documents, then saves the cleaned versions to the platform. * **Export data files** — An agent compiles data into a CSV or Excel file and saves it for the user to retrieve. * **Backup conversation artifacts** — An agent saves important files produced during a conversation for persistent storage. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **VectorShift** category. Select **File Save** to add it as a tool. 2. **Configure input fields** — The `File Name` and `Files` fields can be left for the agent to fill dynamically based on conversation context, or locked to fixed values. 3. **Write a Tool Description** — Describe when the agent should save files. Example: *"Use this tool to save a generated report to the platform. Provide the file and a descriptive name."* 4. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Saves the file immediately. * **Require User Approval** — Pauses for user confirmation before saving. * **Let Agent Decide** — The agent determines whether approval is needed. File Save tool requiring user approval, showing the file name and files fields in the approval dialog 5. **Test the tool** — Generate or upload a file in the chat and ask the agent to save it. ## Settings * `File Name` — Text · Default: none · The name for the saved file. * `Files` — File list · Default: none · The files to save. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. ## Best Practices * **Use descriptive file names** — Include dates, client names, or report types in file names so saved files are easy to find later. * **Lock file names for standardized outputs** — When the agent always produces the same type of file, lock the name to a consistent naming convention. * **Use approval for important saves** — Set to "Require User Approval" to let users verify the file content before it's persisted to the platform. ## Related Templates Automatically generates structured investment memos from deal data and research inputs. Generates professional newsletters from raw content inputs, data, or briefs. Generates and reviews term sheets by extracting and validating key deal terms. Audits existing controls and drafts new control documentation based on compliance requirements. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the File Save node persists files generated during workflow execution to the VectorShift platform's Files tab. Connect upstream file outputs to this node to save them for later access, download, or use in other workflows. ## Use Cases * **Workflow output storage** — A workflow generates reports, transformed files, or exported data and saves them to the platform for user access. * **Intermediate file archival** — A workflow saves intermediate processing results as files for debugging or audit purposes. * **Scheduled report generation** — A cron-triggered workflow generates daily or weekly reports and saves them with timestamped names. * **File conversion output** — A workflow converts files between formats and saves the converted versions to the platform. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **File Save** onto the canvas. File Save node being dragged onto the canvas 2. **Set the file name** — Enter a name in the `File Name` field or connect an upstream text node for dynamic naming. 3. **Connect file input** — Wire upstream file outputs to the `Files` input. This field is required. File Save node connected to upstream and downstream nodes on the canvas 4. **Connect outputs** *(optional)* — Wire the `file_name` output to downstream nodes if you need to reference the saved file name. 5. **Run the workflow** — Execute the workflow. The node saves the file(s) to the platform. ## Settings * `File Name` — Text · **Required** · The name to save the file as. * `Files` — File list · **Required** · The files to save. ## Best Practices * **Use dynamic file names** — Connect upstream text nodes to generate unique file names (e.g., including timestamps or identifiers) to avoid overwriting previous saves. * **Place at the end of processing chains** — Position File Save after all transformations are complete so the final version is saved. * **Validate file inputs** — Ensure the upstream nodes actually produce file outputs before connecting to File Save to avoid runtime errors. ## Related Templates Automatically generates structured investment memos from deal data and research inputs. Generates professional newsletters from raw content inputs, data, or briefs. Generates and reviews term sheets by extracting and validating key deal terms. Audits existing controls and drafts new control documentation based on compliance requirements. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # File Source: https://docs.vectorshift.ai/nodes/file/overview Load a static file into a workflow as a raw file or process it into text. Add it in Python with `pipeline.add(name="...").file(...)`. See the SDK reference. The File node loads a static file into your workflow, either as a raw file reference or processed into text. You can upload a file directly or reference an existing file from the VectorShift platform by name. Use it to bring documents into your workflow for processing — for example, loading a PDF contract for extraction, feeding a CSV into a data transformation workflow, or providing an image for analysis. ## Core Functionality * Upload a file directly into the workflow or select an existing file from the VectorShift Files tab * Output the file as a raw file reference, as processed text, or both * Choose the document processing model (Default, Llama Parse, Textract, Reducto) for text extraction * Reference files by name for dynamic file selection at runtime ## Tool Inputs * `File` \* — **Required** · File upload · The file to load into the workflow. Drag and drop or click to upload. * `File Name` \* — **Required** · Text · The name of the file. When using "File Name" mode, this references an existing file on the VectorShift platform. * `Selected Option` — Dropdown · Default: `Select/ Upload File` · Options: `Select/ Upload File`, `File Name` · Choose between uploading a file directly or referencing a file by name from the platform. * `File Parser` — Dropdown · Default: `Default` · Options: `Default`, `Llama Parse`, `Textract`, `Reducto` · The processing model for document parsing. Default includes standard OCR. Llama Parse handles complex features like tables and charts (0.3¢/page). Textract provides advanced extraction (1.5¢/page). \* indicates a required field. ## Tool Outputs * `file` — File · The raw file that was loaded. * `processed_text` — Text · The text content extracted from the file using the selected parser. * `file_name` — Text · The name of the loaded file. ## Overview In workflows, the File node provides a static file as input to the workflow. The file is loaded once at build time (or referenced by name at runtime) and its outputs — raw file, processed text, and file name — can be wired to any downstream node that accepts those types. ## Use Cases * **Document processing workflow** — Load a PDF financial report into the workflow and pass the processed text to an LLM for summarization or data extraction. * **Template-based generation** — Load a document template file and pass it to downstream nodes that fill in dynamic content. * **File format conversion** — Load a file and pass it through conversion nodes (e.g., CSV to Excel, text to file). * **Knowledge base population** — Load a file and pass it to a Knowledge Base Loader node to add it to a knowledge base. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **File** onto the canvas. File node being dragged onto the canvas 2. **Choose the input mode** — Select `Select/ Upload File` to upload a file directly, or `File Name` to reference an existing file from the VectorShift Files tab by name. 3. **Provide the file** — Upload a file or enter the file name depending on the selected mode. 4. **Configure the parser** *(optional)* — If you need processed text output, choose the appropriate file parser (Default, Llama Parse, Textract, or Reducto) based on your document complexity. 5. **Connect outputs** — Wire `file`, `processed_text`, or `file_name` to downstream nodes as needed. File node connected to upstream and downstream nodes on the canvas 6. **Run the workflow** — Execute the workflow. The node loads the file and passes its outputs downstream. ## Settings * `Selected Option` — Dropdown · Default: `Select/ Upload File` · Upload directly or reference by name. * `File` — File upload · **Required** (when uploading) · The file to load. * `File Name` — Text · **Required** (when referencing by name) · The file name on the VectorShift platform. * `File Parser` — Dropdown · Default: `Default` · Document processing model. ## Best Practices * **Choose the right parser for your documents** — Use Default for standard text documents. Use Llama Parse for documents with complex tables, charts, or multi-column layouts. Use Textract for the most accurate extraction from scanned documents. * **Use File Name mode for dynamic workflows** — When building reusable workflows, reference files by name so the same workflow can process different files by changing the name parameter. * **Connect the appropriate output** — Use `file` when downstream nodes need the raw file (e.g., Knowledge Base Loader). Use `processed_text` when downstream nodes need text content (e.g., LLM nodes, text transformation nodes). ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Generates and reviews term sheets by extracting and validating key deal terms. Validates data and documents against predefined rules, schemas, or compliance standards. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Get Run Data Source: https://docs.vectorshift.ai/nodes/get-run-data/overview Fetch run metrics including trace, latency, cost, tokens, and status for a session. Add it in Python with `pipeline.add(name="...").get_run_data(...)`. See the SDK reference. The Get Run Data node fetches aggregated run metrics for a session, including trace ID, latency, cost, token usage, cache hit rates, and execution status. Use it to monitor and analyze workflow or agent execution performance — for example, tracking API costs across sessions, measuring response latency for SLA compliance, or checking whether a session completed successfully before proceeding. ## Core Functionality * Fetches aggregated run metrics for a session by session ID * Returns performance data: total latency, token usage, API cost, cache hit rates * Returns execution status: success, failure, in\_progress, or not\_found * Provides timing information: start time, end time, and trace ID for debugging ## Tool Inputs * `Session ID` \* — Text. Required. The session ID (execution\_id) to fetch run metrics for. \* *Required field* ## Tool Outputs * `tokens` — Integer. Total tokens across all spans in the session. * `avg_api_latency` — Decimal. Average API latency across LLM spans in seconds. * `avg_cache_hit_rate` — Decimal. Average cache hit rate across LLM spans (0.0 to 1.0). * `total_ai_cost` — Decimal. Total AI credits/cost across spans. * `status` — Text. Aggregated status of the run (success, failure, in\_progress, not\_found). * `status_message` — Text. Last status message from the run, if any. * `trace_id` — Text. Trace ID associated with this session run. * `total_latency` — Integer. Total latency in nanoseconds. * `start_time` — Text. Earliest span start time. * `end_time` — Text. Latest span end time. * `total_cache_savings` — Decimal. Total cache savings across LLM spans. * `total_cached_tokens` — Integer. Total cached tokens across LLM spans. *** ### Overview In workflows, the Get Run Data node connects to a session (via session ID) and retrieves performance and execution metrics. Use it after running an agent session to check costs, latency, token usage, and completion status. This enables monitoring workflows, cost tracking dashboards, and conditional logic based on execution results. get run data connect with nodes ### Use Cases * Track total AI cost per session to monitor spending against budget thresholds and trigger alerts when costs exceed limits * Check session status after running an automated analysis to verify completion before sending results to stakeholders * Measure average API latency across sessions to monitor SLA compliance for customer-facing chatbots * Calculate cache hit rates to evaluate prompt caching effectiveness and optimize for cost savings * Log trace IDs and timing data for debugging failed or slow-running agent sessions ### How It Works #### Step 1: Add the Get Run Data Node In the workflow canvas, click the **Chat** tab and click **Run Data**. Get Run Data node being added from the Chat tab #### Step 2: Connect the Session ID Connect the `Session ID` input from an upstream Create Session or other node that provides a session/execution ID. #### Step 3: Connect Outputs Connect the relevant metric outputs to downstream nodes. For example, connect `status` to a condition node to branch on success/failure, or connect `total_ai_cost` to a notification node for cost alerts. #### Step 4: Test Run the workflow and verify that metrics are returned correctly for the specified session. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ------ | ------- | ----------------------------------------------------- | | `Session ID` | Text | — | The session/execution ID. Required. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional output handles. **Advanced setting.** | ### Best Practices * **Use for cost monitoring.** Connect `total_ai_cost` to threshold checks and notifications to prevent runaway spending. * **Check status before proceeding.** Route the `status` output to a condition node to ensure the session completed successfully before acting on its results. * **Log metrics for analytics.** Store trace IDs, latency, and token counts for long-term performance analysis and optimization. * **Monitor cache effectiveness.** Track `avg_cache_hit_rate` and `total_cache_savings` to measure the impact of prompt caching strategies. * **Pair with Create Session and Post Message.** The full pattern is: Create Session → Post Message → Get Run Data to orchestrate and then measure agent interactions. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Summarizes and surfaces key CRM data insights for sales and relationship management teams. Handles investor inquiries related to portfolios, statements, and fund performance. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Google LLM Source: https://docs.vectorshift.ai/nodes/google/overview Generate text responses using Google's Gemini models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Google LLM node connects your workflows to Google's Gemini family of language models. Use it to generate text responses, analyze documents, answer questions grounded in knowledge bases, or produce structured JSON outputs — for example, summarizing earnings reports with extended thinking capabilities, classifying regulatory documents, or extracting structured data from financial filings. ## Core Functionality * Generate text completions and conversational responses using Gemini models * Process system instructions and dynamic prompts with variable interpolation * Configure thinking tokens for extended reasoning on complex tasks * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `gemini-2.5-flash`) Select from available Gemini models. Click **Dropdown** to view all options * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own Google API key instead of VectorShift's shared key * `Api Key` — (String) Your Google API key. Only visible when `Use Personal Api Key` is enabled * `JSON Schema` — (String) JSON schema to enforce structured output format. Only visible when `JSON Response` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Google LLM node in workflows lets you place a Gemini model directly on the canvas, wire inputs and outputs to other nodes, and configure model behavior through the settings panel. Google Gemini models offer large context windows and extended thinking capabilities, making them well-suited for complex analysis tasks. ## Use Cases * **Extended reasoning for financial analysis** — Leverage thinking tokens to perform multi-step financial reasoning, such as evaluating a company's valuation based on multiple data points across filings and market data. * **Large document processing** — Analyze lengthy regulatory documents or multi-page contracts using Gemini's large context window to capture all relevant details in a single pass. * **Earnings call summarization** — Summarize quarterly earnings transcripts, extracting key metrics like revenue, EPS, and forward guidance for analyst review. * **Structured data extraction** — Pull structured fields from unstructured financial documents using JSON mode for consistent, machine-readable output. * **Client Q\&A systems** — Build knowledge-grounded chatbots that answer investor or client questions using retrieved context from knowledge bases. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Google** node onto the canvas. Google node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. 4. **Select a model.** Use the `Model` dropdown to choose a Gemini model. Available options include `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-preview`, `gemini-2.0-flash-001`, `gemini-2.0-pro-preview`, and others. Google node showing the Model dropdown 5. **Open settings.** Click the **gear icon** (⚙) on the node to open the settings panel, where you can configure thinking tokens, token limits, temperature, retry behavior, and more. Google node settings panel 6. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes. Use token and credit outputs for monitoring. Google node connected to upstream and downstream nodes 7. **Run your workflow.** Execute the workflow. The Google node processes its inputs and returns the generated response along with usage metrics. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | Google | The LLM provider. | | `Max Tokens` | Integer | 80535 | Maximum number of input + output tokens the model will process per run. | | `Thinking Tokens` | Integer | 24576 | Maximum number of tokens the model can use for extended thinking and reasoning before generating a response. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning. Options: Default, Minimal, Low, Medium, High, None. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values produce more diverse outputs; lower values produce more deterministic responses. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token instead of returning the full response at once. | | `JSON Output` | Boolean | Off | Return output as structured JSON. When enabled, a `JSON Schema` input appears for optional schema enforcement. | | `Show Sources` | Boolean | Off | Display source documents used for the response. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max Retries` | Integer | — | Maximum number of retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `Credit Card` | Boolean | Off | Detect and redact credit card numbers from input. | | `Address` | Boolean | Off | Detect and redact physical addresses from input. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports on the node. | ## Best Practices * **Use thinking tokens for complex analysis.** When the model needs to reason through multi-step financial calculations or weigh competing data points, increase the `Thinking Tokens` setting to give it more reasoning capacity. * **Leverage large context windows.** Gemini models support very large context windows — use this to feed entire financial documents rather than chunking, for more coherent analysis. * **Use JSON mode for structured extraction.** Enable `JSON Output` and provide a schema when extracting data from financial documents for consistent output. * **Monitor token usage carefully.** Thinking tokens count toward total usage. Connect `tokens_used` and `credits_used` to monitoring nodes. * **Enable Safe Context Token Window for variable-length inputs.** Prevents token-limit errors when processing documents of unpredictable size. * **Apply PII detection including address.** Google supports address-level PII detection in addition to standard fields — enable it for workflows processing client correspondence. ## Related Templates Matches organizations or individuals to relevant grants based on their profile and eligibility criteria. Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Audits existing controls and drafts new control documentation based on compliance requirements. Assesses risk levels in incoming applications using scoring models and policy rules. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Image to Image Source: https://docs.vectorshift.ai/nodes/image-to-image/overview Modify and edit images using AI models in your workflows and agents. Add it in Python with `pipeline.add(name="...").ai_image_to_image(...)`. See the SDK reference. The Image to Image node uses AI to modify existing images based on text instructions. Use it to edit, transform, or enhance images — for example, adding annotations to financial charts, applying branding to report visuals, redacting sensitive information from document scans, or transforming presentation graphics to match a consistent style. ## Core Functionality * Modify and edit images using AI based on text prompts * Support multiple input images (1–3) for best results * Select aspect ratio for output images * Choose from available image generation providers and models * Use personal API keys for dedicated access ## Tool Inputs * `Provider` \* — (Enum (Dropdown), default: `Google`) Select the model provider * `Model` \* — (Enum (Dropdown), default: `gemini-2.5-flash-image`) Select the image-to-image model * `Prompt` \* — (String) Instructions for how the AI should modify the images. Be specific about desired changes * `Images` \* — (List\) Array of input images to modify. Provide 1–3 images for best results * `Aspect Ratio` — (Enum (Dropdown), default: `1:1`) Select the aspect ratio for the output image. Workflows only * `Use Personal API Key` — (Boolean, default: `No`) Toggle to use your own API key from the model provider * `Api Key` — (String) Your API key. Only visible when `Use Personal API Key` is enabled \* indicates a required field ## Tool Outputs * `image` — (Image) The modified image ## Overview The Image to Image tool in agents allows the AI to modify images during conversations based on user requests. The agent can automatically determine what modifications to make based on conversation context, or you can lock specific fields to fixed values. ## Use Cases * **Chart annotation** — Users can ask the agent to add labels, highlights, or callouts to financial charts and graphs. * **Brand consistency** — Apply consistent branding, color schemes, or watermarks to report visuals during a conversation. * **Document redaction** — Redact sensitive information from document images before sharing. * **Presentation graphics** — Transform or restyle presentation visuals to match corporate templates. ## How It Works 1. **Add the tool to your agent.** In the agent builder, click **Add Tool** and select **Image to Image** from the available tools. 2. **Configure input fields.** Each field can either be filled automatically by the agent based on conversation context, or locked to a fixed value: * `Provider` — Select the model provider (e.g., Google) * `Model` — Choose the image model (e.g., `gemini-2.5-flash-image`) * `Prompt` — The agent fills this based on the user's request, or you can set a fixed instruction * `Use Personal API Key` — Toggle if using your own key 3. **Write the Tool Description.** Provide a clear description of what this tool does so the agent knows when to use it. For example: *"Use this tool to modify or edit images. Describe the desired changes clearly."* 4. **Set Auto Run behavior.** Choose how the tool executes: * **Auto Run** — Executes automatically without user confirmation * **Require User Approval** — Asks the user before executing * **Let Agent Decide** — The agent determines whether to ask for approval 5. **Test the tool.** Send a message to the agent with an image and modification instructions to verify the tool works correctly. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ------------------------ | ------------------------------ | | `Provider` | Dropdown | Google | The image generation provider. | | `Model` | Dropdown | `gemini-2.5-flash-image` | The image-to-image model. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Write specific prompts.** Instead of "make it better," use precise instructions like "add a red circle highlighting the revenue growth bar in Q4." * **Provide 1–3 images.** The model works best with a small number of high-quality input images. * **Use Require User Approval for client-facing agents.** This lets users review modifications before they're applied. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. ## Overview The Image to Image node in workflows lets you place an image modification model on the canvas, connect input images and text prompts, and output the modified image to downstream nodes. ## Use Cases * **Batch image processing** — Process multiple financial charts or document images through consistent modification instructions. * **Automated report styling** — Apply consistent visual transformations to charts and graphics generated by upstream nodes. * **Document preprocessing** — Clean up, enhance, or annotate scanned financial documents before further processing. * **Visual content generation** — Create variations of marketing or presentation visuals at scale. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Image** category and drag the **Image to Image** node onto the canvas. Image to Image node being dragged onto the canvas 2. **Select a provider and model.** Choose the `Provider` (e.g., Google) and `Model` (e.g., `gemini-2.5-flash-image`) from the dropdowns. 3. **Write your prompt.** In the `Prompt` field, describe how you want the images modified. Be as specific as possible. 4. **Connect input images.** Wire image outputs from upstream nodes to the `Images` input, or upload images directly. 5. **Set aspect ratio.** Choose the output aspect ratio from the `Aspect Ratio` dropdown. 6. **Connect the output.** Wire the `image` output to downstream nodes for further processing or display. 7. **Run your workflow.** Execute the workflow to process the images. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | Google | The image generation provider. | | `Model` | Dropdown | `gemini-2.5-flash-image` | The image-to-image model. Options include `gemini-2.5-flash-image` and `gemini-2.0-flash-image-preview`. | | `Aspect Ratio` | Dropdown | `1:1` | Output image aspect ratio. | | `Use Personal API Key` | Boolean | No | Use your own API key from the provider. | ## Best Practices * **Be specific in your prompts.** Detailed modification instructions produce better results than vague descriptions. * **Use 1–3 input images.** The model performs best with a small number of inputs. * **Test with sample images first.** Verify the modification quality before running batch workflows. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Image to Text Source: https://docs.vectorshift.ai/nodes/image-to-text/overview Analyze images and generate text descriptions using AI models in your workflows and agents. Add it in Python with `pipeline.add(name="...").ai_image_to_text(...)`. See the SDK reference. The Image to Text node uses AI to analyze images and generate text descriptions, summaries, or structured data. Use it to extract information from financial charts, read text from document scans, describe visual content, or convert image-based data into machine-readable formats — for example, transcribing handwritten notes from meeting whiteboards, extracting data from screenshot tables, or describing chart trends from financial reports. ## Core Functionality * Analyze images and generate text descriptions using vision-capable AI models * Support multiple providers including OpenAI, Anthropic, Google, and xAI * Process system instructions and prompts to guide image analysis * Return structured JSON output with optional schema enforcement * Stream responses for real-time output * Track token usage per run ## Tool Inputs * `Provider` \* — (Enum (Dropdown), default: `OpenAI`) Select the model provider (OpenAI, Anthropic, Google, xAI) * `Model` \* — (Enum (Dropdown), default: `chatgpt-4o-latest`) Select the vision model. Options vary by provider * `System (Instructions)` — (String) Instructions guiding how the model should analyze the image * `Prompt` — (String) Specific instructions for what to analyze in the image * `Image` \* — (Image) The image to analyze * `Use Personal API Key` — (Boolean, default: `No`) Toggle to use your own API key * `Api Key` — (String) Your API key. Only visible when `Use Personal API Key` is enabled * `JSON Schema` — (String) JSON schema for structured output. Only visible when `JSON Response` is enabled \* indicates a required field ## Tool Outputs * `text` — (String (or Stream\ when streaming)) The generated text analysis of the image * `tokens_used` — (Integer) Total number of tokens consumed ## Overview The Image to Text tool in agents allows the AI to analyze images shared during conversations. The agent can automatically interpret images based on conversation context or follow specific analysis instructions you configure. ## Use Cases * **Financial chart interpretation** — Users share charts and the agent describes trends, key data points, and anomalies. * **Document scanning** — Extract text content from photographed or scanned financial documents. * **Receipt processing** — Analyze expense receipts to extract amounts, vendors, and dates. * **Visual compliance checks** — Review marketing materials or document images for compliance issues. ## How It Works 1. **Add the tool to your agent.** In the agent builder, click **Add Tool** and select **Image to Text** from the available tools. 2. **Configure input fields.** Each field can either be filled automatically by the agent based on conversation context, or locked to a fixed value: * `Provider` — Select the vision model provider * `Model` — Choose the vision model * `System (Instructions)` — Set analysis instructions * `Prompt` — The agent fills this based on the user's request * `Image` — The agent uses images shared in the conversation 3. **Write the Tool Description.** Describe what the tool does so the agent knows when to use it. For example: *"Use this tool to analyze the content of images. Describe what you see in detail."* 4. **Set Auto Run behavior.** Choose: Auto Run, Require User Approval, or Let Agent Decide. 5. **Test the tool.** Share an image with the agent and ask it to analyze the content. ## Settings | Setting | Type | Default | Description | | ----------------- | -------- | ------------------- | ---------------------------------- | | `Provider` | Dropdown | OpenAI | The vision model provider. | | `Model` | Dropdown | `chatgpt-4o-latest` | The vision model. | | `Max Tokens` | Integer | 128000 | Maximum output tokens. | | `Temperature` | Float | 0.7 | Controls response creativity. | | `Top P` | Float | 0.9 | Controls token sampling diversity. | | `JSON Response` | Boolean | Off | Return structured JSON output. | | `Stream Response` | Boolean | Off | Stream the response. | ## Best Practices * **Write specific analysis prompts.** Instead of "describe this image," use "extract all numerical data from this financial chart including axis labels, data points, and trends." * **Choose the right provider for your task.** GPT-4o models excel at detailed image analysis; Claude models are strong at document interpretation. * **Use JSON mode for data extraction.** When extracting structured data from images, enable JSON Response with a schema. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Validates data and documents against predefined rules, schemas, or compliance standards. Generates and reviews term sheets by extracting and validating key deal terms. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. ## Overview The Image to Text node in workflows lets you connect an image input to a vision model and output the generated text analysis to downstream nodes. This is useful for building automated image processing workflows. ## Use Cases * **Batch document OCR** — Process stacks of scanned financial documents and extract text for indexing or search. * **Chart data extraction** — Extract numerical data from financial charts and feed it to downstream analysis nodes. * **Visual quality assurance** — Automatically describe and verify visual content in generated reports. * **Multimodal workflows** — Combine image analysis with text processing for end-to-end document understanding workflows. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Image** category and drag the **Image to Text** node onto the canvas. Image to Text node being dragged onto the canvas 2. **Select a provider and model.** Choose the `Provider` (e.g., OpenAI) and `Model` (e.g., `gpt-4.1`) from the dropdowns. 3. **Configure instructions.** Enter analysis instructions in the `System (Instructions)` and `Prompt` fields. 4. **Connect the image input.** Wire an image output from an upstream node to the `Image` input. 5. **Connect outputs.** Wire the `text` output to downstream nodes for further processing. Image to Text node connected to upstream and downstream nodes 6. **Run your workflow.** Execute the workflow to analyze the image and generate text. ## Settings | Setting | Type | Default | Description | | ------------------------------ | -------- | ------------------- | ----------------------------------------------------------- | | `Provider` | Dropdown | OpenAI | The vision model provider (OpenAI, Anthropic, Google, xAI). | | `Model` | Dropdown | `chatgpt-4o-latest` | The vision model. | | `Max Tokens` | Integer | 128000 | Maximum output tokens. | | `Temperature` | Float | 0.7 | Controls response creativity. | | `Top P` | Float | 0.9 | Controls token sampling diversity. | | `JSON Response` | Boolean | Off | Return structured JSON output. | | `Stream Response` | Boolean | Off | Stream the response. | | `Use Personal API Key` | Boolean | No | Use your own API key. | | `Show Success/Failure Outputs` | Boolean | — | Display additional output ports. | ## Best Practices * **Use specific prompts for extraction tasks.** Guide the model with detailed instructions about what to extract from the image. * **Enable JSON mode for structured data.** Provide a schema when you need consistent structured output across many images. * **Adjust temperature for consistency.** Lower temperature (closer to 0) for factual extraction; higher for creative descriptions. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Validates data and documents against predefined rules, schemas, or compliance standards. Generates and reviews term sheets by extracting and validating key deal terms. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Input Source: https://docs.vectorshift.ai/nodes/input/overview Pass data of different types into your workflow as an entry point for execution. Add it in Python with `pipeline.add(name="...").input(...)`. See the SDK reference. The Input node is the primary entry point for passing data into a workflow. It defines a typed input that users or external systems provide when the workflow runs — for example, a text prompt for an LLM, a PDF file for extraction, an image for analysis, or structured data like tables and integers for processing. Each Input node creates a corresponding field in the workflow's run interface, API, or chatbot. ## Core Functionality * Defines a typed input parameter for the workflow that appears in the run interface, API, or chatbot * Supports a wide range of data types: Text, File, List of files, Audio, Image, Knowledge Base, Agent, Table, Dataframe, Integer, Decimal, Boolean, Timestamp, List of text, and more * Optionally sets a default value to use when no input is provided at runtime * The node name becomes the input field label — give each Input node a distinct, descriptive name ## Tool Inputs This node has no upstream input connections. It receives data from users or external systems at runtime. * `Type` — Dropdown. Default: `Text`. The data type of the input. Options: Text, File, List of files, List of lists of files, Audio, Image, Knowledge Base, Agent, Table, Dataframe, Integer, Decimal, Boolean, Timestamp, List of text, List of lists of text. ## Tool Outputs The output field changes based on the selected `Type`: * `text` — Text. The text that was passed in. (When Type is Text.) * `file` — File. The file that was passed in. (When Type is File.) * `processed_text` — Text. The processed text of the file. (When Type is File.) * `file_name` — Text. The name of the file. (When Type is File.) * Other types produce corresponding typed outputs (e.g., Image, Audio, Integer, etc.). *** ### Overview In workflows, the Input node defines what data the workflow expects when it runs. Each Input node becomes a field in the workflow's execution interface — whether that's the Run dialog, an API call, a chatbot message, or a form. The node outputs the provided data to downstream nodes for processing. Use multiple Input nodes to accept several parameters (e.g., a document and a query) in a single workflow run. ### Use Cases * Accept a text query from a user and route it to an LLM node for financial analysis or summarization * Receive a PDF upload (financial statement, invoice, contract) and pass it through extraction and processing nodes * Collect structured inputs like account numbers (Integer), transaction amounts (Decimal), or approval flags (Boolean) for automated workflows * Accept an image (receipt, check, ID document) for OCR or image-to-text processing * Provide a Knowledge Base reference as input to scope a semantic search to a specific data source ### How It Works #### Step 1: Add the Input Node In the workflow canvas, click the **Start** tab in the node palette and click **Input**. Drag it onto the canvas. Input node being dragged onto the canvas from the Start tab #### Step 2: Name the Input The node displays a suggestion: *"Give the node a distinct name."* Rename the node to describe the input (e.g., "User Query", "Upload Document", "Account Number"). The name appears as the field label when the workflow is run. #### Step 3: Select the Data Type Use the `Type` dropdown to select the appropriate data type. The default is `Text`. Choose from: Text, File, List of files, List of lists of files, Audio, Image, Knowledge Base, Agent, Table, Dataframe, Integer, Decimal, Boolean, Timestamp, List of text, or List of lists of text. The output handle updates to match the selected type. Input node showing the Type dropdown with available data types #### Step 4: Configure Settings (Optional) Click the settings icon to open the Settings panel: * **`Description`** — Enter a description for this input. This text appears as a hint in the run interface to help users understand what to provide. * **`Use Default Value`** — Toggle on to set a default value that is used when no input is provided at runtime. When enabled, a default value field appears where you can enter the fallback value. #### Step 5: Connect to Downstream Nodes Connect the output handle to the downstream node that processes this input. For example, connect a Text output to an LLM's prompt input, or a File output to a file processing node. Input node connected to downstream nodes on the canvas ### Settings | Setting | Type | Default | Description | | ------------------- | -------- | ------- | --------------------------------------------------------- | | `Type` | Dropdown | Text | The data type of the input. | | `Description` | Text | — | A description shown as a hint in the run interface. | | `Use Default Value` | Toggle | Off | Enable to set a fallback value when no input is provided. | ### Best Practices * **Give each Input node a descriptive name.** The node name becomes the field label in the run interface. "User Query" is far clearer than "input\_0" for someone running the workflow. * **Use the Description field.** Add a brief description (e.g., "Upload a PDF financial statement") so users running the workflow know exactly what to provide. * **Set default values for optional inputs.** If an input has a sensible default (e.g., a default date range or model name), enable `Use Default Value` so the workflow can run without requiring every field. * **Match the Type to your data.** Using the correct type (Integer, Decimal, Boolean) instead of always using Text ensures downstream nodes receive properly typed data and avoids unnecessary type conversion steps. * **Use multiple Input nodes for multi-parameter workflows.** If your workflow needs a query and a file, add two Input nodes rather than trying to combine them into one. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Knowledge Base Agent Source: https://docs.vectorshift.ai/nodes/knowledge-base-agent/overview Query a knowledge base using an agentic approach that intelligently determines the best retrieval strategy. Add it in Python with `pipeline.add(name="...").knowledge_base_agent(...)`. See the SDK reference. The Knowledge Base Agent node queries a knowledge base using an AI-powered agentic approach with tools. Instead of performing a simple vector search, it uses an LLM to reason about the query, determine the best retrieval strategy, and synthesize a coherent answer from the retrieved context. Use it to build intelligent Q\&A systems — for example, answering complex compliance questions across a regulatory document library, or synthesizing insights from multiple earnings reports stored in a knowledge base. ## Core Functionality * Query a knowledge base using an AI agent that reasons about the best retrieval approach * Choose between Fast, Focused, and Deep query modes to balance speed and thoroughness * Optionally return the source context and chunks used to generate the answer * Accept additional context (e.g., conversation history) to improve query relevance * Select the LLM provider and model powering the agent's reasoning ## Tool Inputs * `Knowledge Base` \* — **Required** · Knowledge Base selector · The knowledge base to query. * `Query` \* — **Required** · Text · The natural language query. The agent uses this to determine the best way to query the knowledge base. Include the key criteria needed to answer the query. * `Mode` — Dropdown · Default: `Focused` · Options: `Fast`, `Focused`, `Deep` · Controls the query effort — Fast for quick answers, Focused for balanced depth, Deep for thorough analysis. * `Return Answer` — Boolean · Default: `true` · When enabled, generates a synthesized answer from the knowledge base. * `Return Context` — Boolean · Default: `false` · When enabled, returns the relevant context and chunks used to generate the answer. * `Accept Additional Context` — Boolean · Default: `false` · When enabled, shows an additional context input to provide supplementary information to the agent. *(Advanced setting)* * `Additional Context` — Text · Optional · Additional context to help the agent understand the query better (e.g., conversation history, user preferences). Appears when `Accept Additional Context` is enabled. * `Provider` — Dropdown · Default: `Google` · The LLM provider used by the agent. *(Advanced setting)* * `Model` — Dropdown · Default: `gemini-3-flash-preview` · The LLM model used by the agent. *(Advanced setting)* \* indicates a required field. ## Tool Outputs * `answer` — Text · The answer synthesized by the agent from the knowledge base. * `context` — Text · The formatted context and chunks used by the agent to generate the answer. Only present when `Return Context` is enabled. ## Overview When added as a tool inside an agent, the Knowledge Base Agent enables your primary agent to delegate complex knowledge base queries to a specialized retrieval agent. The primary agent passes the query, the retrieval agent reasons about the best search strategy, fetches relevant chunks, and returns a synthesized answer — all within the conversation flow. ## Use Cases * **Regulatory Q\&A assistant** — A client-facing agent delegates SEC filing questions to a Knowledge Base Agent tool connected to a regulatory document library, returning precise citations. * **Investment research copilot** — An analyst agent queries a knowledge base of earnings transcripts and annual reports to answer specific questions about company performance. * **Policy lookup for advisors** — A financial advisor agent uses a Knowledge Base Agent to retrieve and summarize relevant sections from internal compliance policies. * **Due diligence support** — An M\&A agent queries a knowledge base of target company documents to answer specific due diligence questions with sourced context. * **Client portfolio FAQ** — A wealth management agent queries product knowledge bases to answer client questions about fund strategies, fees, and performance history. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **Knowledge** category. Select **Knowledge Base Agent** to add it as a tool. Agent tool panel showing Knowledge Base Agent tool in the tool list 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose which knowledge base the agent will query. 3. **Configure input fields** — The `Query` field can be left open for the primary agent to fill dynamically based on conversation context, or locked to a fixed value for consistent queries. Click the sparkle icon to switch fields between dynamic and static mode. Knowledge Base Agent tool configuration showing fields with sparkle icon to toggle between dynamic and static values 4. **Write a Tool Description** — Describe when the agent should use this tool. Example: *"Use this tool to answer questions about SEC regulatory filings. Provide a specific, detailed query including the regulation name or section number."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Queries the knowledge base immediately. * **Require User Approval** — Pauses for user confirmation before querying. * **Let Agent Decide** — The agent determines whether approval is needed based on context. Knowledge Base Agent tool requiring user approval 6. **Test the tool** — Send a question in the chat interface that should trigger the knowledge base query and verify the agent returns a relevant, sourced answer. ## Settings * `Knowledge Base` — Knowledge Base selector · Default: none · The knowledge base to query. * `Tool Description` — Text · Default: none · Describes when and how the agent should use this tool. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. **Advanced Settings:** * `Provider` — Dropdown · Default: `Google` · LLM provider for the retrieval agent. * `Model` — Dropdown · Default: `gemini-3-flash-preview` · LLM model for the retrieval agent. * `Mode` — Dropdown · Default: `Focused` · Query depth (Fast, Focused, Deep). * `Return Context` — Boolean · Default: `false` · Return source chunks alongside the answer. * `Accept Additional Context` — Boolean · Default: `false` · Enable additional context input. ## Best Practices * **Write specific queries** — The more specific the query, the better the agent can target its retrieval. Include entity names, date ranges, and specific metrics rather than broad questions. * **Use Deep mode for complex questions** — When queries span multiple documents or require cross-referencing (e.g., comparing financials across quarters), use Deep mode for thorough analysis. * **Enable Return Context for auditable answers** — In regulated industries, enable Return Context so users can verify the sources behind every answer. * **Provide additional context for follow-ups** — Enable Accept Additional Context and pass conversation history so the agent understands follow-up questions in context. * **Match the knowledge base to the query domain** — Connect the tool to a knowledge base that contains the relevant documents. A single agent can have multiple Knowledge Base Agent tools, each pointing to a different knowledge base. ## Related Templates Analyzes contracts to extract key terms, flag risks, and summarize obligations. Handles investor inquiries related to portfolios, statements, and fund performance. Answers employee questions about internal policies and flags potential compliance issues. Centralized searchable repository of investment committee memos for quick reference. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Knowledge Base Agent node acts as an intelligent retrieval step that queries a knowledge base, reasons about the best search strategy, and returns a synthesized answer. Connect upstream nodes to provide the query and optionally additional context, then wire the answer output to downstream nodes for further processing or display. ## Use Cases * **Automated report enrichment** — A workflow collects key questions from a template, passes each to a Knowledge Base Agent node connected to a research library, and assembles the answers into a formatted report. * **Compliance screening workflow** — A workflow feeds extracted document clauses into a Knowledge Base Agent to check them against a regulatory knowledge base and flag potential issues. * **Customer inquiry routing** — A workflow uses a Knowledge Base Agent to attempt answering a customer question; if the confidence is low, it routes to a human agent. * **Batch Q\&A processing** — A workflow iterates over a list of analyst questions and queries a knowledge base for each, outputting a structured Q\&A document. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Knowledge Base Agent** onto the canvas. Knowledge Base Agent node being dragged onto the canvas 2. **Set the query** — Enter a query in the `Query` field or connect an upstream text node. This field is required. 3. **Select the knowledge base** — Use the `Knowledge Base` selector to choose the target knowledge base. This field is required. You can select from existing knowledge bases or connect a knowledge base reference from an upstream node. 4. **Configure mode and options** — Set the query `Mode` (Fast, Focused, Deep), toggle `Return Context` if you need source chunks, and enable `Accept Additional Context` if supplementary information is available. Knowledge Base Agent node settings panel showing Query, Knowledge Base, Mode, and other configuration options 5. **Configure advanced settings** — Optionally change the `Provider` and `Model` for the retrieval agent, and adjust settings like `Return Context` and `Accept Additional Context`. 6. **Connect outputs** — Wire the `answer` output (and optionally `context`) to downstream nodes for further processing. Knowledge Base Agent node connected to upstream and downstream nodes on the canvas 7. **Run the workflow** — Execute the workflow. The node queries the knowledge base and passes the synthesized answer downstream. ## Settings * `Query` — Text · **Required** · The natural language query to send to the knowledge base agent. * `Knowledge Base` — Knowledge Base selector · **Required** · The knowledge base to query. Supports Select, Variable, and Knowledge Base connection modes. **Advanced Settings:** * `Provider` — Dropdown · Default: `Google` · LLM provider for the retrieval agent. * `Model` — Dropdown · Default: `gemini-3-flash-preview` · LLM model for the retrieval agent. * `Mode` — Dropdown · Default: `Focused` · Query depth (Fast, Focused, Deep). * `Return Context` — Boolean · Default: `false` · Return the source context and chunks used. * `Accept Additional Context` — Boolean · Default: `false` · Show an additional context input field. * `Show Source/Chunk Output` — Boolean · Controls whether source and chunk details are shown in outputs. ## Best Practices * **Choose the right mode for your use case** — Use Fast for simple lookups, Focused for standard Q\&A, and Deep when queries require reasoning across multiple documents. * **Enable Return Context for traceability** — In financial workflows, always enable Return Context so downstream nodes can include citations and source references in generated reports. * **Use variables for dynamic knowledge base selection** — When building multi-tenant workflows, connect the Knowledge Base input via a variable to dynamically select the correct knowledge base per run. * **Pair with condition nodes** — Add a condition node after the Knowledge Base Agent to check answer quality or relevance before passing results downstream. * **Provide additional context from upstream** — Enable Accept Additional Context and connect relevant upstream outputs (e.g., extracted entities, user preferences) to improve retrieval accuracy. ## Related Templates Analyzes contracts to extract key terms, flag risks, and summarize obligations. Handles investor inquiries related to portfolios, statements, and fund performance. Answers employee questions about internal policies and flags potential compliance issues. Centralized searchable repository of investment committee memos for quick reference. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Knowledge Base Fetch Document Content Source: https://docs.vectorshift.ai/nodes/knowledge-base-fetch-document-content/overview Fetch the full content of a specific document from a knowledge base by reading through all its chunks. Add it in Python with `pipeline.add(name="...").knowledge_base_fetch_document_content(...)`. See the SDK reference. The Knowledge Base Fetch Document Content node retrieves the complete text content of a specific document stored in a knowledge base. Unlike semantic search which returns relevant chunks, this node returns the entire document — similar to a `cat` command for reading a file. Use it when you need the full text of a known document — for example, retrieving a complete contract for clause-by-clause analysis, or pulling an entire earnings transcript for summarization. ## Core Functionality * Fetch the full content of a specific document from a knowledge base by its item ID * Reassemble all chunks belonging to the document into a single formatted text output * Control the maximum number of chunks included to handle very large documents * Works with any document type stored in the knowledge base (PDFs, text files, web pages, etc.) ## Tool Inputs * `Knowledge Base` \* — **Required** · Knowledge Base selector · The knowledge base containing the document to fetch. * `Item ID` \* — **Required** · Text · The item ID of the document to fetch content from. Typically obtained from a Knowledge Base Fetch Items or Knowledge Base List Items node. * `Max Chunks` — Integer · Default: `200` · Maximum number of chunks to include in the content. *(Advanced setting)* \* indicates a required field. ## Tool Outputs * `document_content` — Text · The full document content as formatted text, reassembled from all chunks. ## Overview When added as a tool inside an agent, Knowledge Base Fetch Document Content lets the agent retrieve the complete text of a specific document during a conversation. The agent can use this to read full documents when a user asks about a specific file, rather than relying on chunk-based search results that may miss important context. ## Use Cases * **Full contract review** — An agent fetches the complete text of a specific contract from a legal knowledge base when a user asks to review all terms and conditions. * **Earnings transcript analysis** — An agent retrieves a full earnings call transcript to answer detailed questions that span multiple sections of the document. * **Regulatory filing retrieval** — A compliance agent fetches complete SEC filings when a user needs to review an entire document rather than isolated excerpts. * **Policy document lookup** — An HR or compliance agent retrieves full policy documents by ID when users need to understand the complete policy context. * **Report compilation** — An agent fetches multiple full documents by their IDs to compile a comprehensive research report from existing materials. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **Knowledge** category. Select **Knowledge Base Fetch Document Content** to add it as a tool. Agent tool panel showing Knowledge Base Fetch Document Content tool in the tool list 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose which knowledge base contains the documents. 3. **Configure input fields** — The `Item ID` field can be left open for the agent to fill dynamically (e.g., after listing items with another tool), or locked to a fixed value for a specific document. Click the sparkle icon to switch fields between dynamic and static mode. Knowledge Base Fetch Document Content tool configuration showing fields with sparkle icon to toggle between dynamic and static values 4. **Write a Tool Description** — Describe when the agent should fetch full document content. Example: *"Use this tool to read the complete content of a specific document from the knowledge base. Provide the item ID of the document you want to read."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Fetches the document immediately. * **Require User Approval** — Pauses for user confirmation. * **Let Agent Decide** — The agent determines whether approval is needed. Knowledge Base Fetch Document Content tool requiring user approval 6. **Test the tool** — Ask the agent to retrieve a specific document and verify the full content is returned. ## Settings * `Knowledge Base` — Knowledge Base selector · Default: none · The knowledge base containing the target document. * `Item ID` — Text · Default: none · The ID of the document to fetch. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. **Advanced Settings:** * `Max Chunks` — Integer · Default: `200` · Limits the number of chunks included in the output. ## Best Practices * **Pair with Knowledge Base Fetch Items** — Use the Knowledge Base Fetch Items tool first to let the agent discover available documents and their IDs, then use this tool to read the full content of a specific document. * **Set appropriate max chunks** — For very large documents (e.g., annual reports), consider increasing Max Chunks beyond 200 to ensure the full document is returned. For shorter documents, the default is sufficient. * **Use for targeted retrieval** — This tool is best when the agent knows which specific document to read. For broad queries across many documents, use Knowledge Base Agent or Semantic Search instead. * **Include item ID guidance in the tool description** — Tell the agent how to obtain item IDs (e.g., from a previous Fetch Items call) so it knows the correct workflow. ## Related Templates Analyzes contracts to extract key terms, flag risks, and summarize obligations. Side-by-side comparison of documents to highlight differences and track revisions. Audits existing controls and drafts new control documentation based on compliance requirements. Generates and reviews term sheets by extracting and validating key deal terms. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Knowledge Base Fetch Document Content node retrieves the complete text of a specific document from a knowledge base. Connect an upstream node to provide the item ID, and wire the document content output to downstream nodes for processing — such as summarization, analysis, or formatting. ## Use Cases * **Document processing workflow** — A workflow lists all documents in a knowledge base, iterates over each, and fetches the full content for batch processing (e.g., summarization or classification). * **Targeted document extraction** — A workflow receives a document ID from user input, fetches the full content, and passes it to an LLM for analysis. * **Compliance document review** — A workflow fetches specific regulatory documents by ID and runs them through compliance checking nodes. * **Report assembly** — A workflow fetches multiple documents by their IDs and combines their content into a consolidated report. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Knowledge Base Fetch Document Content** onto the canvas. Knowledge Base Fetch Document Content node being dragged onto the canvas 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose the knowledge base. This field is required. You can select from existing knowledge bases or connect a reference from an upstream node. 3. **Provide the item ID** — Enter an item ID in the `Item ID` field or connect an upstream node that outputs the document ID. This field is required. 4. **Connect the output** — Wire the `document_content` output to downstream nodes for processing. 5. **Run the workflow** — Execute the workflow. The node fetches the document content and passes it downstream. ## Settings * `Knowledge Base` — Knowledge Base selector · **Required** · The knowledge base to fetch from. Supports Select, Variable, and Knowledge Base connection modes. * `Item ID` — Text · **Required** · The item ID of the document to fetch. **Advanced Settings:** * `Max Chunks` — Integer · Default: `200` · Maximum number of chunks to include in the output. ## Best Practices * **Chain with Knowledge Base Fetch Items** — Use a Knowledge Base Fetch Items node upstream to get the list of available document IDs, then pass them to this node. * **Handle large documents carefully** — Documents with more than 200 chunks will be truncated at the default Max Chunks value. Increase this setting for large financial reports or legal documents. * **Validate item IDs** — Ensure the item ID exists in the selected knowledge base. Invalid IDs will result in empty or error outputs. * **Use for full-document operations** — This node is ideal when you need the entire document (e.g., for summarization or conversion). For targeted retrieval of relevant passages, use Semantic Search instead. ## Related Templates Analyzes contracts to extract key terms, flag risks, and summarize obligations. Side-by-side comparison of documents to highlight differences and track revisions. Audits existing controls and drafts new control documentation based on compliance requirements. Generates and reviews term sheets by extracting and validating key deal terms. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Knowledge Base Fetch Items Source: https://docs.vectorshift.ai/nodes/knowledge-base-fetch-items/overview List and navigate knowledge base items (folders and documents) with traversal, filtering, and output shaping capabilities. Add it in Python with `pipeline.add(name="...").knowledge_base_fetch_items(...)`. See the SDK reference. The Knowledge Base Fetch Items node lists documents and folders stored in a knowledge base with powerful navigation capabilities — analogous to an `ls` command for browsing files and folders. Use it to discover what content exists in a knowledge base, navigate folder hierarchies, filter by file type, and retrieve item IDs for downstream processing. For example, you can list all PDF documents in a specific folder, browse the top-level structure of a knowledge base, or recursively discover all items to build a document index. ## Core Functionality * List documents and folders in a knowledge base with pagination support * Navigate folder hierarchies with configurable traversal depth * Filter items by type (folders only, documents only, or all) and by file extension * Control output verbosity from metadata-only to full summaries * Sort results by specified fields in ascending or descending order * Return structured item data, statistics, formatted text, and item IDs ## Tool Inputs * `Knowledge Base` \* — **Required** · Knowledge Base selector · The knowledge base to list items from. * `Root IDs` — Text · Default: empty (lists from root) · Filter to list items in a specific folder. Provide folder ID(s) to scope the listing. Acts as the target directory. * `Max Depth` — Integer · Default: `0` · Maximum depth for descendant traversal. `1` = current directory only; `0` = recursive discovery to traverse all descendants until the limit is reached. *(Advanced setting)* * `Sort Fields` — Text · Default: empty · Comma-separated field names to sort results by. *(Advanced setting)* * `Sort Orders` — Text · Default: empty · Comma-separated sort directions (`asc` or `desc`) corresponding to sort fields. *(Advanced setting)* * `Limit` — Integer · Default: `50` · Maximum number of items to return. *(Advanced setting)* * `Offset` — Integer · Default: `0` · Number of items to skip for pagination. *(Advanced setting)* * `Item Return Type` — Text · Default: `ALL` · Type of items to return: `FOLDERS`, `DOCUMENTS`, or `ALL`. *(Advanced setting)* * `Filter` — Text · Default: empty · JSON filter object for advanced filtering. Supports `eq` and `neq` operators on the `file_extension` field. Example: `{"type": "condition", "field": "file_extension", "operator": "eq", "value": "pdf"}`. *(Advanced setting)* * `Verbosity` — Text · Default: `metadata` · Output verbosity level: `metadata` (no summaries), `short` (short summaries), or `long` (short and long summaries). *(Advanced setting)* \* indicates a required field. ## Tool Outputs * `kb_items` — List of Text · The knowledge base items as structured data. * `stats` — Text · JSON-serialized statistics about the listing results. * `formatted_text` — Text · Human-readable formatted text representation of the items. * `kb_item_ids` — List of Text · The IDs of the returned knowledge base items. ## Overview When added as a tool inside an agent, Knowledge Base Fetch Items lets the agent browse and discover the contents of a knowledge base during a conversation. The agent can navigate folder structures, filter by file type, and retrieve document IDs — then use those IDs with other tools like Knowledge Base Fetch Document Content to read specific documents. ## Use Cases * **Document discovery** — An agent lists all documents in a client's knowledge base to help a user find a specific filing or report by name. * **Folder navigation** — An agent browses the folder structure of a regulatory knowledge base, helping users navigate through organized collections of compliance documents. * **File type filtering** — An agent lists only PDF documents in a knowledge base when a user asks to review all uploaded reports, filtering out other file types. * **Knowledge base auditing** — An agent inventories the contents of a knowledge base to identify missing documents or outdated files for a portfolio review. * **Document indexing** — An agent recursively lists all items in a knowledge base with short summaries to build a quick reference index for a user. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **Knowledge** category. Select **Knowledge Base Fetch Items** to add it as a tool. Agent tool panel showing Knowledge Base Fetch Items tool in the tool list 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose which knowledge base to browse. 3. **Configure input fields** — Fields like `Root IDs`, `Limit`, `Sort Orders`, and `Filter` can be left for the agent to fill dynamically based on user requests, or locked to fixed values for constrained browsing. Click the sparkle icon to switch fields between dynamic and static mode. Knowledge Base Fetch Items tool configuration showing fields with sparkle icon to toggle between dynamic and static values 4. **Write a Tool Description** — Describe when the agent should list items. Example: *"Use this tool to browse and list documents in the knowledge base. You can filter by folder, file type, and control how many results to return."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Lists items immediately. * **Require User Approval** — Pauses for user confirmation. * **Let Agent Decide** — The agent determines whether approval is needed. Knowledge Base Fetch Items tool requiring user approval 6. **Test the tool** — Ask the agent to show documents in the knowledge base and verify it returns the expected listing. ## Settings * `Knowledge Base` — Knowledge Base selector · Default: none · The knowledge base to browse. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. **Advanced Settings:** * `Root IDs` — Text · Default: empty · Target folder ID(s) for scoped listing. * `Max Depth` — Integer · Default: `0` · Traversal depth (0 = recursive, 1 = current level only). * `Sort Fields` — Text · Default: empty · Fields to sort by. * `Sort Orders` — Text · Default: empty · Sort directions (asc/desc). * `Limit` — Integer · Default: `50` · Max items to return. * `Offset` — Integer · Default: `0` · Pagination offset. * `Item Return Type` — Text · Default: `ALL` · Filter by FOLDERS, DOCUMENTS, or ALL. * `Filter` — Text · Default: empty · JSON filter for file extension filtering. * `Verbosity` — Text · Default: `metadata` · Output detail level (metadata, short, long). ## Best Practices * **Use metadata verbosity for browsing** — When the agent is just discovering what documents exist, use `metadata` verbosity for faster results. Switch to `short` or `long` when the user needs content summaries. * **Pair with Fetch Document Content** — Use this tool to find document IDs, then chain with Knowledge Base Fetch Document Content to read the full content of specific documents. * **Set reasonable limits** — For large knowledge bases, keep the limit manageable (50–100) and use pagination via offset for browsing through results. * **Use filters sparingly** — Only apply file extension filters when the user explicitly requests them. The agent should avoid adding filters that were not asked for. * **Scope with Root IDs for large knowledge bases** — When a knowledge base has many folders, provide a Root ID to limit browsing to a specific section rather than listing everything. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Validates data and documents against predefined rules, schemas, or compliance standards. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Side-by-side comparison of documents to highlight differences and track revisions. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Knowledge Base Fetch Items node lists documents and folders from a knowledge base as a workflow step. The node outputs structured item data, statistics, formatted text, and item IDs that can be wired to downstream nodes for processing — such as iterating over documents, filtering results, or passing IDs to a Fetch Document Content node. ## Use Cases * **Batch document processing** — A workflow lists all documents in a knowledge base, then iterates over the item IDs to fetch and process each document individually. * **Knowledge base inventory** — A workflow periodically lists all items in a knowledge base and generates a report of document counts, types, and folder structure. * **Conditional document routing** — A workflow lists items filtered by type, then routes different document categories to different processing workflows. * **Incremental sync detection** — A workflow lists items with pagination to identify new or updated documents since the last processing run. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Knowledge Base Fetch Items** onto the canvas. 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose the target knowledge base. This field is required. 3. **Configure listing options** — Set `Limit`, `Offset`, `Item Return Type`, and other parameters as needed. For recursive traversal, leave `Max Depth` at 0. 4. **Connect outputs** — Wire the desired outputs (`kb_items`, `stats`, `formatted_text`, `kb_item_ids`) to downstream nodes. 5. **Run the workflow** — Execute the workflow. The node lists items and passes the results downstream. ## Settings * `Knowledge Base` — Knowledge Base selector · **Required** · The knowledge base to list items from. * `Root IDs` — Text · Default: empty · Target folder ID(s) for scoped listing. **Advanced Settings:** * `Max Depth` — Integer · Default: `0` · Traversal depth (0 = recursive, 1 = current level). * `Sort Fields` — Text · Default: empty · Comma-separated fields to sort by. * `Sort Orders` — Text · Default: empty · Comma-separated sort directions. * `Limit` — Integer · Default: `50` · Maximum number of items to return. * `Offset` — Integer · Default: `0` · Pagination offset. * `Item Return Type` — Text · Default: `ALL` · FOLDERS, DOCUMENTS, or ALL. * `Filter` — Text · Default: empty · JSON filter for file extension filtering. * `Verbosity` — Text · Default: `metadata` · Output detail level. ## Best Practices * **Use pagination for large knowledge bases** — Set `Limit` and `Offset` to paginate through large collections rather than requesting all items at once. * **Filter by item type when possible** — If you only need documents (not folders), set `Item Return Type` to `DOCUMENTS` to reduce noise in the output. * **Use kb\_item\_ids for downstream chaining** — The `kb_item_ids` output is ideal for passing to a loop or to Knowledge Base Fetch Document Content nodes. * **Choose verbosity based on need** — Use `metadata` for fast enumeration, `short` for quick summaries, and `long` only when you need detailed document descriptions with a lower limit. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Validates data and documents against predefined rules, schemas, or compliance standards. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Side-by-side comparison of documents to highlight differences and track revisions. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Knowledge Base Loader Source: https://docs.vectorshift.ai/nodes/knowledge-base-loader/overview Load files or URLs into an existing knowledge base for indexing and retrieval. Add it in Python with `pipeline.add(name="...").knowledge_base_loader(...)`. See the SDK reference. The Knowledge Base Loader node loads data into an existing knowledge base. It supports uploading files (PDFs, documents, spreadsheets) or scraping URLs, with optional automatic rescraping on a schedule. Use it to populate a knowledge base with content — for example, loading a batch of financial reports into a client knowledge base, or adding a set of web pages that should be periodically refreshed. ## Core Functionality * Load files or URLs into an existing knowledge base * Choose between File and URL document types * Add multiple items (files or URLs) in a single operation * Configure automatic rescraping frequency for URL sources (Never, Daily, Weekly, Monthly) * Works with any existing knowledge base — pair with Create Knowledge Base to build and populate in one workflow ## Tool Inputs * `Knowledge Base` \* — **Required** · Knowledge Base selector · The knowledge base to load data into. * `Document Type` — Dropdown · Default: `File` · Options: `File`, `URL` · The type of document to load. * `Documents` \* — **Required** · File or URL list · The files or URLs to load into the knowledge base. Use the **+ Add Item** button to add multiple items. * `Rescrape Frequency` — Dropdown · Default: `Never` · Options: `Never`, `Daily`, `Weekly`, `Monthly` · How often to rescrape URL sources for updated content. Only applicable when Document Type is URL. \* indicates a required field. ## Tool Outputs This node does not produce outputs. It performs a load operation into the selected knowledge base. ## Overview When added as a tool inside an agent, the Knowledge Base Loader enables the agent to load files or URLs into a knowledge base during a conversation. The agent can accept documents from users and add them to a designated knowledge base, or scrape URLs provided in the conversation. ## Use Cases * **Client document ingestion** — An agent accepts uploaded financial documents from a client and loads them into their dedicated knowledge base for future retrieval. * **Research URL collection** — An agent scrapes analyst report URLs shared in conversation and loads them into a research knowledge base with weekly rescraping enabled. * **Policy document updates** — A compliance agent loads updated regulatory documents into the compliance knowledge base when new versions are shared. * **Meeting notes archival** — An agent loads meeting transcripts and notes into a project knowledge base after each client call. * **Evidence collection** — An audit agent loads supporting documents into an audit-specific knowledge base as users provide them during the review process. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **Knowledge** category. Select **Knowledge Base Loader** to add it as a tool. Agent tool panel showing Knowledge Base Loader tool in the tool list 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose which knowledge base to load data into. 3. **Configure input fields** — Set the `Document Type` (File or URL). The document items can be filled by the agent based on files or URLs provided in conversation, or locked to fixed values. Click the sparkle icon to switch fields between dynamic and static mode. Knowledge Base Loader tool configuration showing fields with sparkle icon to toggle between dynamic and static values 4. **Write a Tool Description** — Describe when the agent should load documents. Example: *"Use this tool to load files or URLs into the client's knowledge base. Accept files uploaded by the user or URLs shared in conversation."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Loads documents immediately. * **Require User Approval** — Pauses for user confirmation before loading. * **Let Agent Decide** — The agent determines whether approval is needed. Knowledge Base Loader tool requiring user approval 6. **Test the tool** — Upload a file or share a URL in the chat and ask the agent to add it to the knowledge base. ## Settings * `Knowledge Base` — Knowledge Base selector · Default: none · The target knowledge base. * `Document Type` — Dropdown · Default: `File` · File or URL. * `Rescrape Frequency` — Dropdown · Default: `Never` · URL rescraping schedule. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. ## Best Practices * **Lock the knowledge base selection** — In most cases, set the Knowledge Base field to a fixed value so the agent always loads into the correct knowledge base rather than guessing. * **Use "Require User Approval" for production** — Loading documents is a write operation that modifies the knowledge base. Use approval mode to prevent accidental uploads. * **Set rescrape frequency for dynamic URLs** — When loading web pages that update regularly (e.g., news sources, market data pages), enable daily or weekly rescraping. * **Pair with Create Knowledge Base** — When onboarding new clients, use Create Knowledge Base first, then Knowledge Base Loader to populate it — all within the same agent conversation. ## Related Templates Centralized searchable repository of investment committee memos for quick reference. Answers employee questions about internal policies and flags potential compliance issues. A configurable chatbot that connects to custom APIs to retrieve and present dynamic data. Handles investor inquiries related to portfolios, statements, and fund performance. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Knowledge Base Loader node loads files or URLs into an existing knowledge base as a workflow step. Connect upstream nodes to provide the documents or URLs, and the node handles the loading operation. This is ideal for automated document ingestion workflows that process and store content without manual intervention. ## Use Cases * **Automated document ingestion** — A workflow receives uploaded files from a form interface and loads them into a knowledge base automatically. * **Scheduled web scraping** — A triggered workflow scrapes a list of financial news URLs and loads them into a market intelligence knowledge base on a daily schedule. * **Workflow-driven population** — A workflow creates a new knowledge base, then immediately loads a set of seed documents into it using the Knowledge Base Loader. * **Multi-source aggregation** — A workflow collects documents from multiple integrations (email attachments, file uploads, API responses) and loads them all into a central knowledge base. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Knowledge Base Loader** onto the canvas. Knowledge Base Loader node being dragged onto the canvas 2. **Set the document type** — Choose `File` or `URL` from the `Data Type` dropdown. 3. **Add items to load** — Add one or more items using the **+ Add Item** button, or connect upstream file/URL outputs to the item inputs. 4. **Select the knowledge base** — Use the `Knowledge Base` selector to choose the target knowledge base. This field is required. 5. **Configure rescrape frequency** *(URL only)* — If loading URLs, set the rescrape frequency to control how often the content is refreshed. Knowledge Base Loader node connected to upstream nodes on the canvas 6. **Run the workflow** — Execute the workflow. The node loads all provided items into the knowledge base. ## Settings * `Data Type` — Dropdown · Default: `File` · Options: File, URL. * `Documents to Load` — File/URL list · **Required** · The items to load. Use + Add Item for multiple entries. * `Knowledge Base` — Knowledge Base selector · **Required** · The target knowledge base. Supports Select, Variable, and Knowledge Base connection modes. * `Rescrape Frequency` — Dropdown · Default: `Never` · Options: Never, Daily, Weekly, Monthly. URL rescraping schedule. ## Best Practices * **Validate inputs before loading** — Ensure file or URL inputs are valid before they reach the Knowledge Base Loader. Invalid files will fail silently or produce errors. * **Use dependencies for ordered execution** — When chaining with Create Knowledge Base, use the dependencies feature to ensure the knowledge base exists before attempting to load. * **Batch wisely** — Loading many large files at once can take time. Consider breaking very large batches into smaller groups. * **Set appropriate rescrape schedules** — For financial data pages that update daily, use Daily rescraping. For static reference documents, leave it at Never. * **Connect to upstream data sources** — Wire file outputs from File nodes, API nodes, or other data loaders directly into the Knowledge Base Loader's item inputs. ## Related Templates Centralized searchable repository of investment committee memos for quick reference. Answers employee questions about internal policies and flags potential compliance issues. A configurable chatbot that connects to custom APIs to retrieve and present dynamic data. Handles investor inquiries related to portfolios, statements, and fund performance. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Knowledge Base Reader Source: https://docs.vectorshift.ai/nodes/knowledge-base-v3/overview Query a knowledge base with semantic search to retrieve relevant content for workflows and agents. Add it in Python with `pipeline.add(name="...").knowledge_base(...)`. See the SDK reference. A knowledge base stores and organizes content — documents, files, URLs, and data from external integrations — so your workflows and agents can search and retrieve relevant information on demand. It uses semantic search to find content that matches the meaning of a query, not just exact keywords. When you query a knowledge base, it converts both the query and the stored content into numerical representations called embeddings, which capture meaning and context. It then finds the stored content whose meaning is closest to the query — so a question like "how do I reset my password?" can match a document titled "Account Recovery Steps" even if the words don't overlap. This makes knowledge bases particularly effective for natural language queries and conversational AI use cases. ## Key Use Cases * Answering user questions grounded in your own documents or internal content * Building RAG workflows that pull relevant context before generating a response * Giving an agent access to product documentation, policies, or knowledge articles * Surfacing citations and sources alongside AI-generated responses * Indexing structured data like tables for retrieval alongside unstructured documents ## Data Sources **File Upload** Upload files directly to your knowledge base. Supported formats: `doc`, `docx`, `pdf`, `csv`, `xls`, `xlsx`, `pptx`, `txt`, `md`, and more. **Integrations** Sync content from connected external services so your knowledge base stays current without manual updates. Supported integrations include: * Google Drive * And more via the Add Integration option **Scrape URL** Pull and index content from a web page by providing a URL. **Workspace Files** Use files already stored in your workspace without re-uploading. **Index Table** Index a structured table as a retrievable knowledge source alongside your unstructured content. ## Using the Knowledge Base Reader Node In workflows, the knowledge base is accessed through the **Knowledge Base Reader** node. Place it on the canvas, point it at a knowledge base, pass it a search query, and it returns the most relevant content for downstream nodes — typically an LLM — to consume. ### Key Use Cases * Retrieving relevant document chunks to answer a user's query in a Q\&A workflow * Feeding retrieved context into an LLM node for RAG * Searching across files and synced content at a specific step in a workflow * Using retrieved pages or documents when broader context is needed beyond individual chunks * Generating a direct answer from retrieved content using Advanced QA mode ### How It Works **Step 1: Add the Knowledge Base Reader Node** Find the **Knowledge Base Reader** node under the **Knowledge** category in the node panel and drag it onto the canvas. Node palette showing the Knowledge category with Knowledge Base Reader node being dragged onto the canvas **Step 2: Name the Node** The node defaults to `knowledge_base_0`. Rename it to something descriptive, especially when using multiple knowledge nodes in the same workflow. **Step 3: Enter a Search Query** In the **Search Query** field, enter the query to run against the knowledge base. Use `{{` to reference a variable from an upstream node — typically an Input node carrying the user's question. **Step 4: Select or Create a Knowledge Base** Use the **Knowledge Base** field to pick an existing knowledge base from the dropdown, or click **+ New Knowledge Base** to create one inline. Switch to **Variable** mode to pass a knowledge base reference dynamically from upstream. Knowledge Base Reader node settings panel showing Search Query, Knowledge Base selection, and configuration options **Step 5: Connect Outputs to Downstream Nodes** Connect the relevant output — `chunks`, `documents`, `pages`, or `formatted_text` — to the node that will consume the retrieved content. Knowledge Base Reader node connected to upstream and downstream nodes on the canvas ### Inputs * `Search Query` \* — The query used to search the knowledge base. Supports variable references via `{{`. * `Knowledge Base` \* — The knowledge base to search. Select from a list, pass as a variable, or create inline. ### Outputs * `chunks` — A list of semantically similar text segments retrieved from the knowledge base. Available when Retrieval Unit is set to Chunks. Best for fine-grained content retrieval. * `documents` — A list of full or partial documents retrieved from the knowledge base. Available when Retrieval Unit is set to Documents. Best when broader document-level context is needed. * `pages` — A list of page-level segments retrieved from the knowledge base. Available when Retrieval Unit is set to Pages. Best for page-aware retrieval over long documents. * `citation_metadata` — A list of source references for the retrieved results, used to surface citations in LLM responses. * `formatted_text` — Retrieved content pre-formatted as a single string ready for direct LLM input. Available when **Format Context for LLM** is enabled (on by default). * `response` — A generated answer produced from the retrieved content. Available when **Do Advanced QA** or **Set Response Format** is enabled. Becomes `stream` when **Stream Response** is also enabled. ### Node Options **Core Settings** * `Max Docs Per Query` *(Integer, default: 10)* — Maximum number of results to retrieve per query. * `Retrieval Unit` *(Dropdown, default: Chunks)* — What unit of content is retrieved. Options: `Chunks`, `Documents`, `Pages`. Each produces a different output key. * `Score Cutoff` *(Decimal, default: 0)* — Minimum similarity score a result must meet to be returned. A value of 0 returns everything. * `Format Context for LLM` *(Toggle, default: Yes)* — Formats retrieved content for LLM input. * `Alpha` *(Decimal, default: 0.6)* — Balance between semantic and keyword search in hybrid retrieval. Higher values weight semantic search more heavily. **Advanced Settings** * `Enable Filter` *(Toggle, default: No)* — Enables metadata-based filtering. When enabled, a `filter` input field appears. * `Enable Context` *(Toggle, default: No)* — Passes additional context with the query. When enabled, a `context` input field appears. * `Rerank Documents` *(Toggle, default: No)* — Reranks results for better relevance. When enabled: * `Rerank Model` — Model used for reranking (default: `cohere/rerank-english-v3.0`) * `Num Chunks to Rerank` *(Integer, default: 10)* * `Transform Query` *(Toggle, default: No)* — Rewrites the query before retrieval to improve results. * `Answer Multiple Questions` *(Toggle, default: No)* — Handles compound or multi-part queries in a single pass. * `Expand Query` *(Toggle, default: No)* — Expands the query to improve recall. * `Expand Query Terms` *(Toggle, default: No)* — Adds related terms to broaden search coverage. * `Generate Metadata Filters` *(Toggle, default: No)* — Derives metadata filters from the query automatically. * `Do Advanced QA (beta)` *(Toggle, default: No)* — Generates a direct answer from retrieved content. When enabled, `citation_metadata` is populated and a `response` output is added. Additional fields: * `QA Model` — Model used to generate the answer (default: `gpt-4o-mini`) * `Advanced Search Mode` — `fast` or `accurate` (default: `accurate`) * `Set Response Format` *(Toggle, default: No)* — Enables a custom response format with a `System Prompt` field. * `Stream Response` *(Toggle, default: No)* — Streams the response progressively. Only takes effect when **Set Response Format** is also enabled; changes `response` output to `stream`. * `Enable Document DB Filter` *(Toggle, default: No)* — Applies document-level filters during retrieval. When enabled, a `document_db_filter` field appears. * `Do NL Metadata Query` *(Toggle, default: No)* — Enables natural language querying against document metadata. ### Best Practices * Pass the user's query dynamically from an Input node rather than hardcoding a search term * Use `formatted_text` for straightforward RAG workflows; use `chunks`, `documents`, or `pages` when you need more control over content assembly * Set `Score Cutoff` above 0 to filter out low-relevance results * Use **Enable List Mode** (right-click the node) when processing multiple queries in a single run In agents, a knowledge base is added to the agent so it can query it autonomously through the **Query Knowledge Base** tool — deciding on its own when to look something up based on the conversation context, without any explicit retrieval step needed. The **Query Knowledge Base** tool is pre-added as a default tool for conversational agents. Once a knowledge base is added to the agent, the tool is always present in the agent's tool list. When the knowledge base input is set to dynamic (variable mode), the agent searches across all available knowledge bases rather than a single fixed one. ### Key Use Cases * Giving an agent access to internal documentation, policies, or support articles to answer user questions * Grounding an agent's responses in specific, curated content rather than relying solely on the model's training * Building a customer-facing assistant that can look up product information or FAQs on demand * Connecting an agent to a knowledge base synced from an integration like Google Drive for always-up-to-date content ### How It Works **Step 1: Open Your Agent** Navigate to the agent you want to configure. Knowledge base setup happens at the agent level. **Step 2: Add a Knowledge Base** Under the **Knowledge Base** section on the agent page, add content via file upload, integration sync, URL scraping, workspace files, or table indexing. **Step 3: Test in the Agent Chat** Use the agent's chat panel to test retrieval. Ask questions that should trigger a knowledge base lookup and verify the agent is pulling the right content. ### Query Knowledge Base Tool Agent tool panel showing the Query Knowledge Base tool in the tool list The agent uses the **Query Knowledge Base** tool autonomously — you do not need to configure when or how it is invoked. From the tool list you can: * **Edit** — Adjust the tool's configuration * **Auto Run** — Set whether the tool executes automatically or prompts the user for confirmation before running Query Knowledge Base tool requiring user approval, showing the search query and knowledge base fields in the approval dialog **Tool Description** The tool description tells the agent when and how to use the knowledge base. You can customize this to guide the agent's retrieval behavior — for example, specifying what types of questions should trigger a lookup. ### Configuring Input Fields Each input field on the Query Knowledge Base tool can be configured in one of two ways: * **Locked value** — Set a fixed value for the field. The agent will always use this value when querying the knowledge base. Use this when the input should remain constant (e.g., always query a specific knowledge base, always return 5 results). * **Agent-determined** — Leave the field for the agent to fill automatically based on conversation context. The agent decides the appropriate value at runtime. Use this for fields like the search query, where the value depends on what the user is asking. Query Knowledge Base tool configuration panel showing Search Query and Knowledge Base fields with sparkle icon to toggle between dynamic and static values This applies to all input fields on the tool, including `Search Query`, `Knowledge Base`, `Max Docs Per Query`, and any advanced settings. ### Advanced Settings * `Settings` — Adjust retrieval settings for the knowledge base as used by the agent. * `Add Document` — Add more content to the knowledge base at any time after creation. ### Common Issues For a full list of known issues and troubleshooting steps, refer to the [Common Issues](#) documentation. ### Best Practices * Keep the knowledge base focused — add content directly relevant to what the agent is meant to do; a broad, unfocused knowledge base leads to lower retrieval quality * Sync integrations like Google Drive so the knowledge base stays current without manual updates * Test retrieval thoroughly in the chat panel before deploying — ask a range of questions to verify the agent surfaces the right content * If the agent is not querying the knowledge base when expected, check the **Auto Run** setting on the Query Knowledge Base tool # Listen — Button Source: https://docs.vectorshift.ai/nodes/listen-button/overview Present users with clickable buttons during a conversation and wait for their selection. Add it in Python with `pipeline.add(name="...").listen(...)`. See the SDK reference. The Button node (a variant of the Listen node) presents users with clickable buttons during a chatbot conversation and pauses the flow until the user selects one. Use it to build guided conversational experiences — for example, letting a user choose between "Check Balance", "Transfer Funds", and "Contact Support", or presenting approval options like "Approve" and "Reject" in a compliance review flow. ## Core Functionality * Displays one or more clickable buttons to the user at a specific step in the conversation * Pauses the conversation flow until the user clicks a button (or sends a message, if allowed) * Routes the conversation to a different path based on which button was clicked * Optionally allows the user to type a free-text message instead of clicking a button ## Tool Inputs * `Button 1`, `Button 2`, `Button 3`, etc. — Text. The label displayed on each button. Default: `Button 1`. Add more buttons with the **+ Add Buttons** button. Remove buttons with the trash icon. * `Allow user message` — Toggle. Default: `No`. When enabled, the user can type a free-text message in addition to clicking a button. The message is routed to the `User Message` output path. ## Tool Outputs Each button creates a corresponding output path: * `button_1` — Path. Activates when the user clicks Button 1. * `button_2` — Path. Activates when the user clicks Button 2. * `button_3` — Path. Activates when the user clicks Button 3. (One output per button.) * `user_message` — Path. Activates when the user sends a typed message instead of clicking a button. Only available when `Allow user message` is enabled. * `complete` — Path. Advanced output. Activates when any selection is made. *** ### Overview In workflows, the Button node sits in a conversational workflow and presents the user with a set of choices. When the conversation reaches this node, the chatbot displays the buttons and waits. Each button's output path connects to a different branch of the workflow, enabling conditional logic based on the user's selection. This is ideal for building menu-driven chatbots, multi-step approval flows, or guided decision trees. listen button connect with nodes ### Use Cases * Present account action options ("Check Balance", "Transfer Funds", "View Statements") in a banking chatbot and route to the appropriate workflow branch * Build an approval flow where reviewers click "Approve" or "Reject" to trigger different downstream actions * Create a guided troubleshooting flow where users select their issue type from a set of buttons * Offer product tier selection ("Basic", "Professional", "Enterprise") in a sales chatbot to route to the right pricing workflow * Implement a feedback collection step with sentiment buttons ("Satisfied", "Neutral", "Dissatisfied") at the end of a support conversation ### How It Works #### Step 1: Add a Start Node The Button node requires a Start node on the canvas. If no Start node is present, a dialog appears: *"To use this node, drag a start node onto the canvas."* Add a Start node from the **Start** tab first. #### Step 2: Add the Button Node In the workflow canvas, click the **Chat** tab in the node palette, click **Listen**, then select **Button** from the variant list. Drag it onto the canvas. listen button drag into canvas #### Step 3: Configure Buttons The node starts with one button (`Button 1`). Edit the label text for each button. Click **+ Add Buttons** to add more options. Remove unwanted buttons with the trash icon. #### Step 4: Configure Allow User Message (Optional) Toggle `Allow user message` to `Yes` if you want the user to be able to type a free-text response instead of clicking a button. When enabled, a `User Message` output path appears on the node. #### Step 5: Connect Output Paths Each button creates a separate output path handle (`button_1`, `button_2`, etc.). Connect each handle to the downstream nodes or branches that should execute when that button is clicked. If `Allow user message` is enabled, also connect the `User Message` output to a branch that handles free-text input. #### Step 6: Test the Flow Deploy the workflow as a chatbot and verify that buttons appear at the correct step. Click each button and confirm it routes to the expected branch. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ------ | -------- | --------------------------------------------------------------------- | | `Button 1`, `Button 2`, etc. | Text | Button 1 | The label displayed on each button. | | `Allow user message` | Toggle | No | Allow the user to type a message instead of clicking a button. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. **Advanced setting.** | ### Best Practices * **Use clear, action-oriented button labels.** Labels like "Check Balance" or "Approve Transfer" are better than generic "Option A" or "Yes" — they tell the user exactly what will happen. * **Limit buttons to 3–5 options.** Too many buttons overwhelm users. If you need more choices, consider cascading Button nodes (first select a category, then a sub-option). * **Enable Allow user message for flexibility.** In many conversational flows, users may want to ask a question or provide context instead of picking a predefined option. Enable this toggle and route the free-text path to an LLM for handling. * **Use the complete output for shared logic.** If some downstream processing should happen regardless of which button was clicked, connect the `complete` advanced output to that shared branch. * **Pair with Talk nodes.** Place a Talk (Message) node before the Button node to explain the choices — for example, "How can I help you today?" followed by the button options. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Provides real-time customer support directly embedded within a website interface. Reviews and routes refund or expense requests based on policy rules and approval thresholds. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Listen — Capture Source: https://docs.vectorshift.ai/nodes/listen-capture/overview Pause the conversation and wait for the user to respond, storing their message for downstream use. Add it in Python with `pipeline.add(name="...").listen(...)`. See the SDK reference. The Capture node (a variant of the Listen node) pauses the conversation at a specific step and waits for the user to type a response. The user's message is stored in the `response` output and passed to downstream nodes. Use it to build multi-step conversational flows — for example, asking a follow-up question after presenting information, collecting free-text feedback, or pausing for user confirmation before proceeding with an action. ## Core Functionality * Pauses the conversational workflow at the current step and waits for the user to respond in the chat * Captures the user's typed message and stores it in the `response` output variable * Resumes the workflow and passes the captured response to downstream nodes * Works with the Start node and other conversational nodes (Talk, Button) to build multi-step chat flows ## Tool Inputs This node has no configurable input fields. It simply pauses and waits for user input. ## Tool Outputs * `response` — Text. The user's message captured at this step in the conversation. *** ### Overview In workflows, the Capture node acts as a pause point in a conversational workflow. When the flow reaches this node, the chatbot waits for the user to type a message. Once the user responds, the workflow resumes and the `response` output carries the user's text to the next node — typically an LLM for processing, a condition node for branching, or another conversational node. Use it between Talk nodes to create back-and-forth dialogue. ### Use Cases * Pause after presenting a financial summary and capture the user's follow-up question for an LLM to answer * Collect free-text feedback after completing a support interaction and route it to a sentiment analysis node * Ask the user to confirm a transaction ("Please type CONFIRM to proceed") and validate their response with a condition node * Gather additional context after an initial classification — e.g., "Can you describe the issue in more detail?" * Build a multi-turn interview flow where each Capture node collects one answer before moving to the next question ### How It Works #### Step 1: Add a Start Node The Capture node requires a Start node on the canvas. If no Start node is present, a dialog appears: *"To use this node, drag a start node onto the canvas."* Add a Start node from the **Start** tab first. #### Step 2: Add the Capture Node In the workflow canvas, click the **Chat** tab in the node palette, click **Listen**, then select **Capture** from the variant list. Drag it onto the canvas. listen capture drag into canvas #### Step 3: Connect Upstream Nodes listen capture connect with nodes Connect the Capture node after a Talk (Message) node or other conversational node. The Capture node pauses the flow at this point and waits for the user's response. #### Step 4: Connect the Response Output Connect the `response` output to the downstream node that should process the user's message — for example, an LLM node, a condition node, or another Talk node. #### Step 5: Test the Flow Deploy the workflow as a chatbot. Verify that the conversation pauses at the Capture step and resumes correctly once the user sends a message. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ------ | ------- | --------------------------------------------------------------------- | | `Show Success/Failure Outputs` | Toggle | Off | Show additional success/failure output handles. **Advanced setting.** | ### Best Practices * **Always precede Capture with a Talk node.** Users need context for what to type. Place a Talk (Message) node before the Capture to ask a clear question or provide instructions. * **Use descriptive node names.** Rename the Capture node to describe what it collects (e.g., "Capture Feedback", "Capture Confirmation") so the workflow is easy to follow. * **Validate captured input when needed.** If the user's response must meet specific criteria (e.g., a date format, a confirmation keyword), connect the `response` output to a condition node before proceeding. * **Chain multiple Talk-Capture pairs.** For multi-step data collection, alternate Talk (Message) and Capture nodes to create a structured back-and-forth conversation. * **Consider using Button instead for constrained choices.** If you need the user to pick from a fixed set of options rather than typing freely, use the Button variant of Listen instead. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Verifies customer identities and performs Know Your Customer checks for onboarding compliance. Answers employee questions about internal policies and flags potential compliance issues. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Merge - Join All Source: https://docs.vectorshift.ai/nodes/merge-join-all/overview Recombine multiple conditional paths into a single list output by joining all input values. Add it in Python with `pipeline.add(name="...").merge(...)`. See the SDK reference. The Merge node in Join All mode recombines multiple execution paths into a single output by collecting all input values into a list. Use it after a Condition or AI Routing node to gather results from every branch that executed — for example, combining extracted data from parallel document processing paths into one consolidated list, or aggregating results from multiple API calls before passing them to a summary step. ## Core Functionality * Collects values from multiple input fields and joins them into a single list output * Designed to recombine paths created by Condition or AI Routing nodes * Supports configurable input/output types (Text, Integer, Decimal, File, JSON, and more) * Allows adding or removing input fields dynamically * Outputs a list (vector) of the configured type ## Tool Inputs * `Function` — The merge strategy. Set to `Join All` to collect all inputs into a list. Dropdown. * `Type` — The expected data type of the input and output fields. Dropdown with options: `Text`, `List of Text`, `Integer`, `Any`, `Decimal`, `Boolean`, `File`, `Audio`, `Image`, `JSON`, `Timestamp`, `Path`, `List of Files`, `Knowledge Base`. Default: `Text`. * `Input 1` — The first input value. Connect from an upstream node or enter directly. Type matches the selected `Type`. * `Input 2` — The second input value. Same as above. * Additional inputs can be added with **+ Add Field**. ## Tool Outputs * `output` — A list (vector) of the configured type containing all input values. For example, if `Type` is `Text` and you provide three text inputs, the output is a list of three text strings. *** ### Overview In workflows, the Merge node in Join All mode sits downstream of branching nodes (Condition, AI Routing) to recombine their outputs. It collects values from all connected input fields into a single list, which you can then pass to downstream nodes for aggregation, summarization, or further processing. Use it when every branch produces a result and you need all of them together. ### Use Cases * Aggregate extracted financial metrics from parallel document processing branches into a single list for reporting * Combine API responses from multiple provider calls into one consolidated result set * Collect validation results from separate rule-checking branches into a summary list * Gather translated text outputs from parallel language-specific branches * Merge compliance check results from multiple regulatory paths into one review list ### How It Works #### Step 1: Add the Merge Node In the workflow canvas, click the **Logic** tab in the node palette and click **Merge**. Drag it onto the canvas. Workflow node palette showing the Logic tab with Merge option #### Step 2: Set the Function to Join All In the Merge node, set the **Function** dropdown to **Join All**. This configures the node to collect all inputs into a list. #### Step 3: Configure the Type Select the expected data type from the **Type** dropdown. This determines what kind of data the input fields accept and what the output list contains. For example, select `Text` for text values or `JSON` for structured data. #### Step 4: Connect Input Fields The node starts with two input fields (**Input 1** and **Input 2**). Connect each to an upstream node's output — typically from different branches of a Condition or AI Routing node. Click **+ Add Field** to add more input fields as needed. Each new field gets a connection handle on the left. #### Step 5: Connect the Output The `output` handle on the right side of the node produces a list containing all input values. Connect it to downstream nodes for further processing. Merge Join All node connected to input and output nodes #### Step 6: Test the Workflow Click **Run** to test. The Merge node collects all non-empty input values into a list and passes them downstream. ### Settings | Setting | Type | Default | Description | | ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Function` | Dropdown | Join All | The merge strategy. Set to Join All to combine all inputs into a list. | | `Type` | Dropdown | Text | The data type of input fields and output list. Options: Text, List of Text, Integer, Any, Decimal, Boolean, File, Audio, Image, JSON, Timestamp, Path, List of Files, Knowledge Base. | | `Input 1` | Configured type | — | First input value. Connect from upstream. | | `Input 2` | Configured type | — | Second input value. Connect from upstream. | | `+ Add Field` | Button | — | Adds additional input fields. | ### Best Practices * **Match the Type to your data.** Set the `Type` dropdown to match what your upstream branches produce. A mismatch can cause type errors at runtime. * **Use after Condition nodes for aggregation.** Place the Merge (Join All) node downstream of a Condition node when you need to collect results from all branches — for example, gathering validation results from multiple checks. * **Add only the fields you need.** Each input field should correspond to one branch or upstream output. Remove unused fields to keep the canvas clean. * **Chain with a Join List Items node.** If you need the output as a single concatenated string instead of a list, connect the Merge output to a Join List Items node downstream. * **Handle empty inputs gracefully.** If a branch doesn't execute (because its condition wasn't met), its input to the Merge node may be empty. Plan for this in downstream processing. ### Related Templates Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Side-by-side comparison of documents to highlight differences and track revisions. Validates data and documents against predefined rules, schemas, or compliance standards. Reconciles financial statements by identifying mismatches and resolving discrepancies. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Merge - Pick First Source: https://docs.vectorshift.ai/nodes/merge-pick-first/overview Recombine multiple conditional paths by selecting the first available input value. Add it in Python with `pipeline.add(name="...").merge(...)`. See the SDK reference. The Merge node in Pick First mode recombines multiple execution paths by selecting the first non-empty input value. Use it after a Condition or AI Routing node when only one branch executes at a time and you need to funnel its result back into a single downstream path — for example, picking the result from whichever extraction workflow the Condition node activated, or selecting the first successful API response from multiple fallback branches. ## Core Functionality * Selects the first non-empty input value from multiple input fields * Designed to recombine paths created by Condition or AI Routing nodes * Supports configurable input/output types (Text, Integer, Decimal, File, JSON, and more) * Allows adding or removing input fields dynamically * Outputs a single value of the configured type (not a list) ## Tool Inputs * `Function` — The merge strategy. Set to `Pick First` to select the first non-empty input. Dropdown. * `Type` — The expected data type of the input and output fields. Dropdown with options: `Text`, `List of Text`, `Integer`, `Any`, `Decimal`, `Boolean`, `File`, `Audio`, `Image`, `JSON`, `Timestamp`, `Path`, `List of Files`, `Knowledge Base`. Default: `Text`. * `Input 1` — The first input value. Connect from an upstream node or enter directly. Type matches the selected `Type`. * `Input 2` — The second input value. Same as above. * Additional inputs can be added with **+ Add Field**. ## Tool Outputs * `output` — A single value of the configured type. Contains the first non-empty input value, evaluated in order from Input 1 to Input N. *** ### Overview In workflows, the Merge node in Pick First mode sits downstream of branching nodes (Condition, AI Routing) to funnel their outputs back into a single path. It checks each input field in order and passes through the first one that has a value. This is the standard pattern for recombining conditional branches where only one branch executes at a time — the active branch produces a result, inactive branches are empty, and Pick First selects the one that ran. ### Use Cases * Funnel the result from whichever Condition branch executed back into a single downstream path * Select the first successful API response when multiple provider endpoints are tried in parallel * Pick the output of the matching document type extractor after AI Routing classifies the document * Merge results from cascading fallback logic — try the primary path, fall back to secondary * Recombine outputs from locale-specific processing branches into a single result ### How It Works #### Step 1: Add the Merge Node In the workflow canvas, click the **Logic** tab in the node palette and click **Merge**. Drag it onto the canvas. Workflow node palette showing the Logic tab with Merge option #### Step 2: Set the Function to Pick First In the Merge node, set the **Function** dropdown to **Pick First**. This configures the node to select the first non-empty input. #### Step 3: Configure the Type Select the expected data type from the **Type** dropdown. This determines what kind of data the input fields accept and what the output contains. The type should match what your upstream branches produce. #### Step 4: Connect Input Fields The node starts with two input fields (**Input 1** and **Input 2**). Connect each to the output of a different branch — typically from a Condition or AI Routing node. Input 1 has the highest priority; if it has a value, it is selected regardless of other inputs. Click **+ Add Field** to add more input fields. Click the red **−** button to remove one. #### Step 5: Connect the Output The `output` handle on the right side of the node produces the single selected value. Connect it to downstream nodes for further processing. Merge Pick First node connected to input and output nodes #### Step 6: Test the Workflow Click **Run** to test. The Merge node evaluates inputs in order and outputs the first non-empty value. ### Settings | Setting | Type | Default | Description | | ------------- | --------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Function` | Dropdown | Pick First | The merge strategy. Set to Pick First to select the first non-empty input. | | `Type` | Dropdown | Text | The data type of input fields and output. Options: Text, List of Text, Integer, Any, Decimal, Boolean, File, Audio, Image, JSON, Timestamp, Path, List of Files, Knowledge Base. | | `Input 1` | Configured type | — | First input value (highest priority). Connect from upstream. | | `Input 2` | Configured type | — | Second input value. Connect from upstream. | | `+ Add Field` | Button | — | Adds additional input fields. | ### Best Practices * **Use after Condition nodes for single-branch results.** Pick First is the standard pattern when a Condition node routes to exactly one branch and you need to continue with a single output downstream. * **Order inputs by priority.** Input 1 is evaluated first. If multiple branches could produce a value, connect the highest-priority branch to Input 1. * **Match the Type to your upstream outputs.** Set the `Type` dropdown to match the data type your branches produce. A mismatch can cause unexpected behavior. * **Pair with Join All when needed.** If some workflows need all branch results (not just the first), use a second Merge node in Join All mode for those cases. * **Use for fallback patterns.** Connect a primary data source to Input 1 and a fallback to Input 2. If the primary fails (produces no output), Pick First automatically selects the fallback. ### Related Templates Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Side-by-side comparison of documents to highlight differences and track revisions. Validates data and documents against predefined rules, schemas, or compliance standards. Reconciles financial statements by identifying mismatches and resolving discrepancies. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Note Source: https://docs.vectorshift.ai/nodes/note/overview Add rich-text sticky notes to the workflow canvas for documentation and annotation. Add it in Python with `pipeline.add(name="...").sticky_note(...)`. See the SDK reference. The Note element adds a sticky note to the workflow canvas for documentation, annotation, and team communication. Use it to leave context for collaborators — for example, explaining why a particular branching logic exists, documenting expected input formats, or marking sections of the workflow that are under construction. ## Core Functionality * Places a resizable sticky note on the workflow canvas that does not affect execution * Supports rich-text formatting: bold, italic, underline, lists, code blocks, and headings (H1, H2, H3) * Includes a color picker to visually categorize notes (default: yellow) * Purely visual — the Note has no inputs, outputs, or settings that affect the workflow ## Tool Inputs The Note element has no inputs. It does not connect to other nodes or participate in data flow. ## Tool Outputs The Note element has no outputs. It is a canvas annotation only. *** ### Overview In workflows, the Note element is a visual annotation tool that sits on the canvas alongside your nodes. It does not execute, produce data, or connect to other nodes — it exists solely to help you and your team document the workflow. Notes are especially valuable in complex workflows where the purpose of a section, a configuration choice, or an edge case would otherwise be unclear. ### Use Cases * Document the purpose of a complex branching section so team members understand the logic at a glance * Mark a section of the workflow as "in progress" or "needs review" during collaborative development * Record expected input formats or assumptions (e.g., "Input must be a PDF under 10 MB") * Leave onboarding notes for new team members who will maintain the workflow * Annotate workarounds or known limitations in specific parts of the workflow ### How It Works #### Step 1: Add a Note In the workflow canvas, click the **Start** tab in the node palette and click **Note**. A yellow sticky note appears on the canvas. Note element on the canvas showing the Start tab with Note option #### Step 2: Enter Text Click inside the note and type your annotation. The placeholder text reads: *"Enter note text here..."* Note element with text entered #### Step 3: Format the Text (Optional) Click the formatting toolbar above the note to apply rich-text formatting: * **Bold** (B), **Italic** (I), **Underline** (U) * Bulleted list * Code block * Headings: **H1**, **H2**, **H3** Note element showing the formatting toolbar #### Step 4: Change the Color (Optional) Click the color dot in the toolbar to change the note's background color. Use different colors to categorize notes by purpose (e.g., yellow for general documentation, red for warnings). #### Step 5: Resize and Position Drag the resize handle at the bottom-right corner to adjust the note's size. Drag the note itself to reposition it on the canvas near the relevant nodes. ### Settings The Note element has no configurable settings. It is a visual canvas element only. ### Best Practices * **Place notes near the nodes they describe.** Position notes adjacent to the section of the workflow they document so the context is immediately clear. * **Use color coding consistently.** Adopt a team convention — for example, yellow for general documentation, red for warnings or known issues, green for completed/verified sections. * **Keep notes concise.** Notes are for quick context, not full documentation. A few sentences explaining "why" is more valuable than a paragraph describing "what". * **Use headings for multi-topic notes.** If a note covers multiple points, use H1/H2/H3 headings to organize the content. * **Remove stale notes.** As the workflow evolves, review and update or remove notes that no longer apply to avoid confusion. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Open Source LLM Source: https://docs.vectorshift.ai/nodes/open-source/overview Generate text responses using open-source models from Together AI in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Open Source LLM node connects your workflows to open-source language models hosted on Together AI, including Meta Llama, Mistral, Google Gemma, DeepSeek, and NVIDIA NeMo. Use it to access cost-effective, high-quality models for tasks like classifying financial transactions, generating research summaries, or building AI workflows with models you can evaluate and audit. ## Core Functionality * Access open-source models from Meta Llama, Mistral, Google Gemma, DeepSeek, and others via Together AI * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `deepseek-ai/DeepSeek-R1`) Select from available open-source models. Click **Dropdown** to view all options * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own Together AI API key * `Api Key` — (String) Your Together AI API key. Required when `Use Personal Api Key` is enabled — the node will show a validation error if left blank * `JSON Schema` — (String) JSON schema to enforce structured output. Only visible when `JSON Response` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Open Source LLM node in workflows lets you place an open-source model on the canvas via Together AI's hosting infrastructure. This gives you access to a wide range of models from different research labs, enabling cost optimization and model evaluation within your workflows. ## Use Cases * **Cost-optimized batch processing** — Route high-volume, lower-complexity tasks like transaction tagging to cost-effective open-source models while reserving premium models for complex analysis. * **Model evaluation and comparison** — Compare outputs across different open-source model families to find the best quality-to-cost ratio for specific financial tasks. * **Research summarization** — Use DeepSeek or Llama models to summarize research papers, market reports, or regulatory updates at scale. * **Regulatory document classification** — Classify documents by type, jurisdiction, or urgency using open-source models that perform well on categorization tasks. * **Internal knowledge Q\&A** — Build cost-effective internal chatbots using open-source models grounded in your organization's documentation. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Open Source** node onto the canvas. Open Source node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference upstream node outputs. 4. **Select a model.** Use the `Model` dropdown to choose an open-source model. Available options include `deepseek-ai/DeepSeek-R1`, `meta-llama/Llama-3-70b-chat-hf`, `mistralai/Mistral-7B-Instruct-v0.1`, `mistralai/Mixtral-8x7B-Instruct-v0.1`, `google/gemma-2-27b-it`, `nvidia/Llama-3.1-Nemotron-Ultra-253B-v1`, and others. Open Source node showing the Model dropdown 5. **Provide an API key.** Toggle `Use Personal Api Key` to **Yes** and enter your Together AI API key. 6. **Open settings.** Click the **gear icon** (⚙) to configure token limits, temperature, retry behavior, and more. Open Source node settings panel 7. **Connect outputs and run.** Wire the `response` output to downstream nodes and execute the workflow. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ----------- | ------------------------------------------------------------------- | | `Provider` | Dropdown | Open Source | The LLM provider (Together AI). | | `Max Tokens` | Integer | 128000 | Maximum number of input + output tokens per run. | | `Temperature` | Float | 0.5 | Controls response creativity. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token. | | `JSON Output` | Boolean | Off | Return output as structured JSON. | | `Show Sources` | Boolean | Off | Display source documents used for the response. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max Retries` | Integer | — | Maximum retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `SSN` | Boolean | Off | Detect and redact Social Security numbers from input. | | `Credit Card` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports. | ## Best Practices * **Start with DeepSeek-R1 for reasoning tasks.** It offers strong reasoning capabilities at a lower cost than commercial alternatives. * **Use Llama models for general-purpose tasks.** Meta's Llama family provides excellent general performance for summarization and Q\&A. * **Compare models before committing.** Swap the model dropdown to test different models on the same inputs and evaluate quality-to-cost tradeoffs. * **Monitor token usage.** Open-source models via Together AI are billed per token — track consumption for budgeting. * **Enable PII detection for client data.** Even with open-source models, apply PII toggles when processing sensitive financial information. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # OpenAI LLM Source: https://docs.vectorshift.ai/nodes/openai/overview Generate text responses using OpenAI's GPT models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The OpenAI LLM node connects your workflows to OpenAI's GPT family of language models. Use it to generate text responses, analyze documents, answer questions grounded in knowledge bases, or produce structured JSON outputs — for example, drafting investment memos from research notes, classifying financial transactions, or extracting key terms from contracts using the latest GPT models. ## Core Functionality * Generate text completions and conversational responses using GPT models * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `gpt-5.1`) Select from available GPT models. Click **Dropdown** to view all options * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own OpenAI API key instead of VectorShift's shared key * `Api Key` — (String) Your OpenAI API key. Only visible when `Use Personal Api Key` is enabled * `JSON Schema` — (String) JSON schema to enforce structured output format. Only visible when `JSON Response` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The OpenAI LLM node in workflows lets you place a GPT model directly on the canvas, wire inputs and outputs to other nodes, and configure model behavior through the settings panel. OpenAI models are widely adopted and offer strong general-purpose performance across a range of financial and analytical tasks. ## Use Cases * **Investment memo drafting** — Generate structured investment memos by combining analyst research notes, market data, and portfolio context into a coherent summary. * **Financial transaction classification** — Categorize transactions by type, risk level, or regulatory relevance using natural language understanding. * **Contract term extraction** — Extract key terms, obligations, and dates from legal and financial contracts using JSON mode for structured output. * **Client communication generation** — Draft personalized portfolio update emails by combining market data with client-specific holdings and preferences. * **Regulatory Q\&A** — Build chatbots that answer compliance questions grounded in your organization's policy knowledge base. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **OpenAI** node onto the canvas. OpenAI node being dragged onto the canvas from the AI category 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to define the model's behavior, tone, and how it should use any data provided in the prompt. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to open the variable builder and reference outputs from upstream nodes. 4. **Select a model.** Use the `Model` dropdown to choose a GPT model. Available options include `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5.1-codes`, `o4-mini`, `gpt-4.1`, `gpt-4.1-mini`, `chatgpt-4o-latest`, `gpt-4o`, `gpt-4o-mini`, and others. OpenAI node showing the Model dropdown with available GPT models 5. **Open settings.** Click the **gear icon** (⚙) to configure token limits, temperature, reasoning effort, retry behavior, and more. OpenAI node settings panel showing token limits, temperature, and other configuration options 6. **Connect outputs.** Click the **Outputs** button to open the outputs panel. Wire the `response` output to downstream nodes. OpenAI node connected to upstream and downstream nodes on the canvas 7. **Run your workflow.** Execute the workflow to process inputs and return the generated response along with usage metrics. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `Provider` | Dropdown | OpenAI | The LLM provider. | | `Max Tokens` | Integer | 128000 | Maximum number of input + output tokens the model will process per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning the model applies to its response. | | `Verbosity` | Dropdown | Default | Controls the verbosity of model responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Higher values produce more diverse outputs; lower values produce more deterministic responses. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Higher values consider more tokens at each generation step. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token. | | `JSON Response` | Boolean | Off | Return output as structured JSON. When enabled, a `JSON Schema` input appears. | | `Show Sources` | Boolean | Off | Display source documents used for the response. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max Retries` | Integer | — | Maximum retry attempts. Visible when `Retry On Failure` is enabled. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retry attempts. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names from input. | | `Email` | Boolean | Off | Detect and redact email addresses from input. | | `Phone` | Boolean | Off | Detect and redact phone numbers from input. | | `SSN` | Boolean | Off | Detect and redact Social Security numbers from input. | | `Credit Card` | Boolean | Off | Detect and redact credit card numbers from input. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports on the node. | ## Best Practices * **Select the right model for your task.** Use `gpt-5.1` or `gpt-5` for complex reasoning; `gpt-5-mini` or `gpt-4o-mini` for cost-effective batch processing of simpler tasks. * **Use JSON mode for structured extraction.** Enable `JSON Response` and provide a schema for consistent, machine-readable output when extracting financial data. * **Monitor token usage.** Connect `tokens_used` and `credits_used` outputs to tracking nodes, especially for high-volume batch processing. * **Enable Safe Context Token Window for variable-length inputs.** Prevents token-limit errors when processing documents of unpredictable size. * **Use streaming for interactive interfaces.** Enable streaming when powering client-facing chatbots for responsive user experience. * **Apply PII detection for regulated data.** Enable SSN and other PII toggles when processing client financial records. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Analyzes contracts to extract key terms, flag risks, and summarize obligations. Reviews and routes refund or expense requests based on policy rules and approval thresholds. Handles common customer inquiries and support tickets through conversational AI. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Output Source: https://docs.vectorshift.ai/nodes/output/overview Output data of different types from your workflow as the final result of execution. Add it in Python with `pipeline.add(name="...").output(...)`. See the SDK reference. The Output node defines the final result of a workflow. It accepts data from upstream nodes and presents it as the workflow's return value — whether in the run interface, API response, or chatbot reply. Use it to surface LLM-generated text, processed files, images, structured JSON, or any other data type as the workflow's deliverable. ## Core Functionality * Defines a typed output parameter for the workflow that appears in the run result, API response, or chatbot reply * Supports multiple data types: Text, File, List of Files, Image, Audio, Streamed Text, JSON, Integer, Decimal, Boolean, Timestamp, and Dataframe * Optionally formats the output for display * The node name becomes the output field label in the workflow's results ## Tool Inputs * `Type` — Dropdown. Default: `Text`. The data type of the output. Options: Text, File, List of Files, Image, Audio, Streamed Text, JSON, Integer, Decimal, Boolean, Timestamp, Dataframe. * `Output` \* — Varies by type. Required. The data to output. Connect an upstream node's output or type a value with `{{}}` variable syntax. * `Format output` — Toggle. Default: `Yes`. When enabled, the output is formatted for display (e.g., markdown rendering for text). \* *Required field* ## Tool Outputs The Output node has no downstream outputs. It is a terminal node that surfaces data as the workflow's result. *** ### Overview In workflows, the Output node is the terminal point where processed data is delivered to the user or calling system. Every workflow needs at least one Output node to return results. The output appears in the Run dialog, API response, chatbot message, or form result depending on how the workflow is deployed. Use multiple Output nodes to return several result fields from a single workflow run. ### Use Cases * Return an LLM-generated summary as Text output in a document analysis workflow * Output a processed PDF (e.g., a filled form or generated report) as a File for the user to download * Stream an LLM's response in real-time using Streamed Text for a chatbot deployment * Return structured extraction results as JSON for an API consumer to parse programmatically * Output a generated chart or diagram as an Image in a data visualization workflow ### How It Works #### Step 1: Add the Output Node In the workflow canvas, click the **Start** tab in the node palette and click **Output**. Drag it onto the canvas. output drag into canvas #### Step 2: Name the Output Rename the node to describe the result (e.g., "Summary", "Report File", "Analysis Results"). The name appears as the output field label in the workflow's results. #### Step 3: Select the Data Type Use the `Type` dropdown to select the appropriate type for the data being output. The default is `Text`. The `Output` input field updates to accept the matching type. Output node showing the Type dropdown with available output types #### Step 4: Connect the Input Connect the upstream node's output to the `Output` field. For example, connect an LLM node's response to a Text output, or a file processing node's result to a File output. This field is required — the node shows a validation error if left empty. output connect with nodes #### Step 5: Configure Settings (Optional) Click the settings icon to open the Settings panel: * **`Description`** — Enter a description for this output. This text helps users understand what the output represents. * **`Format output`** — Toggle on (default) to enable formatted display (e.g., markdown rendering). Toggle off for raw output. ### Settings | Setting | Type | Default | Description | | --------------- | -------- | ------- | -------------------------------------------- | | `Type` | Dropdown | Text | The data type of the output. | | `Output` | Varies | — | The data to output. Required. | | `Format output` | Toggle | Yes | Enable formatted display of the output. | | `Description` | Text | — | A description of what the output represents. | ### Best Practices * **Use Streamed Text for chatbots.** When deploying as a chatbot, use the Streamed Text type instead of Text to stream the LLM's response in real-time rather than waiting for the full response. * **Name outputs descriptively.** When a workflow returns multiple outputs, clear names like "Summary" and "Source Documents" are far better than "output\_0" and "output\_1". * **Use JSON for API integrations.** When the workflow is called via API, JSON output provides structured data that consuming applications can parse directly. * **Match the type to the upstream data.** Using the correct type ensures the output renders properly — for example, Image type for generated images, File type for downloadable documents. * **Add descriptions for complex outputs.** If the output requires interpretation (e.g., a JSON schema or a specific format), use the Description field to document what consumers should expect. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Perplexity LLM Source: https://docs.vectorshift.ai/nodes/perplexity/overview Generate text responses with built-in web search using Perplexity's Sonar models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The Perplexity LLM node connects your workflows to Perplexity's Sonar models, which combine language generation with real-time web search. Use it to generate responses grounded in current web data — for example, researching recent market developments, monitoring competitor announcements, or answering questions that require up-to-date information beyond your training data. ## Core Functionality * Generate text responses with built-in real-time web search capabilities * Access Perplexity Sonar models optimized for research and reasoning * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `sonar-reasoning-pro`) Select from available Perplexity models * `Use Personal Api Key` — (Boolean, default: `No`) Toggle to use your own Perplexity API key * `Api Key` — (String) Your Perplexity API key. Only visible when `Use Personal Api Key` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The Perplexity LLM node in workflows provides access to Sonar models that can search the web in real time as part of their response generation. Unlike standard LLMs that rely only on training data, Perplexity models actively retrieve current information, making them ideal for time-sensitive financial research and monitoring. ## Use Cases * **Real-time market research** — Query current stock prices, recent earnings announcements, or breaking financial news with responses grounded in live web data. * **Competitor monitoring** — Track recent competitor product launches, pricing changes, or partnership announcements across the web. * **Regulatory update tracking** — Monitor recent regulatory changes, SEC filings, or compliance guidance updates in real time. * **Due diligence research** — Research target companies using current web sources, including recent news, press releases, and financial coverage. * **Market sentiment analysis** — Analyze current market sentiment by searching and synthesizing recent financial commentary and analyst opinions. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **Perplexity** node onto the canvas. Perplexity node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field to guide the model's response behavior. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to reference upstream node outputs. 4. **Select a model.** Use the `Model` dropdown to choose a Perplexity model. The default `sonar-reasoning-pro` provides strong reasoning with web search. Perplexity node showing the Model dropdown 5. **Open settings.** Click the **gear icon** (⚙) to configure settings. Perplexity node settings panel 6. **Connect outputs.** Wire the `response` output to downstream nodes. The response includes information retrieved from the web. Perplexity node connected to upstream and downstream nodes 7. **Run your workflow.** Execute the workflow to get responses grounded in current web data. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ---------- | ------------------------------------------------------------------------------ | | `Provider` | Dropdown | Perplexity | The LLM provider. | | `Max Tokens` | Integer | 127072 | Maximum number of input + output tokens per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning. | | `Verbosity` | Dropdown | Default | Controls the verbosity of responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token. | | `JSON Output` | Boolean | Off | Return output as structured JSON. | | `Show Sources` | Boolean | Off | Display source documents used for the response. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. | | `Safe Context Token Window` | Boolean | Off | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max Retries` | Integer | — | Maximum retry attempts. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retries. | | **PII Detection** | | | | | `Name` | Boolean | Off | Detect and redact personal names. | | `Email` | Boolean | Off | Detect and redact email addresses. | | `Phone` | Boolean | Off | Detect and redact phone numbers. | | `SSN` | Boolean | Off | Detect and redact Social Security numbers. | | `Credit Card` | Boolean | Off | Detect and redact credit card numbers. | | `Address` | Boolean | Off | Detect and redact physical addresses. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports. | ## Best Practices * **Use for time-sensitive queries.** Perplexity excels when responses need current data — use it for market research, news monitoring, and regulatory tracking. * **Combine with static data sources.** Feed knowledge base context through the prompt alongside Perplexity's web search for comprehensive answers that blend internal and external data. * **Enable Show Sources.** When grounding is important (e.g., compliance workflows), enable `Show Sources` to trace where the model retrieved its information. * **Monitor costs.** Web-search-augmented models may consume more tokens. Track usage for budgeting. * **Apply PII detection.** Enable relevant PII toggles when processing financial data through the model. ## Related Templates Identifies and analyzes foreign exchange arbitrage opportunities across markets and instruments. Provides real-time customer support directly embedded within a website interface. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Post Message Source: https://docs.vectorshift.ai/nodes/post-message/overview Post a message to an active chat session programmatically from within a workflow. Add it in Python with `pipeline.add(name="...").post_message(...)`. See the SDK reference. The Post Message node sends a message to an active chat session from within a workflow. It enables workflows to programmatically inject messages into a conversation — useful for delivering proactive notifications, status updates, or follow-up information to a user's ongoing session without requiring the user to send a new message first. ## Core Functionality * Posts a text message to a specified chat session by session ID * Enables workflows to push messages into active conversations asynchronously * Returns a status indicator confirming whether the message was delivered successfully * Works with any VectorShift chatbot session, including those deployed via website widget, API, Slack, or WhatsApp ## Tool Inputs * `Session ID` \* — Text. The unique identifier of the chat session to post the message to. Connect from an upstream node or reference a stored session ID using `{{variable}}` syntax. * `Message` \* — Text. The message content to post to the session. Can be a static string, a dynamically generated LLM response, or any text value from an upstream node. post message connect with nodes \* *Required field* ## Tool Outputs * `status` — Text. The status of the message post, indicating whether the message was delivered successfully. *** ### Overview In workflows, the Post Message node allows a workflow to push messages into an active chat session without waiting for the user to send a new message. This is particularly useful for long-running workflows that need to provide progress updates, for event-driven workflows that deliver notifications to a user's session, or for multi-step processes where the system needs to follow up after an initial conversation. The node requires a valid session ID and a message, and it returns a status indicating delivery success. ### Use Cases * Send a trade confirmation or order status update to a client's active chat session after a backend process completes * Deliver real-time portfolio alerts (e.g., a stock crossing a price threshold) to an advisor's open session * Push compliance review results back to a user's conversation after an asynchronous document analysis finishes * Notify a customer in their chat session when a scheduled report (e.g., monthly account statement) is ready for download * Send follow-up information to a session after an approval workflow completes — for example, confirming a wire transfer has been initiated ### How It Works #### Step 1: Add the Post Message Node In the workflow canvas, click the **Chat** tab in the node palette and click **Post Message**. Drag it onto the canvas. post message drag into canvas #### Step 2: Provide the Session ID Connect the `Session ID` input to a node that supplies the target session's identifier. This is typically obtained from a trigger, a stored variable, or a previous workflow run that captured the session ID. #### Step 3: Provide the Message Connect the `Message` input to the text content you want to post. This can come from an LLM node, a Text node, a template with variables, or any upstream node that produces text. #### Step 4: Connect the Output Connect the `status` output to a downstream node if you need to verify delivery or branch logic based on success or failure. For example, connect it to a Condition node to handle failed deliveries. #### Step 5: Configure Settings (Optional) Click the settings icon to access additional options: * **Show Success/Failure Outputs** — Toggle on to expose separate output handles for success and failure paths, enabling conditional logic based on the delivery result. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ------ | ------- | ------------------------------------------------------------- | | `Session ID` | Text | — | The session to post the message to. Required. | | `Message` | Text | — | The message to post to the session. Required. | | `Show Success/Failure Outputs` | Toggle | Off | Expose separate output handles for success and failure paths. | ### Best Practices * **Store session IDs reliably.** Ensure the session ID is captured and stored (e.g., via a variable or database) at the start of the conversation so it can be referenced later by asynchronous workflows. * **Validate before posting.** Use a Condition node upstream to verify that the session ID is not empty before attempting to post, avoiding unnecessary failures. * **Handle delivery failures.** Enable the Show Success/Failure Outputs toggle and add error-handling logic for cases where the session has expired or the ID is invalid. * **Keep messages concise.** Messages posted to a session should be clear and actionable — avoid sending large blocks of text that could overwhelm the chat interface. * **Use for asynchronous follow-ups.** The Post Message node is most valuable when a workflow runs independently of the chat session (e.g., triggered by a cron job or an external event) and needs to deliver results back to the user. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Summarizes and surfaces key CRM data insights for sales and relationship management teams. Handles investor inquiries related to portfolios, statements, and fund performance. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Read Session Messages Source: https://docs.vectorshift.ai/nodes/read-session-messages/overview Read all messages from an agent session with filtering, pagination, and derived metadata. Add it in Python with `pipeline.add(name="...").read_session_messages(...)`. See the SDK reference. The Read Session Messages node retrieves messages from an agent session, with options to filter by message type and paginate results. Use it to extract conversation history, analyze agent responses, audit tool calls, or review reasoning traces — for example, reading the full conversation from a compliance review session, extracting all tool call results for logging, or pulling reasoning messages for quality assurance. ## Core Functionality * Reads messages from an existing agent session by session ID * Filters messages by type: all, data type, reasoning, request, response, component, error, search, status, and reauthorize * Supports pagination via offset to handle large conversation histories * Returns structured outputs: raw messages, clean conversation, tool calls, reasoning, and session result ## Tool Inputs * `Session ID` \* — Text. Required. The ID of the session to read messages from. * `Message Filter` — Dropdown. Default: `None (All Messages)`. Filter messages by type. Options: None (All Messages), Data Type Message, Reasoning Message, Request Message, Response Message, Component Message, Error Message, Search Message, Set Participant Status, Reauthorize Error. * `Offset` — Integer. Default: `0`. Number of messages to skip from the beginning. Supports Number and Variable modes. read session messages settings \* *Required field* ## Tool Outputs * `messages` — List\. All raw session messages as JSON strings. * `conversation` — List\. Clean conversation messages (text and reasoning only). * `tool_calls` — List\. Tool calls with status and request/response data. * `reasoning_messages` — List\. Reasoning and thinking messages from the agent. * `result` — Text. Overall session result and metadata as JSON. *** ### Overview In workflows, the Read Session Messages node connects to a session created by the Create Session node (via session ID) and retrieves the conversation contents. It provides multiple output views of the data — raw messages, clean conversation text, tool calls, and reasoning — making it easy to route different aspects of the conversation to different downstream processing nodes. read session messages connect with nodes ### Use Cases * Read the full conversation from a client onboarding session and generate a summary report using an LLM * Extract all tool call results from an automated analysis session for logging and audit * Pull reasoning messages from a compliance review session to verify the agent's decision-making process * Read error messages from a failed session to diagnose issues and trigger retry logic * Retrieve the session result to check whether the agent completed its task successfully ### How It Works #### Step 1: Add the Read Session Messages Node In the workflow canvas, click the **Chat** tab and click **Read Messages**. Read Session Messages node being added from the Chat tab #### Step 2: Connect the Session ID Connect the `Session ID` input from an upstream Create Session or Post Message node's session ID output. #### Step 3: Configure Message Filter (Optional) Use the `Message Filter` dropdown to narrow results to a specific message type. Leave as "None (All Messages)" to retrieve everything. #### Step 4: Set Offset (Optional) Set the `Offset` value to skip a number of messages from the beginning. Useful for pagination in long conversations. #### Step 5: Connect Outputs Connect the relevant outputs to downstream nodes: `conversation` for human-readable text, `tool_calls` for audit logs, `reasoning_messages` for QA review, or `result` for session status. ### Settings | Setting | Type | Default | Description | | ------------------------------ | ----------- | ------------------- | ----------------------------------------------------- | | `Session ID` | Text | — | The session to read from. Required. | | `Message Filter` | Dropdown | None (All Messages) | Filter by message type. | | `Offset` | Integer | 0 | Number of messages to skip. | | `Show Success/Failure Outputs` | Toggle | Off | Show additional output handles. **Advanced setting.** | | `Dependencies` | List\ | — | Control execution order. **Advanced setting.** | ### Best Practices * **Use Message Filter for targeted analysis.** Instead of processing all messages, filter to the specific type you need (e.g., Error Messages for debugging, Tool Calls for audit). * **Pair with Create Session and Post Message.** The typical pattern is: Create Session → Post Message → Read Session Messages to orchestrate and then analyze agent conversations. * **Use Offset for long conversations.** In sessions with many messages, use offset to paginate and process in batches. * **Route outputs to specialized processing.** Connect `conversation` to an LLM for summarization, `tool_calls` to a logging workflow, and `result` to a condition node for branching. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Summarizes and surfaces key CRM data insights for sales and relationship management teams. Handles investor inquiries related to portfolios, statements, and fund performance. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Semantic Search Source: https://docs.vectorshift.ai/nodes/semantic-search/overview Generate a temporary vector database at runtime and retrieve the most relevant content from documents based on a query. Add it in Python with `pipeline.add(name="...").semantic_search(...)`. See the SDK reference. The Semantic Search node creates a temporary vector database at runtime from provided documents and retrieves the most relevant pieces based on a natural language query. Unlike querying a persistent knowledge base, this node embeds and searches documents on-the-fly — making it ideal for searching through dynamic content that hasn't been pre-indexed. Use it to find relevant passages in uploaded documents, filter through large text collections, or build retrieval-augmented generation (RAG) workflows. ## Core Functionality * Generate a temporary vector index from documents at runtime * Retrieve semantically similar chunks, documents, or pages based on a natural language query * Choose from a wide range of embedding models (OpenAI, Cohere, Voyage, etc.) * Optionally rerank results for improved relevancy * Support advanced search features including query transformation, multi-question extraction, and hybrid search * Configure chunking strategy, document analysis, and context formatting ## Tool Inputs * `Embedding Model` — Dropdown · Default: `OpenAI Text Embedding 3 Small` · The model used to generate embeddings. Supports multiple providers including OpenAI, Cohere, Voyage, Google, and others. * `Search Query` \* — **Required** · Text · The natural language query used to search documents for relevant content. * `Documents for Search` \* — **Required** · Text (multiple) · The text to search through. You can connect multiple upstream nodes to this field. * `Max Docs Per Query` — Integer · Default: `5` · Maximum number of relevant chunks to return. * `Rerank Documents` — Boolean · Default: `false` · Refine the initial ranking of returned chunks based on relevancy. * `Retrieval Unit` — Dropdown · Default: `Chunks` · Options: `Chunks`, `Documents`, `Pages` · What to return — individual chunks, full documents with metadata, or complete pages. * `Splitter Method` — Dropdown · Default: `Markdown` · Options: `Sentence`, `Markdown`, `Dynamic` · Chunking strategy for the temporary index. * `Segmentation Method` — Dropdown · Default: `Words` · Options: `Words`, `Sentences`, `Paragraphs` · Text segmentation method (visible when Splitter Method is Dynamic). * `Analyze Documents` — Boolean · Default: `false` · Analyze and enrich document contents when parsing. * `Hybrid Mode` — Boolean · Default: `false` · Create a hybrid index combining vector and keyword search. * `Enable Filter` — Boolean · Default: `false` · Filter content returned from the search. * `Enable Context` — Boolean · Default: `false` · Provide additional context to advanced search and query analysis. * `Transform Query` — Boolean · Default: `false` · Transform the query for better semantic search. * `Answer Multiple Questions` — Boolean · Default: `false` · Extract separate questions and retrieve content for each. * `Expand Query` — Boolean · Default: `false` · Expand the query to improve search. * `Expand Query Terms` — Boolean · Default: `false` · Expand query terms to improve search. * `Do Advanced QA` — Boolean · Default: `false` · Use additional LLM calls to analyze each document and improve answer correctness. * `Format Context for LLM` — Boolean · Default: `false` · Format the retrieved context for LLM consumption. * `Score Cutoff` — Float · Default: `0` · Minimum similarity score threshold for returned results. * `Alpha` — Float · Default: `0.5` · The alpha value for hybrid retrieval. \* indicates a required field. ## Tool Outputs * `chunks` — List of Text · Semantically similar chunks retrieved from the documents. Present when Retrieval Unit is Chunks. * `documents` — List of Text · Semantically similar documents with metadata. Present when Retrieval Unit is Documents. * `response` — Text · The response from advanced QA. Present when Do Advanced QA is enabled. * `formatted_text` — Text · Knowledge base outputs formatted for LLM input. Present when Format Context for LLM is enabled. * `citation_metadata` — List of Text · Citation metadata for search outputs. Present when Do Advanced QA is enabled. ## Overview In workflows, the Semantic Search node embeds and searches through documents provided at runtime. Connect upstream text or document nodes to provide the search corpus, and wire a query input to find relevant content. The node creates a temporary vector index, performs the search, and outputs matching chunks or documents for downstream processing. ## Use Cases * **RAG workflow** — A workflow takes a user question as input, loads relevant documents, runs Semantic Search to find the most relevant passages, and passes them to an LLM for answer generation. * **Document comparison** — A workflow searches through a set of uploaded contracts to find clauses relevant to a specific topic or keyword. * **Dynamic content retrieval** — A workflow receives fresh data (API responses, web scrapes) and performs semantic search without needing to pre-index into a knowledge base. * **Financial document analysis** — A workflow searches through earnings transcripts or regulatory filings for passages related to specific financial metrics or risk factors. * **Multi-document Q\&A** — A workflow ingests multiple uploaded PDFs and uses Semantic Search to find and aggregate answers across all of them. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Semantic Search** onto the canvas. Semantic Search node being dragged onto the canvas 2. **Select the embedding model** — Choose an embedding model from the `Embedding Model` dropdown. The default (OpenAI Text Embedding 3 Small) works well for most use cases. 3. **Connect the query** — Wire a text input to the `Search Query` field. This field is required. 4. **Connect the documents** — Wire one or more text outputs to the `Documents for Search` field. This field is required. You can connect multiple upstream nodes. 5. **Configure search options** — Set `Max Docs Per Query`, `Retrieval Unit`, and optional features like `Rerank Documents`, `Hybrid Mode`, or `Do Advanced QA`. Semantic Search node settings panel showing Search Query, Documents for Search, and configuration options 6. **Connect outputs** — Wire `chunks`, `documents`, `response`, or `formatted_text` to downstream nodes. Semantic Search node connected to upstream and downstream nodes on the canvas 7. **Run the workflow** — Execute the workflow. The node builds a temporary index, searches it, and passes results downstream. ## Settings * `Embedding Model` — Dropdown · Default: `OpenAI Text Embedding 3 Small` · Vector embedding model. * `Search Query` — Text · **Required** · The search query. * `Documents for Search` — Text (multiple) · **Required** · Documents to index and search. * `Max Docs Per Query` — Integer · Default: `5` · Max results to return. * `Rerank Documents` — Boolean · Default: `false` · Rerank results for relevancy. * `Retrieval Unit` — Dropdown · Default: `Chunks` · Return type (Chunks, Documents, Pages). **Advanced Settings:** * `Splitter Method` — Dropdown · Default: `Markdown` · Chunking strategy. * `Segmentation Method` — Dropdown · Default: `Words` · Segmentation method (with Dynamic splitter). * `Analyze Documents` — Boolean · Default: `false` · Enrich documents during parsing. * `Hybrid Mode` — Boolean · Default: `false` · Vector + keyword hybrid search. * `Enable Filter` — Boolean · Default: `false` · Filter returned content. * `Transform Query` — Boolean · Default: `false` · Query transformation. * `Answer Multiple Questions` — Boolean · Default: `false` · Multi-question extraction. * `Expand Query` / `Expand Query Terms` — Boolean · Default: `false` · Query expansion. * `Do Advanced QA` — Boolean · Default: `false` · LLM-enhanced answer generation. * `Format Context for LLM` — Boolean · Default: `false` · Format output for LLM input. * `Score Cutoff` — Float · Default: `0` · Minimum similarity threshold. * `Alpha` — Float · Default: `0.5` · Hybrid retrieval balance. * `Enable Context` — Boolean · Default: `false` · Pass additional context to search. ## Best Practices * **Choose the right embedding model** — For financial documents, models like OpenAI Text Embedding 3 Large or Voyage provide higher accuracy at slightly higher cost. Use smaller models for speed on less critical searches. * **Enable reranking for precision** — When accuracy matters more than speed, enable `Rerank Documents` to refine the initial results using a dedicated reranking model. * **Use hybrid mode for keyword-heavy content** — Financial documents often contain specific identifiers (tickers, CUSIP numbers, regulation names) where keyword matching complements semantic search. * **Set appropriate max docs** — Start with 5 and increase if the downstream LLM needs more context. Too many results can overwhelm the LLM's context window. * **Connect multiple document sources** — The Documents for Search input accepts multiple connections, so you can search across documents from different upstream nodes in a single query. * **Use Advanced QA sparingly** — Enabling Do Advanced QA adds LLM calls per document, which increases latency and cost. Use it only when answer accuracy is critical. ## Related Templates Automatically categorizes and tags incoming documents based on content and type. Side-by-side comparison of documents to highlight differences and track revisions. Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Validates data and documents against predefined rules, schemas, or compliance standards. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Set Variable Source: https://docs.vectorshift.ai/nodes/set-variable/overview Set a workflow variable to a new value or expression during workflow execution. Add it in Python with `pipeline.add(name="...").set_variable(...)`. See the SDK reference. The Set Variable node lets you assign a new value to a workflow variable during workflow execution. Use it to update counters, store intermediate results, toggle flags, or pass computed values between different stages of a workflow — for example, updating a running total as you process line items in a financial report, or setting a status variable that downstream nodes reference for conditional logic. ## Core Functionality * Sets a workflow variable to a new value at runtime * Selects from existing variable sets defined in the project * Supports any variable data type defined in the variable set * Validates that a variable is selected before execution ## Tool Inputs * `Variable Set` \* — The variable set containing the target variable. Dropdown listing variable sets defined in the project (e.g., `New Project 1 Variables`). Required. * `Variable` \* — The specific variable to update. Dropdown listing variables within the selected variable set. Required. Shows the variable reference (e.g., `{{Variables_1}}`). * `Value` \* — The new value to assign to the variable. Required. The input type is determined by the selected variable's data type. Can be entered directly or connected from an upstream node. \* *Required field* ## Tool Outputs The Set Variable node does not produce data outputs. It updates the variable's value in place. Downstream nodes access the updated value by referencing the variable directly. *** ### Overview In workflows, the Set Variable node updates a workflow variable's value during execution. It references the project's variable sets and lets you select which variable to update. The value can come from an upstream node connection or be entered manually. Use it to maintain state across workflow steps — for example, accumulating a running total, storing a flag that controls downstream conditional branches, or saving an intermediate calculation result for later use. ### Use Cases * Update a running total variable as each line item in a financial report is processed * Set a status flag variable to control downstream Condition node branching * Store an extracted value (e.g., account number, total amount) from a document for use later in the workflow * Reset a counter variable at the start of a loop iteration * Save an LLM-generated classification result into a variable for reference by multiple downstream nodes ### How It Works #### Step 1: Add the Set Variable Node In the workflow canvas, click the **Logic** tab in the node palette and click **Set Variables**. Drag it onto the canvas. Workflow node palette showing the Logic tab with Set Variables option #### Step 2: Select the Variable Set In the `Variable Set` dropdown, select the variable set that contains the variable you want to update. Variable sets are defined at the project level — for example, `New Project 1 Variables`. #### Step 3: Select the Variable In the `Variable` dropdown, select the specific variable to update. The dropdown lists all variables defined in the selected variable set, displayed as references (e.g., `{{Variables_1}}`). #### Step 4: Set the Value Enter the new value in the `Value` field, or connect it from an upstream node's output. The input type matches the selected variable's data type. If the `Variable` field is left empty, the node shows a validation error: *"Variable field is required."* #### Step 5: Connect and Run Connect the Set Variable node into your workflow at the point where the variable should be updated. Downstream nodes can reference the updated variable value. Set Variable node connected to input nodes in a workflow Click **Run** to test. Verify that the variable is updated correctly by checking its value in downstream nodes. ### Settings | Setting | Type | Default | Description | | -------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------ | | `Variable Set` | Dropdown | — | The project variable set containing the target variable. Required. | | `Variable` | Dropdown | — | The specific variable to update. Required. Displays as a variable reference (e.g., `{{Variables_1}}`). | | `Value` | Variable type | — | The new value to assign. Type matches the variable's defined data type. Required. | ### Best Practices * **Define variables before using this node.** Create your variable sets and variables at the project level first. The Set Variable node can only update existing variables — it cannot create new ones. * **Use meaningful variable names.** Name your variables descriptively (e.g., `running_total`, `approval_status`) so the workflow logic is clear when reviewing the canvas. * **Place strategically in the workflow.** Position the Set Variable node at the exact point where the variable's value should change. Variable updates are immediate — any downstream node that references the variable will see the new value. * **Pair with Condition nodes for stateful logic.** Set a flag variable (e.g., `is_approved = true`) and then use a Condition node downstream to branch based on that flag. * **Avoid circular dependencies.** Do not create loops where a Set Variable node's input depends on the same variable it is setting. This can cause unpredictable behavior. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Speech to Text Source: https://docs.vectorshift.ai/nodes/speech-to-text/overview Transcribe audio to text using AI models in your workflows and agents. Add it in Python with `pipeline.add(name="...").ai_speech_to_text(...)`. See the SDK reference. The Speech to Text node converts audio input into text using AI transcription models. Use it to transcribe meeting recordings, earnings call audio, client voicemails, or any audio content — enabling downstream text processing like summarization, search indexing, or compliance review. ## Core Functionality * Transcribe audio files to text using AI speech recognition models * Support multiple providers including OpenAI (Whisper) and Deepgram * Select specialized model tiers for different accuracy and speed tradeoffs * Use personal API keys for dedicated access ## Tool Inputs * `Provider` \* — (Enum (Dropdown), default: `OpenAI`) Select the transcription provider (OpenAI, Deepgram) * `Model` \* — (Enum (Dropdown), default: `whisper-1`) Select the speech-to-text model * `Audio` \* — (Audio) The audio file to transcribe * `Tier` — (Enum (Dropdown), default: `general`) Deepgram-specific: select the transcription tier. Only visible when provider is Deepgram * `Use Personal API Key` — (Boolean, default: `No`) Toggle to use your own API key * `Api Key` — (String) Your API key. Only visible when `Use Personal API Key` is enabled \* indicates a required field ## Tool Outputs * `text` — (String) The transcribed text from the audio ## Overview The Speech to Text tool in agents allows the AI to transcribe audio files shared during conversations. The agent can process voice messages, meeting recordings, or any audio content and return the transcribed text. ## Use Cases * **Meeting transcription** — Users share meeting recordings and the agent provides full transcriptions for note-taking. * **Voicemail processing** — Transcribe client voicemails for documentation and follow-up tracking. * **Audio content search** — Convert audio to text to enable search across audio archives. * **Compliance recording review** — Transcribe compliance-relevant recordings for review and documentation. ## How It Works 1. **Add the tool to your agent.** In the agent builder, click **Add Tool** and select **Speech to Text** from the available tools. Agent tool panel showing Transcribe Speech (Speech to Text) tool in the tool list 2. **Configure input fields.** Each field can either be filled automatically by the agent based on conversation context, or locked to a fixed value: * `Provider` — Select the transcription provider (e.g., OpenAI) * `Model` — Choose the model (e.g., `whisper-1`) * `Audio` — The agent uses audio files shared in the conversation Transcribe Speech tool configuration showing fields with sparkle icon to toggle between dynamic and static values 3. **Write the Tool Description.** Describe what the tool does so the agent knows when to use it. 4. **Set Auto Run behavior.** Choose: Auto Run, Require User Approval, or Let Agent Decide. 5. **Test the tool.** Share an audio file with the agent and ask it to transcribe. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ----------- | --------------------------- | | `Provider` | Dropdown | OpenAI | The transcription provider. | | `Model` | Dropdown | `whisper-1` | The speech-to-text model. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Use OpenAI Whisper for general transcription.** It provides strong accuracy across languages and accents. * **Select Deepgram for specialized needs.** Deepgram offers different tiers optimized for specific use cases. * **Chain with an LLM node.** Connect the `text` output to an LLM node for automatic summarization of transcribed content. ## Related Templates Analyzes earnings call transcripts for sentiment, key themes, and forward-looking signals. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. ## Overview The Speech to Text node in workflows lets you connect an audio input to a transcription model and output the text to downstream nodes. This enables automated audio processing workflows. ## Use Cases * **Earnings call transcription** — Automatically transcribe earnings call recordings and feed the text to summarization nodes. * **Batch audio processing** — Process multiple audio files through consistent transcription settings. * **Voice-to-text workflows** — Convert voice inputs into text for further analysis, classification, or storage. * **Compliance monitoring** — Transcribe recorded client interactions for compliance review workflows. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Audio** category and drag the **Speech to Text** node onto the canvas. Speech to Text node being dragged onto the canvas 2. **Select a provider and model.** Choose the `Provider` (e.g., OpenAI) and `Model` (e.g., `whisper-1`) from the dropdowns. 3. **Connect the audio input.** Wire an audio output from an upstream node to the `Audio` input. 4. **Connect the text output.** Wire the `text` output to downstream nodes for further processing. 5. **Run your workflow.** Execute the workflow to transcribe the audio. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ----------- | ----------------------------------------------------------------------------- | | `Provider` | Dropdown | OpenAI | The transcription provider (OpenAI, Deepgram). | | `Model` | Dropdown | `whisper-1` | The speech-to-text model. | | `Tier` | Dropdown | `general` | Deepgram-specific transcription tier. Only visible when provider is Deepgram. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Match the provider to your needs.** Use OpenAI Whisper for general-purpose transcription; Deepgram for real-time or specialized use cases. * **Chain with LLM nodes.** Feed transcribed text directly into LLM nodes for summarization, analysis, or data extraction. * **Process audio in supported formats.** Ensure audio files are in a supported format (MP3, WAV, etc.) before feeding them to the node. ## Related Templates Analyzes earnings call transcripts for sentiment, key themes, and forward-looking signals. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Start Source: https://docs.vectorshift.ai/nodes/start-node/overview Define the entry point for conversational workflows that use Talk and Listen nodes. Add it in Python with `pipeline.add(name="...").start_flag(...)`. See the SDK reference. The Start node marks the beginning of a conversational workflow. It tells the workflow engine where to begin executing a step-by-step conversation flow built with Talk and Listen nodes. Every conversational workflow requires exactly one Start node. ## Core Functionality * Defines the single entry point for conversational workflows that use Talk and Listen nodes * Signals to the workflow engine that the workflow follows a sequential conversational flow rather than a standard data-processing workflow * Replaces Input, Output, and Trigger nodes — adding a Start node converts the workflow to conversational mode and prevents those node types from being used * Connects to downstream conversational nodes (e.g., Message, Capture, Button, Card, Carousel) via edge connections ## Tool Inputs This node has no configurable inputs. The Start node functions purely as an entry-point marker with no parameters to set. ## Tool Outputs This node has no data outputs. It defines the conversational flow entry point and connects to downstream nodes through edge connections rather than data handles. *** ### Overview In workflows, the Start node is the required entry point for any conversational workflow. When a workflow contains a Start node, it operates in conversational mode — the engine walks through the connected nodes sequentially, presenting messages (Talk nodes) and collecting responses (Listen nodes) one step at a time. Without a Start node, conversational nodes like Message and Capture display a warning and cannot execute. Only one Start node is allowed per workflow. ### Use Cases * Build a client intake chatbot that greets the user, collects account details, and routes to the appropriate advisor based on responses * Create a loan pre-qualification flow that asks income, credit, and employment questions step by step before returning an eligibility decision * Design an expense-report submission assistant that walks employees through category selection, amount entry, and receipt upload in a guided conversation * Implement a portfolio risk-assessment questionnaire that captures investment horizon, risk tolerance, and asset preferences through sequential prompts * Automate a KYC (Know Your Customer) verification process that collects identification documents and personal information through a structured conversational flow ### How It Works #### Step 1: Add the Start Node In the workflow canvas, click the **Start** tab in the node palette and click **Start**. Drag the node onto the canvas. Start node being dragged onto the canvas from the Start tab #### Step 2: Connect to the First Conversational Node Draw an edge from the Start node to your first Talk or Listen node (e.g., a Message node that greets the user). This edge defines where the conversation begins. Start node connected to downstream conversational nodes #### Step 3: Build the Conversation Flow Continue connecting Talk and Listen nodes in sequence. Each edge defines the next step in the conversation. The workflow engine follows these connections in order at runtime. #### Step 4: Deploy Deploy the workflow as a chatbot or voicebot interface. When a user starts a session, the engine begins at the Start node and walks through the connected conversational nodes. ### Settings The Start node has no configurable settings. It functions as a simple entry-point marker for the conversational flow. ### Best Practices * **Use exactly one Start node per workflow.** The engine requires a single entry point. Adding more than one Start node is not supported. * **Keep the Start node at the top or left of the canvas.** Position it where the flow begins visually so the conversation path reads naturally from left to right or top to bottom. * **Do not mix with Input/Output nodes.** Once a Start node is present, the workflow is in conversational mode. Use Talk nodes to present information and Listen nodes to collect input instead. * **Connect directly to a greeting message.** The first node after Start should be a Talk Message node that orients the user — for example, "Welcome! How can I help you today?" * **Test the full conversation path before deploying.** Use the preview or run dialog to walk through every branch and confirm the flow behaves as expected. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Sync Knowledge Base Source: https://docs.vectorshift.ai/nodes/sync-knowledge-base/overview Trigger a sync to re-process all documents and integrations in a knowledge base. Add it in Python with `pipeline.add(name="...").knowledge_base_sync(...)`. See the SDK reference. The Sync Knowledge Base node triggers a synchronization for a selected knowledge base, re-processing all its documents and refreshing any connected integrations. Use it to keep knowledge bases up to date — for example, triggering a sync after loading new documents, or scheduling periodic refreshes to pick up changes from connected data sources like Google Drive or Confluence. ## Core Functionality * Trigger a sync operation on an existing knowledge base * Re-process all documents in the knowledge base to update embeddings and indexes * Refresh content from connected integrations (e.g., Google Drive, Confluence, Notion) * Can be triggered manually or as part of an automated workflow ## Tool Inputs * `Knowledge Base` \* — **Required** · Knowledge Base selector · The knowledge base to sync. \* indicates a required field. ## Tool Outputs This node does not produce outputs. It triggers the sync operation on the selected knowledge base. ## Overview In workflows, the Sync Knowledge Base node triggers a sync operation as a workflow step. This is useful for automated workflows that need to ensure a knowledge base is up to date before querying it, or for scheduled workflows that periodically refresh knowledge base content from connected integrations. ## Use Cases * **Post-load refresh** — After loading new documents with a Knowledge Base Loader node, trigger a sync to ensure the new content is fully indexed and searchable. * **Scheduled integration sync** — A cron-triggered workflow syncs a knowledge base connected to Google Drive or Confluence on a daily schedule to pick up any document changes. * **Pre-query freshness guarantee** — Before running a Knowledge Base Agent query, sync the knowledge base to ensure results reflect the latest document state. * **Multi-knowledge-base refresh** — A workflow iterates over multiple knowledge bases and syncs each one as part of a nightly maintenance workflow. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **Knowledge** category. Drag **Sync Knowledge Base** onto the canvas. Sync Knowledge Base node being dragged onto the canvas 2. **Select the knowledge base** — Use the `Knowledge Base` selector to choose which knowledge base to sync. This field is required. 3. **Position in the workflow** — Place the Sync Knowledge Base node after any document loading or modification steps, and before any query or retrieval steps that depend on fresh data. Sync Knowledge Base node connected to upstream and downstream nodes on the canvas 4. **Run the workflow** — Execute the workflow. The node triggers the sync operation on the selected knowledge base. ## Settings * `Knowledge Base` — Knowledge Base selector · **Required** · The knowledge base to sync. ## Best Practices * **Sync after loading** — Always place a Sync Knowledge Base node after Knowledge Base Loader nodes to ensure newly loaded documents are fully processed and indexed. * **Use with cron triggers** — For knowledge bases connected to external integrations, set up a cron-triggered workflow that runs the sync on a regular schedule (e.g., daily or hourly). * **Allow processing time** — Sync operations can take time for large knowledge bases. If downstream nodes depend on the sync being complete, consider adding appropriate dependencies. * **Avoid unnecessary syncs** — Only sync when content has changed or when integration sources may have updated. Frequent syncs on unchanged knowledge bases consume processing resources without benefit. ## Related Templates Centralized searchable repository of investment committee memos for quick reference. Answers employee questions about internal policies and flags potential compliance issues. Handles investor inquiries related to portfolios, statements, and fund performance. Ensures all closing documents meet regulatory and legal requirements before settlement. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # Talk — Card Source: https://docs.vectorshift.ai/nodes/talk-card/overview Send a rich card with image, title, description, and button in a conversational workflow. Add it in Python with `pipeline.add(name="...").talk(...)`. See the SDK reference. The Card node (a variant of the Talk node) sends a rich card component to the user at a specific step in a chatbot conversation. A card combines an image, title, description, and a clickable button into a single visual element. Use it to present structured information — for example, displaying a product listing with a purchase link, showing a service option with a booking button, or presenting a document summary with a download link. ## Core Functionality * Sends a card component with image, title, description, and action button to the user * The button supports Link action type, navigating the user to a specified URL when clicked * Requires a Start node on the canvas to function * Does not produce outputs — it is a display-only node ## Tool Inputs * `Title` — Text. The card's title text. * `Description` — Text. The card's description text. * `Image` — Image. The card's header image. * `Content` — Text. Additional content text for the card. Default: "This is content". * `Button Name` — Text. The label displayed on the button. Default: "Submit". * `Button URL` — Text. The URL to navigate to when the button is clicked. Default: "[https://vectorshift.ai/](https://vectorshift.ai/)". * `Button Action Type` — The action to occur when the button is clicked. Default: "Link". ## Tool Outputs The Card node has no outputs. It is a display-only node. *** ### Overview In workflows, the Card node presents a visually rich component in the chat interface. It combines multiple pieces of information — an image, title, description, and call-to-action button — into a single card that users can interact with. This is ideal for presenting options, showcasing products, or providing structured summaries with actionable links. ### Use Cases * Present investment fund options with fund name, description, performance chart, and a "Learn More" link * Show product recommendations in an e-commerce chatbot with image, name, price, and a "Buy Now" button * Display a document summary card with a title, brief description, and "Download PDF" button * Present service tier options (Basic, Professional, Enterprise) with features and pricing links * Show a contact card for a financial advisor with their photo, name, role, and a "Schedule Meeting" button ### How It Works #### Step 1: Add a Start Node The Card node requires a Start node on the canvas. #### Step 2: Add the Card Node In the workflow canvas, click the **Chat** tab, click **Talk**, then select **Card** from the variant list. Talk Card node being dragged onto the canvas from the Chat tab #### Step 3: Configure the Card Content Fill in the card fields: `Title`, `Description`, `Image`, and `Content`. These can be static text or connected from upstream nodes via variables. talk card connect with nodes #### Step 4: Configure the Button Set the `Button Name` (label), `Button URL` (destination), and `Button Action Type` (default: Link). The button appears at the bottom of the card. #### Step 5: Connect in the Flow Place the Card node at the appropriate point in the conversation where the card should appear. ### Settings | Setting | Type | Default | Description | | -------------------- | ----- | -------------------------------------------------- | ------------------------------------------- | | `Title` | Text | — | The card's title. | | `Description` | Text | — | The card's description. | | `Image` | Image | — | The card's header image. | | `Content` | Text | This is content | Additional content text. | | `Button Name` | Text | Submit | The button label. | | `Button URL` | Text | [https://vectorshift.ai/](https://vectorshift.ai/) | The URL the button navigates to. | | `Button Action Type` | Text | Link | The action type when the button is clicked. | ### Best Practices * **Use dynamic content for personalized cards.** Connect upstream node outputs to the title, description, and image fields to generate cards tailored to each user's context. * **Write action-oriented button labels.** Labels like "View Report" or "Book Meeting" are clearer than generic "Submit" or "Click Here". * **Include an image for visual impact.** Cards with images are more engaging. Use relevant visuals like charts, product photos, or icons. * **Keep descriptions concise.** Card descriptions should be 1-2 sentences that convey the key information at a glance. * **Use multiple cards via Carousel.** If you need to present several options, consider using the Carousel variant instead of multiple Card nodes. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Provides real-time customer support directly embedded within a website interface. Handles investor inquiries related to portfolios, statements, and fund performance. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Talk — Carousel Source: https://docs.vectorshift.ai/nodes/talk-carousel/overview Send a gallery of multiple cards in a conversational workflow for users to browse. Add it in Python with `pipeline.add(name="...").talk(...)`. See the SDK reference. The Carousel node (a variant of the Talk node) sends a scrollable gallery of multiple cards to the user at a specific step in a chatbot conversation. Each card has a title, description, image, and a clickable button. Use it to present multiple options side by side — for example, showing several product recommendations, listing service plans, or displaying a set of document results for the user to browse and select. ## Core Functionality * Sends a horizontally scrollable gallery of cards to the user in the chat * Each card includes a title, description, image, and action button * Cards are managed as a dynamic list — add or remove cards as needed * Requires a Start node on the canvas to function ## Tool Inputs Each card in the carousel has the following fields: * `Title` — Text. The card's title. * `Description` — Text. The card's description. * `Image` — Image. The card's header image. * `Button Name` — Text. The label on the card's button. Default: "Submit". * `Button URL` — Text. The URL the button navigates to. * `Button Action Type` — The action when the button is clicked. Default: "Link". The carousel starts with one card. Add more cards to the gallery as needed. ## Tool Outputs The Carousel node has no outputs. It is a display-only node. *** ### Overview In workflows, the Carousel node presents multiple rich cards in a scrollable gallery within the chat interface. Users can browse through the cards and interact with individual buttons. This is ideal for presenting multiple options, search results, or recommendations where the user needs to compare and choose. ### Use Cases * Display multiple investment fund options with performance charts, descriptions, and "View Details" buttons for comparison * Present search results from a knowledge base as browsable cards with titles, snippets, and "Read More" links * Show available service plans (Basic, Pro, Enterprise) with features, pricing, and sign-up links * List recent financial reports with titles, dates, summaries, and download buttons * Display product catalog items in an e-commerce chatbot with images, prices, and purchase links ### How It Works #### Step 1: Add a Start Node The Carousel node requires a Start node on the canvas. #### Step 2: Add the Carousel Node In the workflow canvas, click the **Chat** tab, click **Talk**, then select **Carousel** from the variant list. Talk Carousel node being dragged onto the canvas from the Chat tab #### Step 3: Configure Cards Each card has fields for Title, Description, Image, and Button. Fill in the details for the first card, then add more cards as needed. #### Step 4: Connect in the Flow talk carousel connect with nodes Place the Carousel node at the point in the conversation where the gallery should appear. ### Settings | Setting | Type | Default | Description | | ------------------------------- | ----- | -------------------------------------------------- | -------------------------------- | | `Title` (per card) | Text | Card 1 | The card's title. | | `Description` (per card) | Text | This is a description | The card's description. | | `Image` (per card) | Image | — | The card's header image. | | `Button Name` (per card) | Text | Submit | The button label. | | `Button URL` (per card) | Text | [https://vectorshift.ai/](https://vectorshift.ai/) | The URL the button navigates to. | | `Button Action Type` (per card) | Text | Link | The action when clicked. | ### Best Practices * **Limit to 3-5 cards.** Too many cards make it hard for users to browse and compare. If you have more options, consider filtering or categorizing first. * **Use consistent formatting.** Keep titles, descriptions, and images at similar lengths and sizes across cards for a clean gallery appearance. * **Make cards self-contained.** Each card should convey enough information for the user to make a decision without needing to click through. * **Use action-oriented buttons.** Labels like "View Fund Details" or "Download Report" clearly communicate what happens next. * **Connect dynamic data.** Use upstream processing nodes to generate card content dynamically based on user queries or data lookups. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Provides real-time customer support directly embedded within a website interface. Assists banking customers with account inquiries, transactions, and product questions. Handles investor inquiries related to portfolios, statements, and fund performance. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Talk — Image Source: https://docs.vectorshift.ai/nodes/talk-image/overview Send an image to the user at a specific step in a conversational workflow. Add it in Python with `pipeline.add(name="...").talk(...)`. See the SDK reference. The Image node (a variant of the Talk node) sends an image to the user at a specific step in a chatbot conversation. Use it to display visual content inline in the chat — for example, showing a generated chart, presenting a product image, or displaying a captured screenshot from an upstream node. ## Core Functionality * Sends an image to the user at a defined point in the conversational flow * Accepts images via upload or from upstream node variables * Requires a Start node on the canvas to function * Does not produce outputs — it is a display-only node ## Tool Inputs * `Image` \* — Image. Required. The image to send. Can be uploaded directly or connected from an upstream node's image output. Supports Upload and Variable modes. talk image connect with nodes \* *Required field* ## Tool Outputs The Image node has no outputs. It is a display-only node that sends visual content to the user. *** ### Overview In workflows, the Image node sits in a conversational workflow and displays an image to the user when the flow reaches it. Use it to present charts, diagrams, screenshots, or any visual content generated or loaded by upstream nodes. ### Use Cases * Display a dynamically generated financial chart or graph from an upstream image generation node * Show a product image in a sales chatbot based on the user's selection * Present a screenshot captured by a Browser Extension node for review * Display a company logo or branding image at the start of a branded chatbot experience * Show a scanned document or receipt image uploaded by the user back to them for confirmation ### How It Works #### Step 1: Add a Start Node The Image node requires a Start node on the canvas. #### Step 2: Add the Image Node In the workflow canvas, click the **Chat** tab, click **Talk**, then select **Image** from the variant list. Talk Image node being dragged onto the canvas from the Chat tab #### Step 3: Provide the Image In the `Image` field, either upload an image directly or switch to Variable mode to connect an upstream node's image output. This field is required. #### Step 4: Connect in the Flow Place the Image node at the appropriate point in the conversation where the image should appear. ### Settings | Setting | Type | Default | Description | | ------- | ----- | ------- | ------------------------------------------------------------------- | | `Image` | Image | — | The image to display. Required. Supports Upload and Variable modes. | ### Best Practices * **Use Variable mode for dynamic images.** Connect upstream nodes (text-to-image, screenshots, file processing) to display context-specific visuals. * **Pair with Message nodes for context.** Add a Talk (Message) node before the Image node to explain what the image shows. * **Optimize image size.** Large images may slow the chat experience. Use reasonably sized images for the best user experience. * **Use for visual confirmation.** Display processed or extracted images back to the user so they can verify the content before proceeding. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Provides real-time customer support directly embedded within a website interface. Assists banking customers with account inquiries, transactions, and product questions. Answers employee questions about internal policies and flags potential compliance issues. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Talk — Message Source: https://docs.vectorshift.ai/nodes/talk-message/overview Send a text message to the user at a specific step in a conversational workflow. Add it in Python with `pipeline.add(name="...").talk(...)`. See the SDK reference. The Message node (a variant of the Talk node) sends a text message to the user at a specific step in a chatbot conversation. Use it to deliver information, ask questions, provide instructions, or display dynamic content — for example, greeting a user, presenting a financial summary, or asking a follow-up question before a Listen node captures their response. ## Core Functionality * Sends a text message to the user at a defined point in the conversational flow * Supports static text or dynamic content via variable references from upstream nodes * Optionally embeds an iframe for displaying external web content inline in the chat * Requires a Start node on the canvas to function ## Tool Inputs * `Message` \* — Text. Required. The text content to send to the user. Supports variable references via `{{}}` syntax. * `Send an iFrame` — Toggle. Default: `Off`. When enabled, the message content is rendered as an iframe. \* *Required field* ## Tool Outputs The Message node has no outputs. It is a display-only node that sends content to the user. *** ### Overview In workflows, the Message node sits in a conversational workflow and delivers text to the user when the flow reaches it. It is typically paired with Listen (Capture or Button) nodes to create back-and-forth dialogue. ### Use Cases * Greet the user and explain what the chatbot can help with at the start of a financial advisory conversation * Display a portfolio summary or account balance pulled from upstream data processing nodes * Ask a clarifying question before a Capture node collects the user's response * Present compliance disclaimers or terms of service that the user must acknowledge * Show a dynamically generated report or analysis result from an LLM node ### How It Works #### Step 1: Add a Start Node The Message node requires a Start node on the canvas. Add one from the **Start** tab if not already present. #### Step 2: Add the Message Node In the workflow canvas, click the **Chat** tab, click **Talk**, then select **Message** from the variant list. Talk Message node being dragged onto the canvas from the Chat tab #### Step 3: Enter the Message Content Type the message text in the `Message` field, or use `{{}}` syntax to reference outputs from upstream nodes. This field is required. #### Step 4: Enable iFrame (Optional) Toggle `Send an iFrame` to embed an external webpage or widget inline in the chat. #### Step 5: Connect in the Flow talk message connect with nodes Connect the Message node between other conversational nodes. A common pattern is: Start → Message (greeting) → Capture (user input) → processing → Message (result). ### Settings | Setting | Type | Default | Description | | ---------------- | ------ | ------- | ----------------------------------------- | | `Message` | Text | — | The text content to send. Required. | | `Send an iFrame` | Toggle | Off | Render the message as an embedded iframe. | ### Best Practices * **Use variables for dynamic content.** Reference upstream node outputs with `{{}}` to display personalized information. * **Pair with Listen nodes.** Place a Message node before every Capture or Button node so users know what is expected. * **Use iFrame for rich content.** Embed dashboards, forms, or visualizations from external tools directly in the chat. * **Keep messages concise.** Long messages reduce engagement. Break complex information across multiple Message nodes. * **Test the full conversational flow.** Deploy and walk through the entire conversation to ensure messages appear correctly. ### Related Templates Handles common customer inquiries and support tickets through conversational AI. Assists banking customers with account inquiries, transactions, and product questions. Answers employee questions about internal policies and flags potential compliance issues. Provides real-time customer support directly embedded within a website interface. ### Common Issues For help with common configuration issues, see the [Common Issues](/support) page. # Text to Image Source: https://docs.vectorshift.ai/nodes/text-to-image/overview Generate images from text descriptions using AI models in your workflows and agents. Add it in Python with `pipeline.add(name="...").ai_text_to_image(...)`. See the SDK reference. The Text to Image node generates images from text prompts using AI image generation models. Use it to create visuals, illustrations, or graphics — for example, generating custom chart illustrations for reports, creating presentation visuals from descriptions, or producing marketing imagery from text briefs. ## Core Functionality * Generate images from text descriptions using AI models * Support multiple providers including Google, OpenAI, Stability AI, Flux, and xAI * Configure output size and aspect ratio * Use personal API keys for dedicated access ## Tool Inputs * `Provider` \* — (Enum (Dropdown), default: `Google`) Select the image generation provider * `Model` \* — (Enum (Dropdown), default: `gemini-2.5-flash-image`) Select the text-to-image model. Options vary by provider * `Prompt` \* — (String) Text description of the image to generate. Be specific about desired content, style, and composition * `Size` — (Enum (Dropdown), default: `1024x1024`) Output image dimensions. Only visible for OpenAI provider * `Aspect Ratio` — (Enum (Dropdown), default: `1:1`) Output aspect ratio. Workflows only * `Use Personal API Key` — (Boolean, default: `No`) Toggle to use your own API key * `Api Key` — (String) Your API key. Only visible when `Use Personal API Key` is enabled \* indicates a required field ## Tool Outputs * `image` — (Image) The generated image ## Overview The Text to Image tool in agents allows the AI to generate images during conversations based on user descriptions. The agent interprets the user's request and creates appropriate prompts for the image generation model. ## Use Cases * **Presentation visual creation** — Users describe the visual they need and the agent generates it for their presentation. * **Report illustration** — Generate custom illustrations or diagrams to accompany financial reports. * **Marketing content** — Create visual content from text descriptions for marketing materials. * **Concept visualization** — Turn abstract financial concepts into visual representations. ## How It Works 1. **Add the tool to your agent.** In the agent builder, click **Add Tool** and select **Text to Image** from the available tools. Agent tool panel showing Generate Image (Text to Image) tool in the tool list 2. **Configure input fields.** Each field can either be filled automatically by the agent based on conversation context, or locked to a fixed value: * `Provider` — Select the image generation provider * `Model` — Choose the generation model * `Prompt` — The agent fills this based on the user's request * `Quality` — Set the output quality Generate Image tool configuration showing fields with sparkle icon to toggle between dynamic and static values 3. **Write the Tool Description.** Describe what the tool does so the agent knows when to use it. 4. **Set Auto Run behavior.** Choose: Auto Run, Require User Approval, or Let Agent Decide. Generate Image tool requiring user approval 5. **Test the tool.** Ask the agent to generate an image and verify the output. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ------------------------ | ------------------------------ | | `Provider` | Dropdown | Google | The image generation provider. | | `Model` | Dropdown | `gemini-2.5-flash-image` | The text-to-image model. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Write detailed prompts.** The more specific the description, the better the output. Include details about composition, style, colors, and content. * **Use Require User Approval.** Let users review generated images before they're used in outputs. * **Match the provider to your quality needs.** Different providers excel at different image styles. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. ## Overview The Text to Image node in workflows lets you generate images from text prompts and pass them to downstream nodes. This enables automated image generation workflows. ## Use Cases * **Automated report visuals** — Generate custom illustrations based on data analysis results from upstream nodes. * **Batch image generation** — Create multiple images from a list of prompts for marketing or presentation purposes. * **Dynamic content creation** — Generate visuals that adapt based on data flowing through the workflow. * **Template-based generation** — Create consistent imagery using standardized prompts with variable substitution. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Image** category and drag the **Text to Image** node onto the canvas. Text to Image node being dragged onto the canvas 2. **Select a provider and model.** Choose the `Provider` and `Model` from the dropdowns. 3. **Write your prompt.** In the `Prompt` field, describe the image to generate. Use `{{` to reference outputs from upstream nodes. 4. **Configure size or aspect ratio.** For OpenAI, select the `Size`. For other providers, choose the `Aspect Ratio`. 5. **Connect the output.** Wire the `image` output to downstream nodes. 6. **Run your workflow.** Execute the workflow to generate images. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ------------------------ | ------------------------------------------------------------------------ | | `Provider` | Dropdown | Google | The image generation provider (Google, OpenAI, Stability AI, Flux, xAI). | | `Model` | Dropdown | `gemini-2.5-flash-image` | The text-to-image model. | | `Size` | Dropdown | `1024x1024` | Output image size. Only visible for OpenAI provider. | | `Aspect Ratio` | Dropdown | `1:1` | Output aspect ratio. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Be specific in prompts.** Include details about style, composition, and content for better results. * **Use variables for dynamic generation.** Reference upstream node outputs in the prompt using `{{variable}}` syntax. * **Test across providers.** Different providers produce different visual styles — test to find the best fit. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Text to Speech Source: https://docs.vectorshift.ai/nodes/text-to-speech/overview Convert text to audio using AI voice models in your workflows and agents. Add it in Python with `pipeline.add(name="...").ai_text_to_speech(...)`. See the SDK reference. The Text to Speech node converts text input into natural-sounding audio using AI voice models. Use it to generate audio narrations, voice responses, or spoken content — for example, creating audio summaries of financial reports, generating voice responses for phone-based client interactions, or producing narrated presentations from text content. ## Core Functionality * Convert text to natural-sounding audio using AI voice models * Support multiple providers including OpenAI and Eleven Labs * Choose from multiple voice options per model * Use personal API keys for dedicated access ## Tool Inputs * `Provider` \* — (Enum (Dropdown), default: `OpenAI`) Select the voice provider (OpenAI, Eleven Labs) * `Model` \* — (Enum (Dropdown), default: `tts-1-hd`) Select the text-to-speech model * `Voice` \* — (Enum (Dropdown), default: `alloy`) Select the voice. Options vary by model * `Text` \* — (String) The text to convert to audio. Required — the node will show a validation error if empty * `Use Personal API Key` — (Boolean, default: `No`) Toggle to use your own API key * `Api Key` — (String) Your API key. Only visible when `Use Personal API Key` is enabled \* indicates a required field ## Tool Outputs * `audio` — (Audio) The generated audio file ## Overview The Text to Speech tool in agents allows the AI to convert text into audio during conversations. The agent can generate voice output from any text, enabling voice-based interactions and audio content creation. ## Use Cases * **Voice-enabled client interactions** — Generate spoken responses for phone or voice-based client communication systems. * **Audio report summaries** — Convert written financial summaries into audio format for on-the-go consumption. * **Accessibility** — Provide audio versions of text content for accessibility needs. * **Narrated presentations** — Generate voice narration for presentation slides based on text content. ## How It Works 1. **Add the tool to your agent.** In the agent builder, click **Add Tool** and select **Text to Speech** from the available tools. Agent tool panel showing Generate Speech (Text to Speech) tool in the tool list 2. **Configure input fields.** Each field can either be filled automatically by the agent based on conversation context, or locked to a fixed value: * `Provider` — Select the voice provider (e.g., OpenAI) * `Model` — Choose the TTS model * `Voice` — Select the voice * `Text` — The agent fills this from conversation context Generate Speech tool configuration showing fields with sparkle icon to toggle between dynamic and static values 3. **Write the Tool Description.** Describe what the tool does so the agent knows when to use it. 4. **Set Auto Run behavior.** Choose: Auto Run, Require User Approval, or Let Agent Decide. Generate Speech tool requiring user approval 5. **Test the tool.** Ask the agent to read something aloud and verify the audio output. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ---------- | ------------------------- | | `Provider` | Dropdown | OpenAI | The voice provider. | | `Model` | Dropdown | `tts-1-hd` | The text-to-speech model. | | `Voice` | Dropdown | `alloy` | The voice to use. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Choose the right voice.** Test different voice options to find one that matches your brand or use case. * **Keep text concise.** Shorter text inputs produce cleaner audio. Break long content into paragraphs for better results. * **Use Eleven Labs for premium quality.** If voice quality is critical (e.g., client-facing audio), consider Eleven Labs. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. ## Overview The Text to Speech node in workflows converts text from upstream nodes into audio output. This enables automated audio generation workflows. ## Use Cases * **Automated audio reports** — Convert financial report summaries into audio files for distribution. * **Voice response generation** — Generate audio responses for IVR or voice bot systems. * **Batch audio creation** — Convert multiple text items into audio files in a single workflow run. * **Multimodal content** — Combine text-to-speech with other nodes to create rich multimedia content. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Audio** category and drag the **Text to Speech** node onto the canvas. Text to Speech node being dragged onto the canvas 2. **Select a provider, model, and voice.** Choose the `Provider` (e.g., OpenAI), `Model` (e.g., `tts-1-hd`), and `Voice` (e.g., `alloy`) from the dropdowns. 3. **Connect the text input.** Wire a text output from an upstream node to the `Text` input, or enter text directly. 4. **Connect the audio output.** Wire the `audio` output to downstream nodes or an Output node. 5. **Run your workflow.** Execute the workflow to generate audio from text. ## Settings | Setting | Type | Default | Description | | ---------------------- | -------- | ---------- | ----------------------------------------------------- | | `Provider` | Dropdown | OpenAI | The voice provider (OpenAI, Eleven Labs). | | `Model` | Dropdown | `tts-1-hd` | The text-to-speech model. | | `Voice` | Dropdown | `alloy` | The voice to use. Options vary by model and provider. | | `Use Personal API Key` | Boolean | No | Use your own API key. | ## Best Practices * **Match voice to content.** Choose voices appropriate for your content type and audience. * **Use HD models for quality-critical audio.** The `tts-1-hd` model produces higher quality audio at a higher cost. * **Test voice options.** Different voices suit different content — test with representative text before deploying. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Trigger Source: https://docs.vectorshift.ai/nodes/trigger/overview Automatically run workflows when external events occur across your connected integrations. Add it in Python with `pipeline.add(name="...").trigger(...)`. See the SDK reference. The Trigger node starts a workflow automatically when a specific event happens in a connected service -- for example, a new email arriving in Gmail, a file being uploaded to Google Drive, or a row being added to Airtable. Instead of running workflows manually, you wire a Trigger at the start of your workflow so it fires on its own whenever the selected event occurs. ## Core Functionality * Start workflows automatically in response to external events across 17 supported integrations * Select a trigger type, then pick a specific event within that integration (e.g., Gmail > New Email) * Outputs structured event data (sender, subject, file name, etc.) that downstream nodes can consume * Enable or disable automation per trigger without removing it from the workflow * Schedule time-based runs using the Cron trigger with daily, weekly, monthly, or custom cron expressions ## Supported Trigger Types * **Airtable** -- Triggers when rows are added or updated in the selected table * **GitHub** -- Triggers when commits, pull requests, issues, or other events occur in the repository * **Gmail** -- Triggers when new email appears in the specified mailbox * **Google Docs** -- Triggers when Google Docs are created or updated * **Google Drive** -- Triggers when files are created or updated in the specified folder * **Google Sheets** -- Triggers when rows are added in the selected sheet * **Linear** -- Triggers when issues, comments, projects, cycles, labels, or reactions are created, updated, or removed * **Monday** -- Triggers when items are created, status changes, or column values update on a Monday board * **OneDrive** -- Triggers when files or folders are created or updated in the specified folder * **Outlook** -- Triggers when new email appears in the specified mailbox * **SharePoint** -- Triggers when files are created or updated in the specified folder * **Slack** -- Triggers when new message appears in the specified channel * **Teams** -- Triggers when messages are posted in Microsoft Teams channels or chats * **Typeform** -- Triggers when a new form submission is received * **Zendesk** -- Triggers when tickets are created or updated in your Zendesk account * **Cron** -- Triggers the workflow at specific intervals (daily, weekly, monthly, or custom cron expression) ## Tool Inputs * `Trigger Type` \* -- (Selection list) Choose the integration to monitor. Selecting a type reveals event-specific settings and an integration connection field. * `Event` \* -- (Enum (Dropdown)) The specific event within the selected trigger type (e.g., "New Email" for Gmail, "New Message" for Slack) * `Enable/Disable Automation` -- (Boolean, default: `true`) Turn the trigger on or off without removing it from the workflow * `Integration` \* -- (Integration) The connected account for the selected service (shown after selecting a trigger type) Additional inputs vary by trigger type and event. For example: * Gmail/Outlook: no additional inputs beyond the integration * Slack: `Team`, `Channel` * Google Drive/OneDrive/SharePoint: folder selection * Cron: `Timezone`, `Time of Day`, `Day of Week`, `Day of Month`, or custom cron expression * GitHub: `Owner`, `Repository`, event type selection \* indicates a required field ## Tool Outputs Outputs vary by trigger type and event. Common output patterns include: **Email triggers (Gmail, Outlook):** * `email_id` -- (String) Unique identifier of the email * `subject` -- (String) Subject of the email * `sender_email` -- (String) Email address of the sender * `recipient_email` -- (String) Email address of the recipient * `received_time` -- (String) When the email was received * `contents_of_email` -- (String) Contents of the email * `attachments` -- (File\[]) Attachments of the email **Messaging triggers (Slack, Teams):** * `message` -- (String) The message content * `user_id` -- (String) Unique identifier of the message sender * `channel_id` / `channel_name` -- (String) Channel information * `attachments` -- (File\[]) Files attached to the message * `permalink` -- (String) Direct link to the message **File/folder triggers (Google Drive, OneDrive, SharePoint):** * `file_id` -- (String) Unique identifier of the file * `file_name` -- (String) Name of the file **Cron trigger:** * `timestamp` -- (String) The timestamp when the trigger fired *** ## Overview The Trigger node sits at the start of a workflow and automatically runs the workflow when the configured event fires. Each trigger type monitors a specific integration for changes and passes structured event data to downstream nodes for processing. ## Use Cases * **Automated invoice processing** -- Trigger on new Gmail attachments to extract invoice data, validate amounts, and update an ERP or spreadsheet. * **Real-time trade alert routing** -- Trigger on Slack messages in a trading channel to parse alerts, enrich with market data, and route to the appropriate team. * **Scheduled portfolio reporting** -- Use a Cron trigger to generate daily or weekly portfolio performance summaries and distribute via email. * **Document compliance monitoring** -- Trigger on Google Drive or SharePoint file updates to scan new documents for regulatory compliance keywords. * **Support ticket triage** -- Trigger on new Zendesk tickets to classify urgency, extract key details, and assign to the right agent queue. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **Start** tab and drag the **Trigger** node onto the canvas. Trigger node being dragged onto the canvas from the Start tab 2. **Select a trigger type.** In the node panel, choose the integration you want to monitor (e.g., Gmail, Slack, Google Drive, Cron). Trigger node showing the trigger type selection with integration options 3. **Connect your integration.** Authenticate with the selected service using the integration picker. This grants VectorShift permission to listen for events. 4. **Choose a specific event.** Select the event that should fire the trigger (e.g., "New Email", "New Message", "New File"). Configure any additional fields the event requires (team, channel, folder, schedule, etc.). Trigger node showing event selection for the chosen integration 5. **Wire the outputs.** Connect the trigger's output fields (email content, file IDs, message text, etc.) to downstream nodes in your workflow. Trigger node connected to downstream nodes on the canvas 6. **Enable the trigger.** Ensure `Enable/Disable Automation` is set to `true`, then save the workflow. The trigger is now active and will run the workflow automatically when the event occurs. ## Settings | Setting | Type | Default | Description | | --------------------------- | ------------------ | -------- | ----------------------------------------------------------- | | `Trigger Type` | Selection list | -- | The integration to monitor for events. | | `Event` | Dropdown | -- | The specific event within the selected integration. | | `Enable/Disable Automation` | Boolean | `true` | Turn the trigger on or off. | | `Integration` | Integration picker | -- | The authenticated account for the selected service. | | `Timezone` | Dropdown | `UTC` | Timezone for Cron triggers. | | `Time of Day` | String | `00:00` | Time of day for daily/weekly/monthly Cron triggers (HH:MM). | | `Day of Week` | Dropdown | `Monday` | Day for weekly Cron triggers. | | `Day of Month` | Integer | `1` | Day for monthly Cron triggers. | | `Trigger on Weekends` | Boolean | `false` | Include weekends for daily Cron triggers. | ## Best Practices * **Use one trigger per workflow.** Each workflow should have a single Trigger node at its start to keep event handling predictable. * **Test with the automation disabled first.** Build and validate your downstream logic before enabling the trigger to avoid processing unexpected events. * **Filter events early.** Use a Condition node immediately after the Trigger to discard irrelevant events (e.g., emails from specific senders) before heavier processing. * **Monitor Cron expressions carefully.** Verify that custom cron expressions fire at the intended frequency to avoid excessive or missed runs. * **Keep integrations active.** If an integration token expires or is revoked, the trigger will stop firing silently. Periodically verify your connected accounts. ## Related Templates Classifies capital expenditure items against accounting standards and internal policies. Assesses risk levels in incoming applications using scoring models and policy rules. Automatically categorizes and tags incoming documents based on content and type. Reconciles financial statements by identifying mismatches and resolving discrepancies. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Workflow Node Source: https://docs.vectorshift.ai/nodes/workflow/overview Run an existing workflow as a sub-step within another workflow or as a tool inside an agent. Add it in Python with `pipeline.add(name="...").pipeline(...)`. See the SDK reference. The Workflow node lets you run an existing workflow as a sub-step within your current workflow, or as a tool inside an agent. When you select a workflow, its input and output nodes are automatically exposed as input and output handles on the node. Use it to modularize complex workflows — for example, calling a document processing sub-workflow from a larger orchestration workflow, or giving an agent the ability to trigger a pre-built analytics workflow on demand. ## Core Functionality * Run any deployed workflow as a sub-step within another workflow or as a tool in an agent * Automatically inherit the selected workflow's inputs and outputs as node handles * Create new workflows directly from the node configuration * Pass data into the sub-workflow's inputs and receive its outputs for downstream use ## Tool Inputs * `Workflow` \* — **Required** · Workflow selector · The deployed workflow to run. Once selected, the node dynamically generates input fields matching the sub-workflow's input nodes. * Dynamic inputs — One input per input node defined in the selected workflow. Names and types match the sub-workflow's input configuration. \* indicates a required field. ## Tool Outputs * Dynamic outputs — One output per output node defined in the selected workflow. Names and types match the sub-workflow's output configuration. The Workflow node uses the most recent **deployed** version of your sub-workflow. If you don't see the inputs and outputs you expect, make sure the sub-workflow has been deployed. ## Overview When added as a tool inside an agent, the Workflow node (labeled "Run Workflow") lets the agent trigger an existing workflow during a conversation. The agent passes inputs to the workflow, waits for execution, and incorporates the workflow's outputs into its response. This is ideal for giving agents access to pre-built, deterministic processing workflows — such as running a calculation, generating a report, or executing a multi-step data transformation. ## Use Cases * **On-demand report generation** — An agent triggers a report-building workflow when a user requests a financial summary, passing the date range and account as inputs. * **Data processing on request** — An agent runs a CSV processing workflow when a user uploads a file, returning the cleaned and formatted results. * **Calculation workflows** — An agent invokes a risk calculation workflow with portfolio parameters and returns the computed metrics to the user. * **Document generation** — An agent triggers a document assembly workflow to produce contracts, proposals, or compliance reports from user-provided data. * **Integration orchestration** — An agent runs a workflow that coordinates multiple API calls (e.g., fetching market data, running calculations, updating a CRM) as a single operation. ## How It Works 1. **Add the tool** — In the agent builder, open the tool panel and navigate to the **VectorShift** category. Select **Workflow** to add it as a tool. Agent tool panel showing the VectorShift category with Run Workflow tool highlighted 2. **Select the workflow** — Use the `Workflow` selector to choose the deployed workflow to run. Its inputs automatically appear as configurable fields. 3. **Configure input fields** — Each input from the selected workflow appears as a field. You can leave fields open for the agent to fill dynamically based on conversation context, or lock them to fixed values. Click the sparkle icon to switch a field between dynamic (agent-determined) and static (fixed) mode. Run Workflow tool configuration panel showing Workflow field with sparkle icon to toggle between dynamic and static values 4. **Write a Tool Description** — Describe when and why the agent should run this workflow. Example: *"Use this tool to generate a portfolio performance report. Provide the client name and reporting period."* 5. **Set Auto Run behavior** — Choose how the tool executes: * **Auto Run** — Runs the workflow immediately. * **Require User Approval** — Pauses for user confirmation before running. * **Let Agent Decide** — The agent determines whether approval is needed. Run Workflow tool requiring user approval, showing the workflow name and input fields in the approval dialog 6. **Test the tool** — In the chat interface, trigger a request that should invoke the workflow and verify the results are returned correctly. ## Settings * `Workflow` — Workflow selector · Default: none · The deployed workflow to run. * Dynamic input fields — Generated from the selected workflow's input nodes. * `Tool Description` — Text · Default: none · Describes the tool's purpose to the agent. * `Auto Run` — Dropdown · Default: Auto Run · Controls execution behavior. ## Best Practices * **Deploy before using** — The Workflow node runs the most recently deployed version of the sub-workflow. Always deploy your workflow after making changes to ensure the agent uses the latest version. * **Write clear tool descriptions** — Include what the workflow does, what inputs it needs, and what outputs to expect. The agent uses this to decide when to invoke it. * **Lock configuration inputs** — For inputs that should not vary (e.g., API keys, model settings, output formats), lock them to fixed values and only leave user-facing parameters open. * **Use approval for side-effect workflows** — If the workflow performs write operations (sending emails, updating databases, creating records), set Auto Run to "Require User Approval". * **Create dedicated workflows for agent use** — Design sub-workflows with clean, well-named inputs and outputs that make sense as agent tool parameters. ## Related Templates Automatically generates structured investment memos from deal data and research inputs. Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Reviews closing packages for completeness, accuracy, and compliance before deal finalization. Validates data and documents against predefined rules, schemas, or compliance standards. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. ## Overview In workflows, the Workflow node lets you embed another workflow as a sub-step within your current workflow. This enables modular workflow design — you can break complex workflows into reusable components and compose them together. The node inherits the sub-workflow's inputs and outputs, letting you wire data in and out seamlessly. ## Use Cases * **Modular workflow design** — Break a large financial processing workflow into reusable sub-workflows (data extraction, transformation, validation, output) and compose them using Workflow nodes. * **Shared processing steps** — Use a common data cleaning workflow across multiple parent workflows without duplicating the logic. * **Conditional workflow execution** — Route data to different sub-workflows based on conditions (e.g., different processing workflows for equities vs. fixed income). * **Team collaboration** — Different team members build and maintain separate sub-workflows, which are composed into a master workflow using Workflow nodes. ## How It Works 1. **Add the node** — On the workflow canvas, open the node panel and navigate to the **VectorShift** category. Drag **Workflow** onto the canvas. Node palette showing the VectorShift category with Workflow node being dragged onto the canvas 2. **Select or create a workflow** — Use the workflow selector to choose an existing deployed workflow, or click **Create Workflow** to build a new one. The creation dialog offers two options: start from scratch or use AI to generate a workflow from a description. 3. **Connect inputs** — Wire upstream node outputs to the Workflow node's input handles. Each handle corresponds to an input node in the selected sub-workflow. 4. **Connect outputs** — Wire the Workflow node's output handles to downstream nodes. Each handle corresponds to an output node in the sub-workflow. Workflow node connected to upstream and downstream nodes on the canvas 5. **Run the workflow** — Execute the workflow. The Workflow node runs the sub-workflow with the provided inputs and passes its outputs downstream. ## Settings * `Workflow` — Workflow selector · **Required** · The deployed workflow to run as a sub-step. * Dynamic input fields — Generated from the selected workflow's input nodes. * Dynamic output fields — Generated from the selected workflow's output nodes. ## Best Practices * **Deploy sub-workflows first** — The Workflow node uses the most recently deployed version. If inputs or outputs appear missing, redeploy the sub-workflow. * **Keep sub-workflows focused** — Each sub-workflow should handle a single logical step. This makes them reusable and easier to debug. * **Match input/output types** — Ensure the types of upstream outputs match the expected input types of the sub-workflow to avoid type-mismatch errors. * **Use for abstraction, not duplication** — If you find yourself copying node configurations across workflows, extract the shared logic into a sub-workflow and use Workflow nodes to reference it. * **Version control through deployment** — The Workflow node always runs the deployed version. You can safely edit a sub-workflow without affecting parent workflows until you redeploy. ## Related Templates Automatically generates structured investment memos from deal data and research inputs. Compares two or more spreadsheets to identify discrepancies, changes, and anomalies. Reviews closing packages for completeness, accuracy, and compliance before deal finalization. Validates data and documents against predefined rules, schemas, or compliance standards. ## Common Issues For troubleshooting and common issues, see the [Common Issues](/docs/common-issues) page. # xAI LLM Source: https://docs.vectorshift.ai/nodes/xai/overview Generate text responses using xAI's Grok models in your workflows. Add it in Python with `pipeline.add(name="...").llm(...)`. See the SDK reference. The xAI LLM node connects your workflows to xAI's Grok family of language models. Use it to generate text responses, analyze documents, or build AI-powered workflows — for example, generating market commentary, classifying financial documents, or building chatbots that leverage Grok's reasoning and search capabilities. ## Core Functionality * Generate text completions and conversational responses using Grok models * Access specialized model variants including search-enabled and fast-reasoning models * Process system instructions and dynamic prompts with variable interpolation * Stream responses in real time for long-running generations * Return structured JSON output with optional schema enforcement * Track token usage and credit consumption per run * Apply content moderation, PII detection, and safety guardrails * Retry failed executions automatically with configurable intervals ## Tool Inputs * `System Instructions` — (String) Instructions that guide the model's behavior, tone, and how it should use data provided in the prompt * `Prompt` — (String) The data sent to the model. Type `{{` to open the variable builder and reference outputs from other nodes * `Model` \* — (Enum (Dropdown), default: `grok-4-0709`) Select from available Grok models * `Use Personal Api Key` — (Boolean, default: `Yes`) Toggle to use your own xAI API key * `Api Key` — (String) Your xAI API key. Visible when `Use Personal Api Key` is enabled \* indicates a required field ## Tool Outputs * `response` — (String (or Stream\ when streaming)) The generated text response from the model * `prompt_response` — (String) The combined prompt and response content * `tokens_used` — (Integer) Total number of tokens consumed (input + output) * `input_tokens` — (Integer) Number of input tokens sent to the model * `output_tokens` — (Integer) Number of output tokens generated by the model * `credits_used` — (Decimal) VectorShift AI credits consumed for this run ## Overview The xAI LLM node in workflows lets you place a Grok model on the canvas and configure it through the settings panel. xAI offers models with different speed-reasoning tradeoffs and built-in search capabilities. ## Use Cases * **Market commentary generation** — Generate real-time market commentary using Grok's search-enabled models that can access current data. * **Financial document analysis** — Analyze earnings reports, SEC filings, or research notes using Grok's reasoning capabilities. * **Fast classification tasks** — Use fast-reasoning variants for high-throughput classification of financial transactions or documents. * **Research synthesis** — Combine search capabilities with reasoning to synthesize information across multiple sources for investment research. * **Client communication drafting** — Draft personalized financial communications using Grok's conversational capabilities. ## How It Works 1. **Add the node to your workflow.** From the toolbar, open the **AI** category and drag the **xAI** node onto the canvas. xAI node being dragged onto the canvas 2. **Write your System Instructions.** Enter instructions in the `System Instructions` field. 3. **Configure the Prompt.** In the `Prompt` field, type `{{` to reference upstream node outputs. 4. **Select a model.** Use the `Model` dropdown to choose a Grok model. Available options include `grok-4-0709`, `grok-4`, `grok-4-search`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, `grok-4-0625`, `grok-3-fast`, `grok-3-fast-beta`, `grok-3-mini-beta`, and others. xAI node showing the Model dropdown 5. **Provide an API key.** The `Use Personal Api Key` toggle defaults to **Yes**. Enter your xAI API key in the `Api Key` field. 6. **Open settings.** Click the **gear icon** (⚙) to configure settings. xAI node settings panel 7. **Connect outputs.** Wire the `response` output to downstream nodes. Click the **Outputs** button to see all available outputs. xAI node connected to upstream and downstream nodes 8. **Run your workflow.** Execute the workflow to process inputs through the Grok model. ## Settings All settings below are accessed via the **gear icon** (⚙) on the node. | Setting | Type | Default | Description | | ------------------------------ | -------- | ------- | ------------------------------------------------------------------------------ | | `Provider` | Dropdown | xAI | The LLM provider. | | `Max Tokens` | Integer | 131072 | Maximum number of input + output tokens per run. | | `Reasoning Effort` | Dropdown | Default | Controls the depth of reasoning. | | `Verbosity` | Dropdown | Default | Controls the verbosity of responses. | | `Temperature` | Float | 0.5 | Controls response creativity. Range: 0–1. | | `Top P` | Float | 0.5 | Controls token sampling diversity. Range: 0–1. | | `Stream Response` | Boolean | Off | Stream responses token-by-token. | | `JSON Output` | Boolean | Off | Return output as structured JSON. | | `Show Sources` | Boolean | Off | Display source documents used for the response. | | `Toxic Input Filtration` | Boolean | Off | Filter toxic input content. | | `Safe Context Token Window` | Boolean | On | Automatically reduce context to fit within the model's maximum context window. | | `Retry On Failure` | Boolean | Off | Enable automatic retries when execution fails. | | `Max Retries` | Integer | — | Maximum retry attempts. | | `Max Interval b/w re-try` | Integer | — | Interval in milliseconds between retries. | | `Show Success/Failure Outputs` | Boolean | — | Display additional success and failure output ports. | ## Best Practices * **Choose the right Grok variant.** Use `grok-4-search` for queries needing current web data, `grok-4-fast-reasoning` for speed-optimized reasoning, and `grok-4` for general-purpose tasks. * **Use JSON mode for structured extraction.** Enable `JSON Output` for consistent output when extracting financial data from documents. * **Monitor token usage.** Connect `tokens_used` and `credits_used` for cost tracking across high-volume workloads. * **Enable Safe Context Token Window.** This is on by default for xAI — keep it enabled to prevent token-limit errors. * **Apply PII detection for sensitive data.** Enable PII toggles when processing client financial information. ## Common Issues For troubleshooting common issues with this node, see the [Common Issues](/support) documentation. # Agent Instructions Source: https://docs.vectorshift.ai/platform/agents/agent-instructions Define your Agent's role, behavior, tone, and task scope This is the first thing you see when you open the Agent tab, and it's the most important part of your setup. The instructions tell your Agent how it should behave, what kind of tasks it should handle, what tone to use, and what to do (or not do) in different situations. You'll see a text area with a helper note above it: *"Describe how your agent should work. It's recommended to provide examples of tasks it might receive and what to do. You can reference tools/inputs as variables by typing '`{{`' to open the variable builder."* Agent instructions text area Write your instructions in plain language. The default template looks like this: > "You are an intelligent assistant designed to provide helpful, accurate, and relevant information. Your responsibilities: > > * Answer questions clearly and concisely > * Assist with tasks within your capabilities > * Acknowledge when you don't know something > * Maintain a professional and friendly tone > * Follow user instructions carefully > > When responding, focus on providing value while being respectful of the user's time and needs." You can replace this entirely with your own instructions. You can reference tools and inputs in your instructions by typing `{{` in the text field. This opens a variable builder that lets you insert references to specific tools or input variables (e.g., `input_0`) by name. This is useful when you want to explicitly tell the Agent when or how to use a particular tool, or when you need to inject input values directly into the instructions. Input variables are only available when the agent variant is set to **Functional**. If you're using a different variant, only tool references will appear in the variable builder. There is also an expand button on the text area that opens the instructions in a full-screen editor, which is helpful when working with longer instruction sets. If you reference a variable that doesn't exist or has been removed, the instructions field will show a red border to indicate the invalid reference. The more specific your instructions are, the better your Agent will perform. Include examples of tasks the Agent might receive, describe how it should handle edge cases, and be explicit about what it should not do. **Example: Compliance Assistant instructions** *You are a compliance assistant for Meridian Financial. You help team members with questions about SEC regulations, internal audit policies, and trade reporting requirements. Your responsibilities:* * *Answer questions using the Query Knowledge Base tool to search our compliance documentation* * *Always cite the specific policy or regulation section in your response* * *If a question falls outside SEC, FINRA, or internal policy scope, say so clearly* * *Never provide legal advice — direct users to the legal team for interpretation questions* Vague instructions like "help with compliance stuff" lead to unpredictable behavior. Specific instructions like the above give the Agent clear boundaries and consistent behavior. # Agent Tools Source: https://docs.vectorshift.ai/platform/agents/agent-tools Add, configure, and manage the tools your Agent can use Add any tool in Python via `AgentTools.(tool_name="...")` or `agent.add_tool.(...)`. See the SDK tool reference. Tools give your Agent the ability to take actions — not just talk. With tools, your Agent can search the web, generate images, read documents, run code, query databases, and connect to third-party apps to get real work done. Agent tools section Click **+ Add Tool** to browse and add tools, or use the category filter tabs (**All**, **VectorShift**, **LLM**, **Web Search**, **File Ops**, **Data**) to quickly find what you need. Every new Conversational agent comes with 13 tools pre-added so you can start building immediately: 1. Run Agent 2. Modify Image 3. Analyze Image 4. Transcribe Speech 5. Generate Image 6. Generate Speech 7. Code Interpreter 8. Research Web 9. Read Document 10. Generate Chart 11. Query Knowledge Base 12. Run Workflow 13. URL Scraper Each tool row gives you quick access to: * **Edit** — customize the tool's description, inputs, and outputs to fit your use case. * **Auto Run / Require Approval** — control whether the tool runs automatically or waits for user confirmation (Conversational agents only). * **"…" menu** — remove the tool from your Agent. If a tool has required inputs that haven't been filled in, you'll see a red **Fill required inputs** warning on the tool row. During testing, tool cards show live status: a spinner when running, green on success, and red on error. ## Adding tools Click **+ Add Tool** to open the tool browser. On the left side, you'll see Tool Categories for navigation. On the right, you'll see all available tools grouped by category, each with a short description and an **+ Add** button. Tools that are already added to your Agent show an **Added** badge. Tool browser with categories and available tools You can also use the **Search** bar at the top to find a specific tool by name. Searching for tools in the tool browser ## Tool categories Tools are organized into the following categories: * **VectorShift:** Run code, generate charts, query your knowledge bases, delegate to sub-agents, trigger workflows, and more — all using platform-native tools like Code Interpreter, Generate Chart, Query Knowledge Base, Run Agent, and Run Workflow. * **Web Search:** Pull real-time information from the internet using Google Search, Exa AI Search, Perplexity Search, or Parallel AI Search. * **LLM:** Generate images from text, analyze images, convert speech to text, and create voiceovers — powered by tools like Generate Image, Analyze Image, Transcribe Speech, and Generate Speech. * **File Ops:** Read, write, and process files like Excel spreadsheets and documents so your Agent can work with uploaded data directly. * **Data:** Access external data sources — query APIs, scrape URLs, pull Wikipedia articles, fetch YouTube transcripts, and search ArXiv or Crunchbase. * **Integration tools:** Connect to 50+ third-party services like Airtable, Slack, Asana, Salesforce, Google Sheets, HubSpot, and more — so your Agent can take actions across your existing tools. Each integration offers its own set of tools specific to that service. For example, Airtable provides tools for Add New Record, Column List Writer, Delete Record, Get Row, Get Table, Get Table Schema, List Bases, Search Records, and Update Records. You can add tools individually with **+ Add**, or use the **+ Add All** button to add every tool from an integration at once. ## Configuring a tool Click **Edit** on any tool to customize how it behaves. The Agent uses each tool's description along with its instructions to decide when to use it — so tailoring these helps your Agent make smarter decisions. Click Edit to open the tool configuration panel Every tool configuration panel has these sections: ### Tool description The tool description helps your Agent decide when to use the tool. A more specific description leads to better decisions about when the tool gets called. For example, instead of the default *"Semantically query a knowledge base…"*, you could write *"Search the customer financials database for revenue data, account details, and quarterly reports."* — this helps the Agent match the right tool to the right question. Think of the tool description as a label for the Agent. The Agent reads every tool description before deciding which tool to call, so be specific about what the tool does and what kind of questions it answers. A well-written description reduces tool misuse and speeds up responses. ### Static vs. dynamic inputs Each tool input has a sparkle icon (✦) toggle button in the top-right corner that switches between **static** and **dynamic** mode. Click it to toggle: * **Dynamic** (sparkle icon active/highlighted): The input shows a green pill labeled "Defined automatically by the Agent". This means the Agent will autonomously decide what value to use based on the conversation context. For example, when the sparkle icon is active on a Knowledge Base input, the Agent will analyze the user's question and automatically pick the most relevant Knowledge Base from your available options. * **Static** (sparkle icon inactive): The input switches to a text field, dropdown, or other input control where you set a fixed value. The Agent will always use this exact value every time it calls the tool. Clicking the sparkle toggle to switch a tool input from dynamic to static mode Use static inputs when you want to lock a value — for example, always querying a specific Knowledge Base. Use dynamic inputs when the Agent should decide the value based on context — for example, letting it compose its own search query from the user's message. When you set an input to static and it is required, you must fill in a value before saving. If you don't, the tool row will show a red **Fill required inputs** warning. ### Input descriptions Below each dynamic input, you'll see a **+ Add description for the agent** link. Click it to provide guidance that helps the Agent understand what kind of value to generate for that input. This is especially useful when the input name alone isn't descriptive enough. ### Advanced settings Most tools have an **Advanced Settings** section at the bottom of the configuration panel. Click it to expand additional options specific to that tool. These settings vary by tool — for example, the Query Knowledge Base tool lets you configure retrieval options like reranking, query expansion, and chunk limits, while the Code Interpreter tool has options for execution environment settings. For most use cases, the default advanced settings work well. Only adjust these if you notice the Agent returning unexpected results — for instance, increasing **Max Chunks Per Query** can help when answers span multiple document sections. ### Tool outputs The **Tool Outputs** section at the bottom of the panel shows what the tool returns to the Agent after it runs. Each output has a name and type (e.g., text, file, image). The Agent uses these outputs to compose its response to the user. You can review the output configuration to understand what data the tool provides — for example, the Query Knowledge Base tool returns the matched text chunks, while the Generate Chart tool returns an image. ## Execution modes Each tool can run in one of two execution modes. You can toggle between them directly on the tool row in the tools list. ### Auto Run The Agent calls the tool automatically whenever it's needed — no user intervention required. This is the default and works best for most use cases where you want a seamless, hands-off experience. For example, if a user asks *"What's the latest news on NVIDIA?"* and you have the Research Web tool set to Auto Run, the Agent will immediately search the web and return results without any pause. ### Require User Approval The Agent pauses and shows the user exactly what it's about to do before running the tool. An approval form appears in the chat showing all the inputs the Agent has pre-filled. Users can review, edit any field, and then approve or cancel. The approval form includes: * All tool inputs pre-filled by the Agent, editable before approval * An **Advanced** section for fine-tuning settings * **Cancel** and **Approve** buttons Approval flow showing Query Knowledge Base request waiting for user approval with editable search query and knowledge base fields Users can modify any field — change the search query, pick a different Knowledge Base, or adjust advanced settings — before clicking **Approve**. Advanced settings panel showing retrieval options like Enable Filter, Rerank Documents, Max Chunks Per Query, and more Use Require User Approval for sensitive actions — like querying confidential documents, updating CRM records, or making external API calls — so users can review and refine inputs before execution. For example, a compliance team might require approval on all Knowledge Base queries to ensure the right documents are being searched. # AI Model Source: https://docs.vectorshift.ai/platform/agents/ai-model Choose the language model and configure advanced settings for your Agent Directly below the instructions, you'll find the AI Model section. This is where you choose the large language model that powers your Agent's reasoning. * **Provider:** A dropdown that lets you select the AI provider. The available options are OpenAI, Anthropic, Google, and Groq. * **Model:** A dropdown that lets you pick a specific model from your chosen provider (e.g., gpt-5.1 for OpenAI). AI Model provider and model selection ## Advanced settings Click the **Advanced Settings** button to open a side panel with additional configuration. These are organized into two groups. Advanced settings panel ### Basic config The following fields appear in order from top to bottom: * **Use Personal API Key:** Toggle this on if you want to use your own API key instead of VectorShift's default key. This is useful if you have a separate billing arrangement or need access to specific model versions. * **Show Sources:** When enabled, the Agent will display citation sources in its responses. This is helpful when your Agent pulls answers from a Knowledge Base and you want users to see where the information came from. Enabled by default. * **Base URL (optional):** If you're using a custom or self-hosted model endpoint, enter the base URL here. * **Endpoint (optional):** Specify a custom API endpoint if your setup requires one. * **Deployment ID (optional):** For Azure OpenAI or similar deployments, enter the deployment ID here. * **Fine-Tuned Model ID (optional):** If you've fine-tuned a model, enter its ID here so the Agent uses your custom model. ### Privacy and security Below the basic config, you'll find privacy and security controls. **Toxic Input Filtration:** Toggle this on to automatically filter out potentially harmful or inappropriate inputs before they reach the AI model. **PII Detections:** A set of individual toggles that let you detect and flag personally identifiable information in user inputs. These toggles are only interactive when Toxic Input Filtration is turned on. Each type can be enabled or disabled independently: * Names * Email Addresses * Phone Numbers * Social Security Numbers * Credit Card Numbers # @ Tag References Source: https://docs.vectorshift.ai/platform/agents/at-tag-references Directly reference tools, knowledge bases, and other resources in the chat The @ tag menu is one of the most powerful ways to direct your Agent's behavior during a conversation. It lets you explicitly point the Agent to specific resources instead of relying on it to choose automatically. In the chat input, you can type **@** to open a searchable dropdown menu that lets you reference specific resources directly in your message. This works both in the builder preview and in the deployed chatbot. @ tag dropdown menu in chat input The available resource types, in the order they appear in the dropdown, are: * **Agent Tools:** Reference a specific tool to prompt the Agent to use it. * **Agent Memory:** Reference the Agent's stored memory from the current session. * **Agents:** Tag another Agent to bring it into the conversation. * **Knowledge Bases:** Point the Agent to a specific Knowledge Base for its response. * **Tables:** Reference a VectorShift Table for data lookups. * **Workflows:** Trigger a specific Workflow from within the chat. You can also type to search within the dropdown to quickly find the resource you need. For example, in a multi-desk finance setup you could type "`@Fixed Income Agent` What is the current yield curve?" to send that question directly to the Fixed Income sub-agent, or "`@Q4 Holdings Report` what is our NVIDIA allocation?" to force the Agent to query that specific document rather than its general knowledge base. **When to use @ tags:** * **Reference a specific Knowledge Base:** *"`@Customer FAQ` What is the return policy for international orders?"* — forces the Agent to search that specific KB instead of choosing on its own. * **Route to a sub-agent:** *"`@Compliance Agent` Does this trade require pre-clearance?"* — sends the question directly to the Compliance sub-agent. * **Force a specific tool:** *"`@Code Interpreter` Plot a bar chart of Q3 revenue by region"* — ensures the Agent uses the Code Interpreter rather than another tool. * **Reference a Table:** *"`@Sales Pipeline` Show me all deals closing this month"* — points the Agent to a specific VectorShift Table for data lookups. You can combine @ tags with natural language to be precise about what you want the Agent to do. # Build an Agent Source: https://docs.vectorshift.ai/platform/agents/build-an-agent Create a new Agent from scratch, orient yourself in the builder, and build your first working Agent step by step This page walks you through creating a new Agent from scratch, orienting yourself in the builder, and building your first working Agent step by step. ## Create a new Conversational agent ### 1. Open the Projects page Go to the **Projects** page from the left sidebar and click the **+ New Project** button in the top-right corner. Create New Project dialog ### 2. Configure the project In the Create New Project dialog, fill in the following: * **Name:** Give your project a descriptive name like "Portfolio Research Assistant" or "Compliance Assistant." VectorShift will auto-generate one (e.g., "New Project 1"), but something meaningful makes it easier to find later. * **Variant:** Choose **Agent**. You'll see the description: "Create conversational agents that deploy directly to VectorShift chat interfaces." Select Agent variant ### 3. Click Create Click **Create** to open the Agent Builder. After a moment, the Agent Builder opens with your new agent pre-loaded with default instructions, an AI model, and 13 built-in tools that let you do the following out of the box: * Search the web for real-time information * Generate, modify, and analyze images * Transcribe speech and generate audio * Execute Python code to analyze data and create files * Read and extract text from uploaded documents * Generate charts and visualizations from data * Query your knowledge base for grounded answers * Run other agents as sub-agents for complex tasks * Trigger Workflows for multi-step automations * Scrape content from web URLs If you need specialized capabilities beyond these, you can add more tools from the tool browser, including 30+ third-party integrations. The builder is split into two areas. On the left is the configuration panel where you'll set up everything about your Agent. On the right is a live chat preview that lets you test your Agent as you build it. Agent builder layout with configuration panel and chat preview At the top of the screen, you'll see three tabs: **Agent**, **Interface**, and **Manager**. We'll walk through each of these in the sections that follow. Agent, Interface, and Manager tabs The builder also has a few controls in the top-right corner: * **Versions** lets you manage saved versions of your Agent. * **Share** lets you collaborate with teammates. * **Save** saves your work. You'll also notice a **Draft saved** indicator that confirms your changes are being auto-saved as you go. ## Example: creating a portfolio research assistant Let's walk through creating a Portfolio Research Assistant Agent from scratch. ### Step 1: Create the Agent Go to Projects and click **+ New Project**. Name it "Portfolio Research Assistant" and select **Agent** as the variant. Click **Create**. ### Step 2: Add Agent Instructions In the Agent Instructions field, replace the default text with: *You are a financial research assistant for Apex Capital. You help analysts with market research, company analysis, and portfolio questions. When an analyst asks about a company, use the Research Web tool to find the latest news and the Query Knowledge Base tool to look up internal research notes. Always cite your sources and flag when information may be outdated.* ### Step 3: Configure the AI Model Under AI Model, select **OpenAI** as the provider and **gpt-5.1** as the model. ### Step 4: Configure Tools In the Tools section, keep the default tools. Then click **+ Add Tool**, find **Google Search** under Web Search, and click **+ Add**. ### Step 5: Connect your Knowledge Base Find the **Query Knowledge Base** tool in the tools list — it is added by default. Click **Edit** to open its configuration panel. Click the sparkle icon (✦) next to the **Knowledge Base** input to switch it from dynamic to static. When the sparkle icon is active (highlighted), it means the Agent will automatically decide which Knowledge Base to pick based on the conversation context. Switching it to static locks the tool to always search your selected documents. A dropdown appears — select your Knowledge Base or click **+ New Knowledge Base** to create one. Switching the Knowledge Base input from dynamic to static and selecting a Knowledge Base ### Step 6: Configure the Interface Switch to the **Interface** tab and set: * Display Title: `Apex Research` * Welcome Description: `Hi there! Ask me anything about our portfolio or market research.` Interface tab settings ### Step 7: Save Click **Save** in the top-right corner. ### Step 8: Test it In the chat preview on the right, type: *"What's our current position in NVIDIA and what's the latest news on their earnings?"* — the agent should query your Apex Capital KB for the holdings data and use Google Search for the latest news, without any approval prompts. Testing the Agent in the chat preview Your Agent is now ready to test in the chat preview on the right side of the builder, and you can open the deployed chatbot URL to share it with users. ### Other common use cases The portfolio research example above is just one way to use Agents. Here are a few other finance-focused setups you can create following the same process: * **Financial document analyst:** Upload quarterly reports and balance sheets. Keep the Code Interpreter and Generate Chart tools. Users can ask "Show me a breakdown of operating expenses by quarter" and get a chart back instantly. * **Compliance assistant:** Upload regulatory guidelines and internal policies to the Knowledge Base. Team members can ask "What are our reporting requirements for trades over \$1M?" and get answers sourced from actual compliance documents. * **Risk assessment assistant:** Add the Research Web and Query Knowledge Base tools. Instruct the Agent to cross-reference real-time market data with internal risk frameworks to help analysts draft risk assessments. * **Client onboarding assistant:** Connect your CRM through integration tools. Upload your onboarding playbook. Relationship managers can ask "What documents do we still need from Client X?" and the Agent pulls the answer from both the CRM and the playbook. * **Multi-desk router:** Use the Run Agent tool to connect specialized sub-agents for equities, fixed income, compliance, and operations. The main Agent reads the user's question and delegates to the right desk automatically. See the Run Agent tool section for setup details. # Test and Deploy Source: https://docs.vectorshift.ai/platform/agents/chat-preview Test your Agent in the builder preview and deploy it as a chatbot ## Builder chat preview Test your Agent in real time without leaving the builder. The live preview on the right side of the Agent Builder behaves exactly like the deployed chatbot — so you can validate instructions, tools, and knowledge base responses as you build. Builder chat preview panel The preview supports full conversations, file uploads, voice input, and [@ tag references](/platform/agents/at-tag-references) for targeting specific tools and knowledge bases. ## Deployed chatbot When your Agent is ready, click **Open Chatbot** in the Interface tab to launch the deployed version. Your chatbot gets a shareable URL that you can send directly to users. Deployed chatbot interface The deployed chatbot reflects everything you configured — display title, avatar, accent color, font, welcome message, and branding. You can also deploy to [Slack and WhatsApp](/platform/agents/interface-tab) to meet users where they already work. # Customize Your Agent Source: https://docs.vectorshift.ai/platform/agents/interface-tab Configure the chatbot interface, appearance, security, and deployment integrations For detailed documentation on chatbot configuration and embedding options, see [Chatbot Documentation](/platform/interfaces/chatbots/getting-started). The Interface tab lets you control how your Agent looks and feels to end users — from branding and welcome messages to security and deployment channels. ## Configuration **Use Latest Version** (enabled by default) ensures your deployed chatbot always runs the most recently saved version of your Agent. The builder preview always reflects your latest changes — including unsaved edits — so you can test instantly. However, the deployed chatbot your end users see only updates when you click **Save**. In Projects, saving is all you need — no separate deploy step required. ## General Brand your chatbot and shape the first impression users get when they open it. * **Display Title** and **Display Image** — set the name and logo users see at the top of the chatbot. * **Welcome display description** — write a greeting that appears when the chatbot loads (e.g., "Hi, how can I assist you today?"). * **Placeholder for message input field** — guide users on what to type (e.g., "Ask anything or tag with '@'"). Display title, welcome description, and input placeholder settings * **Enable initial prompts** — show clickable prompt suggestions so users can get started with one click. Initial prompt suggestions configuration * **Generate related questions** — automatically suggest follow-up questions after each response to keep the conversation going. You can control how many suggestions appear and add guidelines for what types of questions to suggest. Generate related questions settings * **Processing message and icon** — customize what users see while the Agent is thinking (e.g., "Understanding your request…"). * **User and bot message names** — label who's speaking in the chat (defaults: "User" and "Assistant"). * **Powered by VectorShift** — toggle the branding badge on or off. ## Style Match the chatbot's look to your brand. * **Avatar Image** — give your Agent a recognizable face next to its messages. * **Accent color** — apply your brand color across buttons, highlights, and UI elements. * **Messages font** — choose a typeface that fits your brand's tone (e.g., Inter). Style settings - avatar image, accent color, and font ## Security Control who can access your deployed chatbot and what unauthorized users see. ### Protect with SSO Auth Require Single Sign-On authentication so only authorized users in your organization can access the chatbot. When enabled, you can: * **Enable Auto Redirect** — automatically send users to your SSO login instead of showing the access denied page. * **Share with** — invite specific users by email and assign them a role (e.g., Editor) to control who can access the chatbot. #### Customize Access Denied Page Tailor the message unauthorized users see when they don't have access: * **Permission Text** — the main message displayed (e.g., "You do not have permission to access this chatbot."). * **Contact Text** — instructions for requesting access (e.g., "Please contact the owner to request access"). * **Icon Color** — match the access denied page icon to your brand. SSO authentication and access denied page settings ### Protect with Password Gate access behind a password so only users with the credentials can interact with the chatbot. * **Password** — set the password users must enter to access the chatbot. #### Customize Login Page Brand the authentication screen users see before entering the chatbot: * **Change Header** — set the page title (e.g., "Authenticate to Chatbot"). * **Change Password Text** — customize the label for the password field. * **Change Button Text** — customize the submit button text. * **Icon Color** — match the login page icon to your brand. Password protection and login page customization ## Slack Deploy your Agent directly into Slack so your team can interact with it where they already work. For detailed step-by-step setup instructions, see [Deploy to Slack](/platform/interfaces/chatbots/export-slack). ## Twilio Reach users on WhatsApp by connecting your Agent to Twilio. For detailed step-by-step setup instructions, see [Deploy to WhatsApp](/platform/interfaces/chatbots/export-whatsapp). # Agents Source: https://docs.vectorshift.ai/platform/agents/introduction Build intelligent, conversational AI assistants that reason, remember context, and take actions autonomously Agents are intelligent, conversational AI assistants you can build, customize, and deploy without writing code. Unlike Workflows, which follow a fixed sequence of steps, Agents can reason, remember context within a conversation, and decide which tools to use on their own to get things done. At their core, Agents work like a knowledgeable team member who can hold a conversation, look things up, take actions on your behalf, and remember what you talked about. You give them instructions, connect them to your data and tools, and deploy them as a chatbot that your users or team can interact with. ## What agents can do Agents are flexible and can handle a wide range of tasks. Here are some of the things they can do: * **Answer questions from your data:** Connect your documents, PDFs, spreadsheets, and web content to a Knowledge Base, and the Agent will search through them to give grounded, accurate answers. * **Search the web:** Pull in real-time information from the internet using web search tools like Google Search, Exa AI, or Perplexity. * **Generate and modify media:** Create images from text descriptions, modify existing images, convert text to speech, and transcribe audio to text. * **Read and process files:** Extract text from uploaded documents, read Excel files, and convert between file formats. * **Run code:** Execute Python code in a sandboxed environment to analyze data, process spreadsheets, create charts, and generate files. * **Connect to external apps:** Interact with third-party services like Airtable, Slack, Google Sheets, Asana, Salesforce, and dozens more through integration tools. * **Generate charts and visualizations:** Turn data into bar charts, line graphs, pie charts, scatter plots, and donut charts directly in the chat. * **Delegate to other Agents:** Call specialized sub-agents for specific tasks, creating multi-agent workflows where different Agents handle different domains. * **Run Workflows:** Trigger VectorShift Workflows from within a conversation to execute complex, multi-step automations. You can build any custom automation as a workflow and give your Agent access to it as a tool — something very few platforms support. * **Connect to MCP Servers:** Access external services through the Model Context Protocol for custom integrations. ## Common use cases **Portfolio research assistant:** Search the web for market news and financial research, then deliver sourced summaries so analysts skip manual searching. **Financial document analyst:** Upload spreadsheets and reports, then ask questions and get auto-generated charts and data insights directly in the chat. **Compliance assistant:** Answer natural-language policy questions instantly by grounding responses in your uploaded regulatory guidelines and audit checklists. **Client onboarding assistant:** Guide relationship managers step-by-step through onboarding by pulling CRM records and referencing your internal playbooks. **Risk assessment assistant:** Combine real-time market data with your internal risk frameworks to help analysts draft risk reports faster. **Multi-desk routing:** Route questions to specialized sub-agents for different domains like equities, compliance, and operations — all from one main Agent. ## When to use an Agent vs. a Workflow Agents and Workflows are both powerful, but they're designed for different situations. Here's how to decide which one to use: **Use an Agent when:** * A user needs to interact through a conversation and the next step depends on what they say. * The task requires judgment, reasoning, or deciding between multiple possible actions. * You want to deploy a chatbot that users can talk to directly. * The path to the answer isn't fixed and may vary from question to question. * You need the AI to search through documents, decide which tool to use, and compose a response. **Use a Workflow when:** * The task follows a fixed, predictable sequence of steps every time. * You need to process data in bulk without human interaction. * The automation should run on a schedule or be triggered by an event. * You want deterministic, repeatable results where the same input always produces the same output. * The process involves chaining multiple nodes together in a workflow. **Use both together when:** * You have a conversational Agent that needs to trigger a complex automation. The Agent can use the Run Workflow tool to kick off a Workflow from within a chat. * You have a workflow that needs AI reasoning at one step. A Workflow agent can be embedded as a node inside a larger Workflow. For example, a portfolio research Agent might chat with an analyst to understand their query, then use the Run Workflow tool to trigger a "Fetch and Normalize Market Data" Workflow that follows a fixed sequence: pull data from APIs, clean it, and return a structured dataset for the Agent to summarize. ## How agents work under the hood When a user sends a message, the Agent follows this general process: 1. The Agent reads its instructions to understand its role and guidelines. 2. It looks at the conversation history (if Session Memory is enabled) to understand context. 3. It decides whether it needs to use any tools to answer the question, based on the tool descriptions and its instructions. 4. If it decides to use a tool, it executes the tool (or asks the user for approval, depending on the execution mode). 5. It takes the tool's output and uses it to compose a response. 6. It may repeat steps 3 through 5 multiple times if the question requires multiple tool calls. 7. It sends the final response back to the user. This reasoning loop is what makes Agents different from simple chatbots. They don't just generate text; they actively decide what actions to take and use the results to inform their answers. ## Building blocks of an Agent An Agent is made up of five core building blocks that you configure from a single builder: * **Instructions** tell the Agent who it is and how it should behave. Think of this as the Agent's job description. * **AI Model** powers the Agent's reasoning. You can choose from providers like OpenAI, Anthropic, Google, and Groq, and select a specific model from each. * **Tools** are the actions the Agent can take autonomously. These range from web search and image generation to code execution and third-party app integrations. Crucially, you can also build custom Workflows and use them as tools inside your Agent — giving you a platform-native way to turn any multi-step automation into an Agent capability. * **Knowledge Base** gives the Agent access to your documents and data so it can ground its answers in real information rather than relying on general knowledge alone. * **Session Memory** lets the Agent remember what was said earlier in the same conversation, enabling coherent multi-turn dialogue. The rest of this document walks through how to create and configure each of these building blocks, customize the chatbot interface, monitor usage, and share your Agent with teammates. # Knowledge Base Source: https://docs.vectorshift.ai/platform/agents/knowledge-base Give your Agent persistent knowledge that stays available throughout every session The **Knowledge Base** section in the Agent tab is where you attach persistent knowledge directly to your Agent. This is different from the **Query Knowledge Base** tool — the Knowledge Base section defines the Agent's own background knowledge that is always available, while the Query Knowledge Base tool is a tool the Agent calls on-demand to search specific documents. Think of it this way: the Knowledge Base section is like giving an employee a reference manual they always have on their desk, while the Query Knowledge Base tool is like sending them to search through filing cabinets when a specific question comes up. Knowledge Base section in the Agent builder ## How it works Knowledge attached through this section is persisted for the entire Agent session. The Agent can draw on this knowledge at any time without needing to call a tool. This makes it ideal for: * **Static reference knowledge** — product catalogs, company policies, FAQs, brand guidelines, or any information the Agent should always know. * **Accumulated session knowledge** — information the Agent gathers and stores during a conversation that should persist across messages. For example, an Agent can have three **Query Knowledge Base** tools configured to search different document collections on demand, and *also* have a static global Knowledge Base attached through this section that provides foundational context the Agent always has access to — even if no tool is called. ## Adding a Knowledge Base 1. In the **Knowledge Base** section of the Agent tab, click to attach an existing Knowledge Base or create a new one. 2. Select one or more Knowledge Bases from the dropdown. Create your Knowledge Bases from the **Knowledge Base** section in the main sidebar before building your Agent. Upload your documents and wait for each file to show a green checkmark confirming it has been indexed. Then come back to the Agent builder and attach it here. ## Configure Metadata Click **Configure Metadata** to add metadata to your Knowledge Base documents. Metadata helps the Agent filter and prioritize information — for example, tagging documents by department, date, or document type. Configure Metadata settings ## Settings Click **Settings** to adjust how the Knowledge Base behaves within your Agent. These settings control retrieval behavior like chunk size, overlap, and relevance scoring. Knowledge Base settings panel ## Knowledge Base vs. Query Knowledge Base tool | | Knowledge Base section | Query Knowledge Base tool | | ------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | | **What it does** | Attaches persistent knowledge the Agent always has access to | A tool the Agent calls on-demand to search specific documents | | **When it's used** | Always available — no tool call needed | Only when the Agent decides to search (or is prompted to) | | **Best for** | Static reference material, global context, accumulated knowledge | Searching large document collections, querying specific data | | **Example** | Company brand guidelines the Agent should always follow | Searching a collection of quarterly earnings reports for a specific metric | Use the Knowledge Base section for information your Agent should always know. Use the Query Knowledge Base tool when the Agent needs to search through large or varied document collections on demand. You can use both together — for example, attach a company overview as persistent knowledge and add Query KB tools for searching detailed financial records. # Monitor Your Agent Source: https://docs.vectorshift.ai/platform/agents/manager-tab View session and message analytics, and access individual conversation logs The Manager tab gives you visibility into how your Agent is being used — track adoption trends, spot issues, and review individual conversations. Manager tab overview ## Date and time controls Filter analytics by date range, duration preset (e.g., 30 days), and frequency (e.g., Weekly) to focus on the time period that matters. ## Analytics charts Two charts give you a quick pulse on usage: * **Sessions** — see how many conversations are being started over time. * **Messages** — track total message volume to understand engagement depth. Sessions analytics chart Messages analytics chart ## Sessions table Drill into individual conversations to understand what users are asking and how your Agent is responding. Sessions table Each session shows the session ID, name, start time, last message time, participating users, AI model used, and a link to view the full conversation log. Use the **Filter** button to narrow results or **Export All** to download session data for deeper analysis. # Save and Version Source: https://docs.vectorshift.ai/platform/agents/saving-and-versioning Auto-save, manual save, and version history for your Agent ## Saving Your work in the Agent Builder is auto-saved as you make changes. You'll see a **Draft saved** indicator in the top-right corner confirming this. To explicitly save, click the **Save** button in the top-right corner. The button will show a green **Saved** state when the save is complete. ## Versioning Click the **Versions** button in the top-right corner to access version history for your Agent. This lets you manage and track changes over time. Version history In the Interface tab, the **Use Latest Version** checkbox (enabled by default) ensures that the deployed chatbot always runs the most recently saved version of your Agent. Before making significant changes to a working Agent, save a version first. This gives you a safe point to roll back to if the new changes don't work as expected. # Session Memory Source: https://docs.vectorshift.ai/platform/agents/session-memory Control whether your Agent retains context across a conversation At the very bottom of the Agent tab, you'll find the Session Memory section. This controls whether your Agent remembers previous messages within a single conversation session. There is a toggle with two options: **Enabled** and **Disabled**. The default state is Enabled. Session Memory toggle When enabled, the Agent will retain the context of earlier messages in the conversation, allowing it to reference things the user said previously and maintain a coherent, multi-turn dialogue. When disabled, each message is treated independently with no memory of prior exchanges. When Session Memory is enabled, a **Configure** button appears that opens a settings drawer. This drawer lets you control how session memory data is processed and stored. The configuration options mirror those found in the Knowledge Base settings panel, including Embedding Model, Advanced Document Analysis, Hybrid search, Chunk Size, Chunk Overlap, Splitter Method, Segmentation Method, Processing Model, and Apify Key. Refer to the [Knowledge Base Settings](/platform/agents/knowledge-base#settings) section for details on each field. Enable session memory for most conversational use cases so your Agent can maintain context across a multi-turn dialogue. For example, a portfolio research assistant needs to remember that an analyst said "focus on emerging markets" earlier in the conversation so follow-up questions like "which ones have the highest risk?" still make sense. Only leave session memory disabled if you have a specific reason, such as building an Agent that answers standalone, one-off questions where prior context could cause confusion. # Share with Teammates Source: https://docs.vectorshift.ai/platform/agents/sharing Invite teammates to view or edit your Agent project Collaborate on your Agent by inviting teammates as viewers or editors — so your team can build, review, and improve the Agent together. To share your Agent, click the **Share** button in the top-right corner of the Agent builder (next to the **Save** and **Versions** buttons). This opens the share dialog: Share with teammates In the share dialog, search for teammates by name or email, assign a role (e.g., Editor or Viewer), and click **+ Add**. You'll see all current members listed with their name, email, and role. The project creator is the **Administrator**. # Tips and Best Practices Source: https://docs.vectorshift.ai/platform/agents/tips Guidelines for building effective, reliable Agents ## Write instructions like a job description Define the role, list specific responsibilities, describe how to handle common scenarios, and set boundaries on what the Agent should not do. The more context you provide, the more consistently the Agent will behave. **Example instruction:** *You are a portfolio research assistant for Apex Capital. Your responsibilities:* * *Answer analyst questions about portfolio holdings using the Query Knowledge Base tool* * *Find latest market news using the Research Web tool* * *Always cite your sources and flag when information may be outdated* * *Do not provide investment advice or make buy/sell recommendations* * *If you cannot find an answer in the Knowledge Base, say so clearly rather than guessing* ## Start lean on tools Start with fewer tools and add more as needed. An Agent with 3 to 5 well-described tools will typically outperform one with 15 poorly described tools. Each tool you add is another decision the Agent has to make, so keep the toolset focused on what the Agent actually needs. For a customer support Agent, start with just **Query Knowledge Base** (for FAQs), **Research Web** (for product updates), and **Code Interpreter** (for data lookups). Add more tools only after testing shows the Agent needs them. ## Gate tools that modify data Use "Require User Approval" for any tool that modifies external data, such as updating CRM records, sending Slack messages, or writing to files. This gives the user a chance to review and confirm before the action is taken, preventing accidental changes. Set tools like **Airtable > Update Records**, **Slack > Send Message**, and **Google Sheets > Write Cell** to Require User Approval. Keep read-only tools like **Research Web** and **Query Knowledge Base** on Auto Run for a smooth experience. ## Keep sub-agents domain-focused When building multi-agent setups, keep each sub-agent focused on a single domain. A "Fixed Income Agent" that only handles bond and rate questions will be more reliable than a general "Research Agent" that handles everything. In your main Agent's instructions, define clear routing logic: *When the user asks about fixed income or bonds, use the Run Agent tool to call the Fixed Income Agent. When the user asks about equities or stock positions, use the Run Agent tool to call the Equities Agent.* ## Test retrieval before scaling your knowledge base Upload your most important documents to the Knowledge Base first and test retrieval in the chat preview before adding more. This lets you verify that the chunk size, overlap, and embedding model are working well for your content before scaling up. Upload 3–5 representative documents first. Ask the Agent questions you know the answers to and check whether the responses are accurate and well-sourced. If retrieval is off, adjust the settings before adding the full document set. ## Use @ tagging to debug and reference specific resources Use the **@** tag feature in chat to explicitly reference specific tools, knowledge bases, agents, or other resources. This is useful both for debugging and for directing the Agent to use a specific resource. @ tag dropdown menu showing available resources **Examples of @ tag usage:** * Type `@Q4 Earnings Report` to force the Agent to query that specific Knowledge Base document: *"`@Q4 Earnings Report` What was our revenue growth last quarter?"* * Type `@Fixed Income Agent` to route a question to a specific sub-agent: *"`@Fixed Income Agent` What is the current yield curve for Treasury bonds?"* * Type `@Code Interpreter` to force the Agent to use code for a calculation: *"`@Code Interpreter` Calculate the compound annual growth rate from $100K to $250K over 5 years"* This is especially useful when the Agent picks the wrong tool or Knowledge Base automatically — tagging lets you override its decision and test specific resources in isolation. ## Review real conversations in the Manager tab Monitor the Manager tab regularly after deploying your Agent. The sessions table lets you review actual conversations, which is the best way to spot issues with instructions, tool usage, or knowledge base gaps that you might not catch during testing. Look for patterns in conversations where the Agent fails: Does it pick the wrong tool? Does it miss information from the Knowledge Base? Use these patterns to refine your instructions and tool descriptions. ## Surface sources for knowledge base answers Enable "Show Sources" in the AI Model's Advanced Settings when your Agent answers questions from a Knowledge Base. This builds user trust by letting them see where the information came from — especially important for compliance, risk, and regulatory use cases where analysts need to verify citations. With Show Sources enabled, the Agent will display clickable source references alongside its answers, so users can verify the original documents. This is critical for regulated industries where audit trails matter. # Files Source: https://docs.vectorshift.ai/platform/files Upload and manage files You can view your Files under the Files sub-tab in the Storage tab. Here, you can upload files to be utilized in Workflows. To upload a File, click "New" and then "Upload File". File Page Utilize Files in your Workflows with the [File Node](/platform/pipelines/data-loaders/file). Additionally, you can leverage files in vector stores. You can also save Workflow outputs to your Files by using a [File Save Node](/platform/pipelines/general/file-save). # Agentic Chatbot Source: https://docs.vectorshift.ai/platform/interfaces/chatbots/agentic Build an autonomous chatbot powered by a VectorShift Agent An Agentic chatbot is a conversational interface powered by a VectorShift Agent. Instead of following a fixed sequence of workflow nodes, the Agent reads the user's message, decides which tools to call, and chains together actions autonomously. You define what the Agent can do by giving it tools and a knowledge base; the Agent figures out how to use them. If you are completely new to VectorShift, head to the [Quickstart](/quickstart) first. This page assumes you understand basic chatbot concepts covered in the [Chatbots overview](/platform/interfaces/chatbots/overview). ## What can an Agentic chatbot do? Start with the outcome you want your users to experience: * **"Book a meeting on my calendar when someone asks for availability."** The Agent uses a calendar tool automatically, checks open slots, and confirms the booking without additional prompting. * **"Search the knowledge base and cite sources when answering product questions."** The Agent retrieves relevant documents, extracts the answer, and formats a response with source references. * **"Create a support ticket in Jira when a bug is reported."** The Agent recognizes the intent, gathers details from the conversation, and calls the Jira integration to file the ticket. In each case, you do not hard-code the sequence of steps. The Agent decides what to do based on the conversation. ## Creating an Agentic chatbot ### Step 1. Create a project with an Agent Start by creating an Agent project. The Agent is the engine behind an Agentic chatbot — it contains the LLM and system instructions that determine how your chatbot reasons and responds. For a full walkthrough on creating Agents, see [Agents](/platform/agents). Creating a new Agent project in VectorShift ### Step 2. Give instructions to the Agent Configure the Agent's system instructions to define its persona, constraints, and how it should respond. Instructions are sent to the LLM before every conversation and shape how the Agent interprets user messages and decides which tools to call. Configuring system instructions for the Agent ### Step 3. Add tools to the Agent Give your Agent the capabilities it needs by adding tools — integrations, API calls, data loaders, and knowledge bases. The Agent will autonomously decide which tools to call based on the user's message. Adding tools to the Agent in the Agent editor ### Step 4. Go to the Interface tab Once your Agent is ready, navigate to the **Interface** tab to configure how users will interact with it. This is where you turn your Agent into a chatbot. Navigating to the Interface tab to configure the chatbot ### Step 5. Personalize the interface Customize the chatbot's appearance and behavior — set your brand colors, welcome message, bot name, starter prompts, and avatars. For full details on customization options, see [Customizing your chatbot](/platform/interfaces/chatbots/customize). Personalizing the Agentic chatbot interface ### Step 6. Deploy Deploy the chatbot to make it available to your users. Choose from a shareable link, an embedded widget, Slack, WhatsApp/SMS, or API. See [Sharing and deploying](/platform/interfaces/chatbots/deploying) for details on each channel. ## How it works When a user sends a message, the following happens behind the scenes: 1. The message is passed to the Agent along with the conversation history. 2. The Agent's LLM reads the message, the list of available tools, and any system instructions you have configured. 3. The LLM decides which tool (if any) to call first. If no tool is needed, it generates a direct response. 4. If a tool is called, the Agent executes it, reads the result, and decides whether to call another tool or respond to the user. 5. This loop continues until the Agent produces a final response, which is returned to the user as the chatbot's reply. The key difference from a [Workflow chatbot](/platform/interfaces/chatbots/workflow) is that you never define the execution sequence. The Agent adapts its behavior based on each conversation. ## Example Agentic chatbots you can build Agentic chatbots shine in finance where users ask open-ended questions that require pulling from multiple sources or taking multi-step actions — and where you cannot always predict the exact sequence in advance. * **Investment research assistant** — A portfolio manager asks "Give me a summary of AAPL's recent earnings and how it compares to analyst expectations." The Agent decides to call a market data tool to fetch earnings figures, query a knowledge base of analyst reports, and then synthesize both into a coherent answer — all in a single response. No fixed workflow could anticipate every combination of instruments and data sources a user might ask about. * **Client onboarding bot** — A new client opens the chatbot and asks to open an account. The Agent gathers the required information through natural conversation, cross-checks eligibility criteria against an internal rules knowledge base, and when everything is complete, calls a CRM integration to create the client record. It handles follow-up questions mid-flow ("Can I open a joint account instead?") without losing track of what has already been collected. * **Trade reconciliation assistant** — An operations analyst asks "Why does our position in XYZ differ from the custodian's record?" The Agent calls a trade data API to pull internal records, queries the custodian feed tool for the external position, identifies the discrepancy, and explains the likely cause — all autonomously. The analyst does not need to specify which systems to check; the Agent determines that based on the question. * **Regulatory Q\&A bot** — A compliance officer asks "Does this proposed transaction structure comply with MiFID II best execution requirements?" The Agent searches a knowledge base of regulatory documents, retrieves the relevant rules, and generates a structured answer with citations. If the officer asks a follow-up ("What documentation would we need to demonstrate compliance?"), the Agent picks up the context and continues without starting over. ## Next steps Build a chatbot backed by a step-by-step workflow you define Choose how your chatbot appears to users # Chat analytics Source: https://docs.vectorshift.ai/platform/interfaces/chatbots/analytics Track performance, review traces, and manage conversations from the Analytics and Manager tabs Once your chatbot is live, you have two tabs for monitoring and reviewing it: the **Analytics** tab for workflow-level performance metrics and traces, and the **Manager** tab for conversation history, user feedback, and exports. ## Analytics tab The Analytics tab shows performance data for the workflow or Agent powering your chatbot. It has two sub-tabs: **Dashboard** and **Traces**. ### Controls At the top of the Analytics tab, three controls let you slice the data: * **Date range** — presets include 24 hours, 7 days, 30 days, 3 months, 1 year, or a custom range. All charts update to match. * **Granularity** — choose how data points are grouped: Hourly, Daily, Weekly, Monthly, Yearly, or All Time. * **Filter** — narrow charts to a specific workflow or Agent by name. ### Dashboard The Dashboard shows five metric panels: #### Runs The **Runs** area chart shows the total number of workflow executions over time. The header displays **Total runs** for the selected period. Use this to spot adoption trends, identify peak usage periods, and measure the impact of changes like adding the chatbot to a new channel. #### Failures The **Failures** chart shows how many runs failed during the selected period. The header displays **Total failures**. A healthy chatbot should have near-zero failures. Use this to catch broken workflows early — a sudden spike usually means a recent change introduced an error. Cross-reference with the Traces table to find the root cause. #### Model Costs The **Model Costs** panel shows the total spend for the selected period in USD. The breakdown table lists each model used, the number of tokens consumed, and the cost in USD. Use this to track LLM spend and compare costs across model versions. #### Workflow Latency The **Workflow Latency** chart shows average end-to-end workflow latency in seconds over time. Switch between the **50th**, **75th**, **90th**, and **99th** percentile views to understand your typical and worst-case response times. Use this to detect regressions after workflow changes. #### Model Usage The **Model Usage** chart shows total token consumption over time. Toggle between **Tokens** and **AI Credits** views. Use the **All models** dropdown to filter to a specific model. Use this to monitor consumption trends and plan capacity. #### Average node latencies Below the charts, the **Average node latencies** panel shows the average processing time for each node in the workflow. Use this to identify bottlenecks — if one node is consistently slow, that is where to start optimizing. ### Traces The **Traces** sub-tab lists every individual workflow execution as a row in the **Workflow Traces** table. | Column | What it tells you | | -------------- | -------------------------------------------------------------------------------------------- | | **Trace ID** | Unique identifier for this run — copy it to share with support or reference in logs | | **Source** | What triggered the run (e.g. a Form, the chatbot interface, or an API call) | | **Status** | Success or Failure | | **Start Time** | When the run began | | **Latency** | How long the full run took in seconds | | **AI Cost** | Cost of LLM calls for this run in USD | | **Tokens** | Total tokens consumed | | **Caller** | Who or what initiated the run (user email or system source) | | **Details** | Click the eye icon to inspect the full trace, including per-node inputs, outputs, and timing | Use the **Filter** button to narrow traces by status, source, or other fields. ## How to access the Manager tab There are two ways to reach the Manager view: 1. **From the Chatbots page:** Click **Manage chatbot analytics** at the top of the Chatbots tab. 2. **From inside the chatbot builder:** Open the chatbot you want to inspect and click the **Manager** tab. Once you are in the Manager view, use the pull-down menu at the top to select which chatbot's data you want to see. All metrics and charts update to reflect the selected chatbot. The navigation path to the Manager tab from the Chatbots page ## Understanding the Manager dashboard The dashboard has three sections: charts that show trends at a glance, a feedback view, and a conversations table for drilling into individual exchanges. ### Date range selector Use the date picker at the top to focus on a specific time window. All charts and the table update to match your selection. Use this to: * **Compare periods** — check if a workflow change last week improved or worsened performance. * **Investigate incidents** — narrow the range to a specific day when users reported problems. * **Track growth** — expand to a monthly view to see adoption trends over time. The date range selector at the top of the analytics dashboard ### Runs chart — "How much is my chatbot being used?" The **Runs** area chart shows conversation volume over time. Each data point represents the number of chatbot runs for that day. Use this to: * **Spot adoption trends** — a steady increase means users are finding and returning to the chatbot. * **Identify peak hours/days** — schedule workflow updates or maintenance during low-traffic periods. * **Measure the impact of changes** — if you added the chatbot to a new page or channel, you should see a corresponding spike. The header shows **Total runs** for the selected period. The Runs area chart showing chatbot usage over time ### Failures chart — "Is my chatbot reliable?" The **Failures** bar chart shows how many runs failed during the selected period. A healthy chatbot should have near-zero failures. Use this to: * **Catch broken workflows early** — a sudden spike usually means a recent workflow change introduced an error. * **Detect rate limits** — gradual increases in failures during peak hours may indicate you're hitting API rate limits. * **Correlate with external outages** — if failures spike across all chatbots simultaneously, the issue is likely upstream (e.g., an LLM provider outage). Cross-reference spikes with the **Error Message** column in the conversations table below to find the root cause. The header shows **Total failures** for the selected period. The Failures bar chart ### Feedback chart — "Are users happy with the responses?" The **Feedback** chart visualizes the thumbs-up and thumbs-down reactions users give to bot responses. This chart only shows data if you've enabled the **Turn On User Feedback** toggle in the chatbot's [customization settings](/platform/interfaces/chatbots/assistant). Use this to: * **Measure response quality** — a high ratio of negative feedback means your workflow's prompts, knowledge base, or LLM configuration needs work. * **Track improvement over time** — after updating your workflow, check whether positive feedback increases. * **Identify problem areas** — pair feedback trends with conversation transcripts to find which topics produce the most negative reactions. The header shows **Total feedback** for the selected period. The Feedback chart ## Conversations table Below the charts, a table lists every conversation for the selected chatbot. Each row is one conversation thread. This is where you go from high-level trends to specific interactions. | Column | What it tells you | How to use it | | ----------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | **Source** | Where the conversation came from: web (share link or embed), Slack, Twilio (WhatsApp/SMS), or API | Identify which deployment channel drives the most traffic and where to focus optimization | | **Name** | Auto-generated conversation title based on the first message (LLM summary, up to 4 words) | Quickly scan what users are asking about without opening each conversation | | **Status** | Success or Failure | Filter by Failure to find and fix broken conversations | | **Start Time** | When the first message was sent | Identify peak usage hours | | **End Time** | When the last message was received | Measure conversation duration — long conversations may indicate the bot is struggling to resolve the query | | **User Email** | The user's email (populated when SSO is enabled or the user is logged in) | Identify power users or follow up with users who had bad experiences | | **Details** | **View** (read the full exchange) and **Export** (download as CSV or JSON) | Drill into specific conversations for quality review or debugging | | **Error Message** | Error details for failed conversations (hover to read full message) | Diagnose workflow failures — common errors include timeout, rate limit, and missing knowledge base | The Conversations table with sample data ### Viewing a conversation Click **View** on any row to open the full message exchange. You see every message in chronological order with timestamps. Use this to: * **Debug unexpected answers** — read what the user asked and what the bot said to understand why a response was off. * **Audit for quality** — spot-check conversations to ensure the bot stays on-topic and accurate. * **Discover training gaps** — find questions the bot couldn't answer well, then update your workflow's knowledge base or prompts accordingly. ## Filtering and exporting ### Filtering — find the conversations that matter Click the **Filter** button above the table to narrow results: * **Status** — show only **Success** or **Failure** conversations. Use this to quickly isolate failures and investigate what went wrong. * **Source** — filter by deployment channel (web, Slack, Twilio, API). Useful for comparing performance across channels, for example: "Are Slack users getting better answers than web users?" * **Text search** — search by conversation name, user email, or error message content. Use this to find a specific user's conversations or all conversations that hit the same error. ### Exporting individual conversations Click **Export** on any row and choose **CSV** or **JSON** to download that conversation's full message history. Use this when: * You need to share a specific conversation with your team for debugging. * A user reports a problem and you want to review exactly what happened. ### Exporting all conversations Click **Export All** at the top of the table to download every conversation in the current date range as **CSV** or **JSON**. Use this to: * Import into a spreadsheet for bulk analysis. * Feed into your own analytics pipeline or BI tool. * Create training datasets from real user conversations to improve your workflow. The Export All button and format options ## Using your analytics data The analytics dashboard helps you answer questions like: * **Are users satisfied?** Check the Feedback chart. A high ratio of negative reactions suggests the chatbot's responses need improvement, whether through better workflow logic, updated knowledge base content, or clearer prompts. * **Is the chatbot reliable?** Look at the Failures chart. A sudden spike in failures likely correlates with a workflow change or an external service outage. Cross-check with the Error Message column in the conversations table to find the root cause. * **Where is traffic coming from?** The Source column tells you which deployment channel is generating the most conversations, helping you decide where to focus optimization efforts. * **What are users asking about?** Open individual conversations to read the actual exchanges. Look for patterns in questions that the chatbot struggles with, and use those insights to improve your workflow's knowledge base or prompts. ## Next steps If your analytics reveal issues with chatbot performance, revisit the workflow powering it or adjust the chatbot's configuration: Review the workflow connection and input/output mapping Adjust prompts, feedback settings, and follow-up question generation # Chat via API Source: https://docs.vectorshift.ai/platform/interfaces/chatbots/api Integrate chatbot functionality into your own application using the REST API If you are building your own application and want to integrate chatbot functionality into it, you can call the chatbot directly through the VectorShift API. This gives you full control over how messages are sent and responses are displayed, and it supports both synchronous and streaming responses. See the complete API reference for all chatbot endpoints — run, list, upload, and terminate ## Prerequisites Your chatbot must be deployed before making API calls. Toggle **Deployment Enabled** in the chatbot builder's Export tab. You also need your VectorShift **API key**, which you can find by clicking your profile icon in the top-left corner of the VectorShift app, then clicking **API Keys**. The profile menu with API Keys highlighted ## How it works You send a POST request to the chatbot endpoint with your message. VectorShift runs the connected workflow and returns the chatbot's response. To maintain conversation continuity across multiple messages, you include the `conversation_id` from the previous response in each subsequent request. 1. **First message:** Send your text without a `conversation_id`. The API returns the bot's response along with a new `conversation_id`. 2. **Subsequent messages:** Include the `conversation_id` from the previous response. The chatbot retrieves the conversation history and responds in context. 3. **New conversation:** Omit the `conversation_id` to start a fresh conversation at any time. Always store the `conversation_id` from the first response and include it in every subsequent call. Without it, each call starts a new conversation and the chatbot loses context. ## Authentication Every API request must include your VectorShift API key in the `Api-Key` header. You can generate and manage API keys from your profile settings. | Header | Value | | -------------- | ------------------------ | | `Content-Type` | `application/json` | | `Api-Key` | Your VectorShift API key | ## Request and response formats ### Endpoint ``` POST https://api.vectorshift.ai/api/chatbots/run ``` ### Request body | Field | Type | Required | Description | | ----------------- | ------- | ----------------------- | --------------------------------------------------------------------------------------------------- | | `input` | string | Yes | The user's message | | `chatbot_name` | string | Yes (or `chatbot_id`) | The name of the chatbot to run | | `chatbot_id` | string | Yes (or `chatbot_name`) | The ID of the chatbot to run | | `conversation_id` | string | No | The conversation ID from a previous response. Omit to start a new conversation. | | `stream` | boolean | No | Set to `true` to receive the response as a stream of Server-Sent Events (SSE). Defaults to `false`. | ### Response (non-streaming) ```json theme={"languages":{}} { "status": "success", "output": "Your order #12345 is currently in transit and expected to arrive by Friday.", "conversation_id": "abc123def456" } ``` | Field | Description | | ----------------- | -------------------------------------------------------------------------- | | `status` | `"success"` or `"failed"` | | `output` | The chatbot's response text | | `conversation_id` | Store this and include it in the next request to continue the conversation | ### Response (streaming) When `stream` is set to `true`, the response is delivered as Server-Sent Events. Each event contains a JSON object with the current `output` text and the `conversation_id`. The final event includes the complete response. ```json theme={"languages":{}} {"output": "Your order", "conversation_id": "abc123def456"} {"output": "Your order #12345 is currently", "conversation_id": "abc123def456"} {"output": "Your order #12345 is currently in transit and expected to arrive by Friday.", "conversation_id": "abc123def456"} ``` ## Conversation management Each conversation is identified by a `conversation_id`. The chatbot automatically generates a name for new conversations based on the first message (using a short LLM summary). To manage conversations programmatically: * **Start a new conversation:** Send a request without a `conversation_id`. * **Continue an existing conversation:** Include the `conversation_id` from the previous response. * **List conversations:** Use the [List Chatbots API](/api-reference/chatbots/list) to retrieve chatbot metadata, including associated conversations. ## Code examples ### Python ```python theme={"languages":{}} import requests API_KEY = "your_api_key" CHATBOT_ID = "your_chatbot_id" url = "https://api.vectorshift.ai/api/chatbots/run" headers = { "Content-Type": "application/json", "Api-Key": API_KEY, } # First message (no conversation_id) payload = { "input": "Where is my order #12345?", "chatbot_id": CHATBOT_ID, } response = requests.post(url, json=payload, headers=headers) data = response.json() print(data["output"]) conversation_id = data["conversation_id"] # Follow-up message (with conversation_id) payload = { "input": "Can I change the shipping address?", "chatbot_id": CHATBOT_ID, "conversation_id": conversation_id, } response = requests.post(url, json=payload, headers=headers) data = response.json() print(data["output"]) ``` ### JavaScript ```javascript theme={"languages":{}} const API_KEY = "your_api_key"; const CHATBOT_ID = "your_chatbot_id"; const url = "https://api.vectorshift.ai/api/chatbots/run"; // First message (no conversation_id) const firstResponse = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "Api-Key": API_KEY, }, body: JSON.stringify({ input: "Where is my order #12345?", chatbot_id: CHATBOT_ID, }), }); const firstData = await firstResponse.json(); console.log(firstData.output); const conversationId = firstData.conversation_id; // Follow-up message (with conversation_id) const followUpResponse = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "Api-Key": API_KEY, }, body: JSON.stringify({ input: "Can I change the shipping address?", chatbot_id: CHATBOT_ID, conversation_id: conversationId, }), }); const followUpData = await followUpResponse.json(); console.log(followUpData.output); ``` ### cURL ```bash theme={"languages":{}} # First message (no conversation_id) curl -X POST https://api.vectorshift.ai/api/chatbots/run \ -H "Content-Type: application/json" \ -H "Api-Key: your_api_key" \ -d '{ "input": "Where is my order #12345?", "chatbot_id": "your_chatbot_id" }' # Follow-up message (include conversation_id from the first response) curl -X POST https://api.vectorshift.ai/api/chatbots/run \ -H "Content-Type: application/json" \ -H "Api-Key: your_api_key" \ -d '{ "input": "Can I change the shipping address?", "chatbot_id": "your_chatbot_id", "conversation_id": "abc123def456" }' ``` ## Rate limits and error handling If the chatbot fails to run (for example, the connected workflow encounters an error), the response will have `"status": "failed"` and include an error message. Common causes include: * The chatbot is not deployed (Deployment Enabled is off). * The connected workflow has a configuration error. * The API rate limit has been exceeded. API calls are subject to rate limiting. If you receive a rate limit error, wait before retrying. See [Subscriptions](/account/subscriptions/overview) for details on rate limits by plan. For the full API reference, including upload, terminate, and listing endpoints, see the [API Reference](/api-reference/chatbots/run). ## Next steps Track usage, review conversations, and export data Explore other deployment channels # Chat Assistant Source: https://docs.vectorshift.ai/platform/interfaces/chatbots/assistant Deploy a full-page chat experience and customize it to match your brand The Chat Assistant template gives your users a standalone, full-page chat interface. They open a link and are immediately in a conversation — no website to embed into, no launcher to configure. The chatbot is the entire experience. It works well for internal tools, dedicated support portals, and any situation where the chatbot is the primary thing users are there to do. This page walks you through what a Chat Assistant looks like, how to configure and personalize it, and how to get it in front of your users. ## What does a Chat Assistant look like? A Chat Assistant occupies the full browser window. On the left side, users see a conversation list showing all their previous chats. On the right side is the active conversation where they send messages and receive responses. The Chat Assistant full-page interface showing the sidebar and conversation area ## Editing your Chat Assistant The chatbot builder organizes settings into four panels: **Configuration**, **General**, **Style**, and **Security**. Work through them in order to configure, personalize, and secure your chatbot. The General and Style tabs for customizing the chatbot ### Step 1. Configuration Connect the chatbot to the workflow or Agent that powers it. * **Input** — select the variable that carries the user's message into your workflow. If you pick the wrong one, the bot receives an empty input and cannot respond correctly. * **Output** — select the variable that carries the bot's reply back to the user. This must point to the node where your final answer is generated. * **Use Latest Version** — keep this on during active development so every change you make is reflected immediately. Pin it to a specific version before a production release to prevent accidental changes from going live. ## Customizing the user experience ### Step 2. General The General panel is where you shape the entire look, feel, and personality of the chatbot — from the first thing users see to the label on every message. #### Display The display section is the first thing users see when they open the chatbot. Getting this right means users immediately understand what the bot does and trust it enough to start typing. * **Display Title** — put your brand name here so users know they are talking to your product, not a generic tool. Replace `VectorShift` with your company name or chatbot name — for example, `Acme Advisor` for a client-facing tool, or `People Ops Assistant` for an internal HR bot. * **Display Image** — upload your logo so your brand appears in the chat header and next to every bot response. A recognizable image builds trust, especially for client-facing tools. Recommended size: 56 × 56 px, PNG or JPEG. * **Welcome display description** — tell users exactly what the chatbot can help with before they send a single message. Replace `Hi, how can I assist you today?` with something specific like `Ask me about your portfolio, account settings, or compliance questions.` A clear description gets users to the right question faster and reduces drop-off. The Display Title and Welcome Description fields in the General panel #### Message input * **Placeholder for message input field** — guide users toward the right first question instead of leaving them staring at a blank box. Replace the generic `Write a message` with something like `Ask about your account, transactions, or portfolio...`. The more specific the placeholder, the faster users engage. The Placeholder for message input field highlighted in the chatbot preview #### Suggested prompts Give users a running start. Instead of facing a blank input box, they see clickable buttons for the most common questions and can get an answer in one click without typing anything. Toggle **Enable initial prompts**, then click **+ Add Suggestion** to add prompts. Each suggestion has a **Title** (the button label users see) and **Content** (the message sent when clicked). For example, a financial advisory chatbot might offer: `"What's my current portfolio allocation?"`, `"Show me recent transactions"`, and `"How do I update my risk profile?"` — the top three questions your team handles every day, now answered instantly. Enable initial prompts with suggestions configured in the General panel #### Follow-up questions After the bot responds, it can suggest what to ask next — keeping users in the conversation and helping them discover capabilities they would not have thought to ask about on their own. * **Generate related questions** — turn this on to automatically surface follow-up questions after each response. This is especially useful when your chatbot covers a broad topic and users may not know the full range of what they can ask. Enabled by default. * **Number of related questions** — start with `3`. That is enough to spark the next question without overwhelming the screen. Increase this if your chatbot covers a wide topic area with many natural follow-ups. * **Guidelines for generating related questions** — prevent the bot from suggesting questions it cannot handle well. For example: `Focus on portfolio performance, risk management, and tax implications. Do not suggest questions about specific stock picks or personal legal advice.` Without guidelines, follow-ups may lead users into topics the bot cannot answer confidently. Follow-up questions settings and preview in the General panel If you notice users frequently hitting dead ends after follow-up suggestions, tighten the guidelines to keep suggestions within topics the bot handles well. #### Message senders These labels appear next to every single message in the conversation. Getting them right makes the chatbot feel purpose-built for your product rather than a generic tool. * **Name for user messages** — change `User` to something that fits who is on the other end. `You` feels conversational, `Client` fits a financial services tool, `Advisor` works for an internal analyst tool. * **Name for bot messages** — change `Assistant` to your bot's name or brand. Every response carries this label, so it reinforces your identity throughout the entire conversation. Use your product name, company name, or a persona like `Finance Bot`. Name for user messages and Name for bot messages fields #### Processing indicator While the bot generates a response, users see a loading state. A well-configured indicator reduces perceived wait time and reassures users that something is actually happening. * **Message to display when assistant is processing** — replace the generic `Understanding your request...` with something that reflects what your bot is actually doing. `Analyzing your portfolio...`, `Searching your knowledge base...`, or `Checking your account...` feels more purposeful and builds user confidence during the wait. * **Icon to display when messages are processing** — upload a custom loading icon (56 × 56 px, PNG or JPEG) to replace the default spinner. Using an animated GIF with your logo creates a polished, branded experience that reinforces trust. Processing text and icon settings highlighted in the General panel #### Branding * **Powered by VectorShift** — turn this off if you are building a white-labeled product and do not want end users to know the underlying platform. Clients and end users will only see your branding. ## Designing your chatbot's look ### Step 3. Style A chatbot that matches your brand feels like part of your product. One that does not looks like a third-party widget bolted on. * **Avatar Image** — upload your logo so your brand appears in every bot response bubble, not just the header. This is the most visible branding element in an active conversation. Recommended size: 56 × 56 px, PNG or JPEG. * **Accent color** — set this to your primary brand color so buttons, links, and interactive elements feel native to your product rather than defaulting to VectorShift purple. * **Messages font** — match this to your product's typography. A font mismatch is a subtle signal to users that this is a third-party tool rather than a native part of your experience. Avatar Image and Accent color settings in the Style panel ## Adding security features By default, anyone with the link can access your Chat Assistant. The **Security** panel gives you two options to lock it down. SSO and password protection are mutually exclusive — enabling one disables the other. ### Protect with SSO Auth Use this for internal tools where access should be limited to employees or team members with VectorShift accounts. When a user opens the link, they are redirected to VectorShift's login page. Anyone without an account is blocked before they ever reach the chatbot. The SSO protection panel in the Security section ### Protect with Password Use this to share a chatbot with a specific external group — clients, partners, beta users — without requiring them to create VectorShift accounts. Share the password directly and only people who have it can chat. Customize the login screen under **Customize Login Page** so it matches your brand rather than showing generic defaults: * **Change Header** — replace `Authenticate to Chatbot` with something on-brand like `Enter your access code`. * **Change Password Text** — replace `Password` with `Access code` or whatever label fits your context. * **Change Button Text** — replace `Submit` with `Continue` or `Enter`. The password protection panel in the Security section Test your security setup by opening the chatbot URL in an incognito browser window before sharing it. This ensures you experience exactly what your users will see. ## Deploying your Chat Assistant From the **Interface** tab, you have three ways to get your chatbot in front of users: ### Share a direct link Click **Open Chatbot** at the top of the Interface tab to open the live chatbot in a new tab. Copy the URL to share it — by email, Slack message, or anywhere else your users will find it. ### Embed on a website Click **Embed Chatbot** at the top of the Interface tab to open the embed modal. It provides two code snippets: * **Script** — a `