# Ask Sage Documentation — Full Text > Full text of the Ask Sage documentation, cleaned for LLM ingestion. See /llms.txt for a structured index. --- # Chat Source: /docs/v2/asksage-platform/asksage-platform-parent.html # Chat Leverage the power of GenAI (Generative Artificial Intelligence) without locking into a specific model or dataset ![Ask Sage Chat User Interface](/assets/images/asksage-platform-v2-new-ui.png) ### Welcome to Chat The Ask Sage Chat is a generative AI platform that allows enterprises and its users to leverage the power of GenAI. The platform is designed to be user-friendly, scalable, and secure, allowing users to interact with the platform. In this section, you will find information on how to use and interact with Chat, ingest data, utilize plugins, customize your account by creating custom personas and prompts, and manage your own account. **Flexibility at Your Fingertips:** Ask Sage brings the power of GenAI to your fingertips, allowing you to generate text, code, and much more with ease without locking you into a specific model or dataset. We provide you with the flexibility to choose the model, dataset, and fine-tuning options (such as temperature and creativity level) you want to use to generate the best results for your use case. **Getting Started:** We recommend that you start with the [Getting Started](/docs/v2/asksage-platform/getting-started/getting-started.html) section to familiarize yourself with the platform and its features and then move on to the other sections based on your requirements and utilization of the platform. --- # Getting Started Source: /docs/v2/asksage-platform/getting-started/getting-started.html # Getting Started with Ask Sage Master the Ask Sage Chat interface and unlock the full potential of AI-powered interactions ![Ask Sage User Interface Overview](/assets/images/asksage-platform-v2-new-ui-explained.png) **Your Journey Begins:** This guide will walk you through the Ask Sage Chat User Interface, helping you understand each component and feature. Mastering these fundamentals is crucial to generating optimal results for your use cases. ---------------- ## User Interface (UI) ### Ask Sage Platform Overview The Ask Sage platform is designed to be user-friendly for organizations and their users to interact with GenAI models. The UI is divided into five main sections: Prompt Settings, Prompt Window, Inference Window, Chat History, and Side Bar Menu. ----------------- ### Prompt Window - A ### Prompt Window ![Ask Sage Prompt Window Interface](/assets/images/asksage-platform-v2-prompt-window.png) This is where users can enter a prompt, which is like a question, query or set of instructions/commands they want the model to follow in order to generate a response. The prompt window includes several interactive features to enhance user experience: ### Attachment Button Upload files such as images and documents. Enables text generation based on the content without storing in the dataset. ### Tools Menu Access comprehensive prompt configuration options and settings. ### Model Selection Select from a variety of models available on the platform for different functionalities. ### Enhance Prompt Refines and optimizes inputs to improve clarity, context, and specificity for better responses. ### Microphone Button Generate text using voice input, making prompt creation easier without typing. **Multiple File Support:** The platform supports uploading 5 files simultaneously. Please note that you are still subject to the [context window limitations](/docs/v2/asksage-platform/getting-started/conversation-context.html) of the model in use. ![Multiple File Attachment Interface](/assets/images/asksage-platform-v2-multiple-file-attachement.png) ----------------- ### Tools Menu - B ### Prompt Tools & Configuration ![Ask Sage Hyperparameters Configuration](/assets/images/asksage-platform-v2-hyperparamters.png) Here users can set the various features for a prompt. This includes `Adding photos and files`, `Persona`, `Prompts`, `Plugins`, `Datasets`, `Web search`, `Deep agent`, `Temperature`, and `MCP tools` they want to reference or activate for the prompt. **Learn More:** In the following [Prompt Features](/docs/v2/asksage-platform/getting-started/model-persona-prompt-templates.html) section, we will explain each of these features in detail. ----------------- ### Inference Window - C ### Inference Window ![Ask Sage Inference Window](/assets/images/asksage-platform-v2-inference-window.png) This section displays the text generated by the model. After each response, users will see additional questions or follow-up prompts to continue the conversation. **Quick Access:** You can access 'Copy', 'Save as DOCX', and 'Read aloud' located below the response generated. ![Prompt Response Quick Options](/assets/images/asksage-platform-v2-prompt-response-options.png) **Conversation Context:** The token badge in the bottom-right corner of the chat window opens the **Conversation Context** panel, showing how much of the current model's context window your conversation is using. This is not your token balance — see [Conversation Context](/docs/v2/asksage-platform/getting-started/conversation-context.html) for a full breakdown. ---------------- ### Chat History - D ### Chat History Management When users engage with models in Ask Sage Chat, their interactions occur within a chat session. All chat sessions are saved and listed under **Recents** in the sidebar, and can be accessed by users at a later time. Please note that the names of chat histories are automatically generated based on the initial prompt entered. ![Chat History Sidebar](/assets/images/asksage-platform-v2-chat-history.png) **Chat Search:** With the Chat Search Feature users can search based on chat titles to quickly find specific conversations. The search functionality operates on the context from the last 5 chats which are loaded in memory, allowing for fast and efficient retrieval of recent discussions. Users can copy an entire chat history, rename a chat session, share it with members from the same organization, and delete it if they no longer need it within the User Interface. These options are available via the three dots next to the chat session name. #### **Manage Chats** ![Manage chats dialog with search, select all, and delete selected](/assets/images/asksage-platform-v2-manage-chats.png) Click **Manage** above the Recents list to open the **Manage chats** dialog for bulk cleanup. Search for chats by title, use **Select all** or check individual chats, then click **Delete selected** to remove multiple chat sessions at once. **Privacy Notice:** The chat history can only be accessed by the user who created it. However, users can share their chat history with other members of the same organization. Users are not allowed to share their chat history with users from other organizations. **Best Practice:** Always initiate a new chat session when changing topics or contexts. Continuing a session with a different subject can hinder the model's ability to generate accurate results. Additionally, if you encounter issues with the model, starting a new chat session may help resolve them, as prior chat history could influence the model's responses. ---------------- ### Sidebar Menu - E ### Sidebar Menu - Platform Features ![Sidebar Menu Section E](/assets/images/asksage-platform-v2-side-bar-menu-section-e.png) In the sidebar menu, users can use the options to navigate the platform and access additional products paid subscriptions will have access to: - **New Chat** - Start a fresh conversation with a blank context - **Search** - Search across your chat history by title - **Chats** - The main user interface for interacting with Ask Sage Chat - **[Workbook](/docs/v2/workbook/workbook.html)** - Engage with GenAI models in a more intuitive manner - **Agents** - Create an Agent and a multi-step workflow - **Compare** - Evaluate and compare the outputs of different models - **Code Canvas** - Chat with an LLM to write code **Integrations:** Connecting Ask Sage to your IDE, terminal, and other platforms is now configured from [Account Settings → Integrations](/docs/v2/asksage-platform/getting-started/account-settings.html) rather than the sidebar. **Continuous Innovation:** We are constantly updating the platform and adding new products, so stay tuned for more exciting features and tools to come! ---------------- ### Sidebar Menu - F ### Sidebar Menu - Account & Support ![Sidebar Menu Section F](/assets/images/asksage-platform-v2-side-bar-menu-section-f.png) The bottom of the sidebar provides access to support and your account: **Learn More:** See the [Account Settings](/docs/v2/asksage-platform/getting-started/account-settings.html) section for a full walkthrough of each option. - **Settings** - Configure your account preferences and platform settings - **Dark Mode** - Toggle between dark and light interface themes - **Classic View** - Switch to the classic Ask Sage interface - **Help** - Access documentation, tutorials, and support resources - **Updates** - View the latest platform updates and release notes - **Disclosures** - Review important notices and compliance disclosures - **Log out** - Sign out of your Ask Sage account **Learn More:** In the following [Account Settings](/docs/v2/asksage-platform/getting-started/account-settings.html) section, we will explain each of these features in detail. ---------------- ## Summary ### What You've Learned Now that you have a better understanding of the **User Interface** components of the Ask Sage Platform, including the Prompt Tools, Prompt Window, Inference Window, Chat History, and Sidebar Menu features, you are equipped to navigate the platform effectively and leverage its powerful interface capabilities! **Next Steps:** Proceed to the next sections to learn more about Ask Sage and unlock advanced features! --- # Model, Persona, Prompt Templates, & Plugins Source: /docs/v2/asksage-platform/getting-started/model-persona-prompt-templates.html # Model, Persona, Prompt Templates, & Plugins Optimize your AI interactions by mastering model selection, personas, templates, and powerful plugins ![Ask Sage Hyperparameters Configuration Panel](/assets/images/asksage-platform-v2-hyperparamters.png) **Customization Power:** To optimize results for your specific use case, explore the different features available on Ask Sage. These features can be adjusted for each prompt, allowing you to fine-tune the model and generate the best possible outcomes. ---------------- ## Model ### Model Selection Select the model you want to use for the prompt. Because the Ask Sage Platform is agnostic you will have access to the latest models available today. By default, we have an `Auto` mode which automatically selects the best model for the prompt you are utilizing. **Auto Mode:** `Auto` is a great option for users who are unsure of which model to use, however, if you are familiar with the models and their capabilities, you can select the model you want to use for your prompt. Auto is marked **Recommended** in the model picker and routes to the newest model that fits your prompt's context window. An **Allow switching** toggle controls this behavior mid-conversation — when off, Auto stays on the model that answered your previous message instead of picking a new one for each reply. ![Ask Sage Model Selection Interface](/assets/images/asksage-platform-v2-model-selection.png) Having the ability to choose the model you want to use for your use case is a powerful feature Ask Sage provides. If you don't see the model you want to use or have a custom model, you can always reach out to the Ask Sage team to have it added. **Custom Models:** Enterprises/Users can request more models to be added, but additional charges may apply. Contact the Ask Sage team for more information at [support@asksage.ai](mailto:support@asksage.ai). Click **See All Models** (or a specific model's dropdown) to open the **Browse Models** dialog, where you can search by name, sort results, and use the filter option to narrow models by the following categories: **Capabilities** - **Reasoning** - Models that are optimized for reasoning tasks - **Vision** - Analyzes and understands images - **MCP** - Models that can utilize tools (Model Context Protocol) - **Image Generation** - Generates images based on text prompts - **Video Generation** - Generates a video based on text prompts - **CUI** - Sensitive-data compliant models (see [Model Security Guidelines](#model-security-guidelines)) - **Non-CUI** - Standard models not cleared for sensitive data - **ITAR** - Subject to International Traffic in Arms Regulations export controls - **EAR** - Subject to Export Administration Regulations export controls **Creator** - OpenAI, Anthropic, Google, Meta, X.AI, AWS **Model Cards:** Each model card in Browse Models also shows its provider, tier (`Flagship`, `Standard`, `Lightweight`, `Economy`, `Creative`, or `Heavy Thinking`), release date, and [context window](/docs/v2/asksage-platform/getting-started/conversation-context.html) size, alongside its capability badges and CUI/ITAR/EAR status. ----- ### Model Security Guidelines ### Security & Compliance #### **Sensitive Data Compliant Models (CUI*)** Models marked with an asterisk (*) are **CUI-compliant** and safe for sensitive data. The Ask Sage UI displays compliance status at the bottom of the prompt window. **Key Features:** - Your data is protected and never used for model training - Available to all users (no special credentials required) - Suitable for production use with sensitive information **CAC/PIV Access:** While anyone can use these models, only users with CAC/PIV authentication can apply CUI labels to datasets. Or if you do not have a CAC/PIV Card, you can request activation for CUI classification by emailing [support@asksage.ai](mailto:support@asksage.ai). (Access is not granted automatically and follow on instructions will be provided to you via email.) #### **Standard Models (Non-CUI)** Models without the asterisk are designed for research and testing only. These models are not found on all instances of Ask Sage. If you are on a CUI-compliant instance, these models will not be available. **Important Limitations:** - Not recommended for sensitive data - Data may be used for future model training - System blocks CUI dataset uploads to these models #### **Export-Controlled Models (ITAR / EAR)** Some model cards also carry **ITAR** and/or **EAR** badges alongside their CUI status. These flag models whose use is subject to U.S. export-control regulations, independent of whether the model is CUI-compliant. **ITAR:** International Traffic in Arms Regulations — governs defense-related technical data and services. A model badged ITAR may carry additional access restrictions tied to your organization's authorization. **EAR:** Export Administration Regulations — governs dual-use commercial and technical items. A model badged EAR may likewise be subject to organization-level access restrictions. **Filtering:** Both `ITAR` and `EAR` are filterable from the Browse Models Capabilities list, so you can quickly narrow to (or exclude) export-controlled models. A model can carry CUI, ITAR, and EAR badges simultaneously — for example, Claude 4.8 Opus and Gemini 2.5 Pro are marked CUI, ITAR, and EAR, while GPT-5.6 Sol is CUI only. Contact your org admin if you're unsure whether you're authorized to use an ITAR- or EAR-flagged model. ---------------- ## Persona ### Persona Selection Select the persona you want the model to use when interacting with it via the Persona selection option. By default, the persona is set to `Ask Sage`. A persona is a set of characteristics or rules that define the behavior and specific knowledge you want the model to focus on - think of it as guardrails. It's like choosing a character for the model to play or defining a specific role for the model to follow. Ask Sage provides an array of public personas to choose from, all accessible from the Personas panel. You can filter by All, Public, or Mine (your custom personas), search by name, and use the `Sort` control (e.g. `Name (A–Z)`) to change the ordering. ![Ask Sage Available Personas List](/assets/images/asksage-platform-v2-personas.png) ### Custom Persona ### Create Custom Personas Users can also create their own custom persona by selecting the `Create a New Persona` option. This allows users to define the characteristics and knowledge they want the GenAI model to focus on. ![Create New Persona Button](/assets/images/asksage-platform-v2-create-a-new-persona.png) Opening `+ Create Persona` launches a **3-step AI-assisted wizard** by default: **Wizard Steps:** 1. **Describe** - Write a plain-English description of the persona you want (example chips include *Legal reviewer*, *Technical writer*, *Customer support*), then click `Generate`. The AI drafts a name, description, and system prompt for you. 2. **Review & refine** - Read over the generated name, description, and system prompt, and edit anything that isn't quite right. 3. **Icon & save** - Choose or upload an icon, then save the persona. If you'd rather skip the AI assist, click **Start blank instead** from the wizard to drop into the classic form: **Quick Steps (Start blank instead):** 1. Open the `Personas` panel and click `+ Create Persona` (top right), then `Start blank instead` 2. Enter a `Name` and `Description` 3. Write your `System Prompt` - this defines the persona's behavior 4. Optionally upload a `Logo` (JPG or PNG) 5. Click `Create Persona` to save 6. Find your new persona under the `Mine` tab in the Personas panel **Field Limits:** | Field | Limit | | --- | --- | | Name | 70 characters max | | Description | 500 characters max | | System Prompt | 20 characters minimum | | Logo | JPG or PNG, 250KB max | #### Example: Data Science Expert Persona You are a seasoned Data Science Expert with a deep understanding of statistical modeling, machine learning techniques, and data-driven best practices. Your extensive expertise allows you to guide both the processes and technical implementations in data science projects with exceptional rigor and clarity. Proficient in multiple programming languages, including Python, R, C, and Matlab, you excel at providing robust code suggestions, detailed explanations, and troubleshooting support. Your responsibilities encompass mentoring data scientists, sharing industry-leading insights, and ensuring that data-driven solutions are both innovative and reliable. You consistently bridge the gap between advanced technical details and practical business applications, offering formal, clear, and methodically substantiated recommendations to both technical and non-technical audiences. **Pro Tip:** If you're not confident in crafting system prompts or writing effective prompts, don't worry! We offer a specialized persona for this purpose. The **Prompt Engineer** persona is an excellent choice for generating both prompts and system prompts. It harnesses the power of GenAI to assist you in creating the most effective prompts possible. ---------------- ## Prompt Library ### Prompt Library Ask Sage provides a set of `Prompt Library` that users can utilize to generate text. These templates are designed to help users get started with the platform and generate text based on a specific use case. ![Prompt Library Interface](/assets/images/asksage-platform-v2-prompt-template.png) **Filter Option:** There is a filter option that allows users to search for a group of prompt templates based on a specific `persona`. The panel also has `All` / `Public` / `Mine` tabs and a `Sort` control (e.g. `Name (A–Z)`), matching the Personas panel. ### Custom Prompt Templates ### Create Custom Templates Additionally, users can also create their own prompt templates by selecting the `Add Prompt` option. This allows users to define unique prompt templates that are relevant to their organization/operations. ![Add Custom Prompt Template Interface](/assets/images/asksage-platform-v2-prompt-template-custom.png) #### Example: DevSecOps Term Explanation Prompt Please provide a detailed explanation of the following DevSecOps term: **[User Input]**. The explanation should include the following sections: - **Definition:** Clearly define the term and spell out any abbreviations. - **Uniqueness:** Explain what makes this term unique or important in the context of DevSecOps. - **How it Works:** Describe how this term or concept functions within a DevSecOps framework. - **Use Cases and Examples:** Provide practical examples or use cases to illustrate the term. - **Memory Aids:** Include any techniques or phrases that can help students remember the information. (Also, ensure that any acronyms or abbreviations are spelled out to enhance user understanding.) **Getting Started:** If you're new, we recommend utilizing the `Prompt Engineer` persona to help you create the best prompt templates for your use case. ---------------- ## Plugins ### Extend Your Capabilities Ask Sage provides a growing library of plugins organized by category (Acquisition, Audio, Automation, Coding, and more) and filterable by Free or Paid. A `Sort` control (e.g. `Name (A–Z)`) is also available for ordering results. To explore all available plugins, open the Plugins panel from the prompt toolbar. --- # Data & Settings, Deep Agent, & MCP Source: /docs/v2/asksage-platform/getting-started/data-settings-deep-agent-mcp.html # Data & Settings, Deep Agent, & MCP Unlock advanced AI capabilities with datasets, intelligent agents, and powerful integrations ![Ask Sage Advanced Settings Panel](/assets/images/asksage-platform-v2-hyperparamters.png) **Advanced Features:** To optimize results for your specific use case, explore these advanced features available on Ask Sage. These capabilities can be adjusted for each prompt to generate the best possible outcomes. ---------------- ## Data & Settings ### Chat Toolbar All data and configuration options are accessible from the chat toolbar. Click the settings icon at the bottom of the chat window to open the toolbar, which consolidates the following controls in one place: - **Add photos and files** — Upload images or documents inline with your prompt - **Persona** — Quick-switch the active persona (displays the currently selected persona) - **Prompts** — Opens the Prompt Library - **Plugins** — Extend functionality with available plugins - **Datasets** — Select datasets to ground your prompt with your own data - **Web search** — Toggle real-time web search on or off - **Deep agent** — Enable advanced multi-step research across the web and your datasets - **Temperature** — Adjust response creativity from Precise to Creative - **MCP Tools** — View and manage active Model Context Protocol servers ### Ask Sage Datasets ### Dataset Selection & Management Datasets can be selected directly from the chat toolbar. Click **Datasets** to open the quick-select panel, where you can toggle individual datasets on or off using checkboxes, or use the `All`, `None`, or `Manage` tabs to control your selection in bulk. **Datasets Panel:** Click `Manage` to open the full Datasets panel. The left pane lists all your datasets — each showing the dataset name, classification badge, and file count. Click any dataset to browse its files in the right pane, where you can also **Share** the dataset or click **+ Add Files** to upload new content. Use **+ Add Dataset** at the top of the left pane to create a new dataset. **Learn More:** To learn more about creating datasets, please refer to the [Dataset](../dataset/dataset.md) section of the documentation. The dataset feature allows users to generate text from a specific dataset. This is important since GenAI models are trained on data that is locked in time and may not have the most up-to-date information. By selecting a dataset, you can ensure that the model generates text based on the most current information you want to reference. ![Ask Sage Dataset Selection Interface](/assets/images/asksage-platform-v2-dataset.png) #### **How Does it Work?** The dataset feature in Ask Sage Chat enables users to select one or multiple datasets. This process utilizes Retrieval-Augmented Generation (RAG) to extract the most relevant information from the chosen dataset(s) and generate responses based on that data. #### **What is RAG?** RAG enhances the GenAI process by retrieving pertinent external context and integrating it into the original prompt. This involves two key steps: 1. Retrieve Relevant Context Gather additional data related to the task → 2. Augment Prompt with Data Incorporate gathered information into the prompt **Unique Capability:** Users have the flexibility to create their own datasets within the platform. What sets Ask Sage apart is that it allows users to utilize their datasets with any model of their choice, ensuring that they are not confined to a specific model. **Data Classification:** When datasets are created, they can be classified as either `Unclassified` or `CUI`. Other tenants may offer additional classification options. **Note:** To utilize the `CUI` label, users must possess a CAC/PIV card or request activation for CUI classification if you do not have a CAC/PIV Card. To request this feature, please email [support@asksage.ai](mailto:support@asksage.ai). (Access is not granted automatically and follow on instructions will be provided to you via email.) **Performance Tip:** To optimize response generation time, we recommend selecting only the dataset(s) necessary for your prompt. If you do not need to reference any dataset, you can simply choose the `none` option. #### **Uploading Files to a Dataset** ![Ask Sage Dataset Selection Interface](/assets/images/asksage-platform-v2-dataset-upload.png) To add files to an existing dataset, open the Datasets panel, select the dataset, and click **+ Add Files**. The File Ingest panel will open on the right with a drag-and-drop area or a **Choose Files** button. **Upload Limits:** - Upload up to **15 files at a time** - Maximum file size: **50MB per file** ----------------- ### Web Search ### Real-Time Web Search Integration The `Web Search` feature is accessible from the chat toolbar as a simple toggle. By default, web search is set to `Off`. When enabled, it activates real-time web search and return up-to-date information in the inferences generated by the model. ![Ask Sage Live Web Search Toggle](/assets/images/asksage-platform-v2-live-function.png) **Security Notice:** The `Web Search` feature is not CUI/Sensitive data compliant as it is using a Search Engine to pull information from the web, and we can not control what information is being collected by the search engine. ---------------- ### Temperature ### Model Temperature Control The temperature slider is accessible from the chat toolbar. Drag the slider left toward **Precise** for more deterministic, consistent outputs, or right toward **Creative** for more varied and imaginative responses. By default, the temperature is set to `0.0`. A lower temperature produces structured, reliable answers suited for factual or analytical tasks. A higher temperature allows the model to explore a wider range of responses, which can be valuable for brainstorming or creative writing — though outputs may be less structured as a result. ![Ask Sage Temperature Control Slider](/assets/images/asksage-platform-v2-temperature.png) **Best Practice:** We recommend using a temperature of `0.0` for most use cases, as this will provide the most accurate and relevant results. However, if you are looking for more creative or varied responses, you can increase the temperature to `0.5` or `1.0`. ---------------- ## Deep Agent ### Deep Agent: Advanced Research AI **Deep Agent** is an AI agent capable of conducting searches across both the web and your secure datasets, including Retrieval-Augmented Generation (RAG) sources. Enable it from the chat toolbar using the **Deep agent** toggle. ![Deep Agent Settings](/assets/images/asksage-platform-v2-deepagent-settings.png) #### **How Deep Agent Works** Deep Agent leverages advanced AI agents to iteratively perform complex research tasks. It automatically generates queries and prompts, seamlessly exploring the web, your private datasets, or both. This capability enables users to uncover deeper insights and achieve higher productivity. ![Deep Agent Question](/assets/images/asksage-platform-v2-deepagent-question.png) ![Deep Agent Answer](/assets/images/asksage-platform-v2-deepagent-answer.png) **Ideal Use Case:** Deep Agent is ideal for users who need to combine public and private data sources for comprehensive research. Whether you're analyzing trends, generating reports, or solving complex problems, Deep Agent simplifies the process. #### **Token Usage Guidelines** Each Deep Agent query initiates multiple prompts, which can consume a significant number of tokens. To optimize your experience, select your models carefully. By default, Deep Agent uses the **GPT 4.1** model, which balances cost-effectiveness and performance. **Model Selection:** The **auto** model is great for most users. However, if you require higher precision or specific capabilities, you can select a different model from the available options. #### Token Consumption Example - A single Deep Agent query may generate **dozens of prompts**, depending on the complexity of the task. - For example, a query analyzing both web and RAG data might consume **500–1,000 tokens** per session. ---------------- ## Model Context Protocol (MCP) ### Model Context Protocol Integration The Model Context Protocol (MCP) is a powerful framework designed to enable seamless interaction between users and AI models. MCP provides a structured way to define, manage, and execute actions or tools within a given context. By leveraging MCP, users can extend the capabilities of AI models to perform specific tasks, automate workflows, and integrate external systems or APIs. MCP Tools are accessible directly from the chat toolbar. The toolbar entry shows the number of currently active MCP servers (e.g., `0 servers active`). Click it to view, configure, or connect MCP servers for your session. **Comprehensive Documentation:** To learn more about MCP, please refer to the [Model Context Protocol (MCP)](/docs/v2/mcp-documentation/mcp-documentation.html) documentation. --- # Account Settings Source: /docs/v2/asksage-platform/getting-started/account-settings.html # Account Settings Customize your interface, manage tokens, secure your account, and configure integrations all in one place ---------------- ## Settings Overview ### Accessing Settings Open Settings from the bottom of the left sidebar by clicking **Settings**. Settings are organized into eleven tabs in the left panel: - **Profile** — Personal info, custom intro prompt, and password - **Appearance** — Theme, timestamps, chat width, and display toggles - **Chat Defaults** — Default model, temperature, persona, and datasets - **Security** — MFA, CAC/Smart Card, and YubiKey registration - **API Keys** — Create and manage API keys - **Usage & Billing** — Token usage and subscription plan - **MCP Servers** — Add and manage Model Context Protocol servers - **Integrations** — Connect Google, GitHub, and Microsoft accounts - **Data & Privacy** — Review recent login history and jump to your prompt logs - **Widgets** — Opens the embeddable Widgets configuration page - **Prompt Logs** — Opens your prompt/response log history ---------------- ## Profile ### Profile Information Update your personal details including **First Name**, **Last Name**, **Company**, and **Phone**. Your email address is displayed but cannot be changed directly. **Email Address:** For security reasons, email addresses cannot be changed self-service. To update your email, contact the Ask Sage team at [support@asksage.ai](mailto:support@asksage.ai). #### **Custom Intro Prompt** The **Custom Intro Prompt** field (800 character limit) is added to the system prompt of every chat to personalize responses — tone, role, and preferences. It is saved to your account and applied to all new and existing conversations until you change or clear it. **Important:** Avoid including sensitive or mission-specific details in the Custom Intro Prompt — it will influence every response across all chats. Use **Clear prompt** to remove it at any time. #### **Change Password** Scroll down within the Profile tab to access the **Change Password** section and update your account password. ---------------- ## Appearance ### Display & Theme Options The Appearance tab controls how the Ask Sage interface looks and behaves. Most options are simple toggles; Chat Width is a multi-option selector. #### Dark Mode Switch between dark and light theme #### Show Timestamps Show timestamps on messages #### Auto Name Chats Automatically name chats based on the first message #### Expand Chat Names Show full chat names in the sidebar instead of truncated titles #### Show Classification Indicator Display the CUI/Unclassified badge near the chat input #### Inline Citation Chips Render numbered chips inline next to each cited claim. When off, citations only appear in the Sources section below the response #### Chat Width Choose **Standard**, **Wide**, or **Full** to control how wide the chat messages and input stretch across the screen ---------------- ## Chat Defaults ### Default Chat Configuration Chat Defaults set the starting configuration applied to every new conversation. Individual settings can still be overridden per-chat from the chat toolbar. #### Default Model The AI model used for new conversations. Select from all available models in the dropdown #### Temperature Controls randomness. Slide toward **Precise** for focused outputs or **Creative** for more varied responses #### Default Persona The persona applied to new conversations by default #### Default Datasets Datasets automatically included in new conversations #### Long Paste as Chip When on, large pastes collapse into a "Pasted" chip you can click to view or edit. Turn off to paste raw text directly into the input #### Allow Auto to Switch Models Mid-Conversation When on, Auto picks the best model for each message. When off, Auto picks a model on your first message and reuses it for the rest of the conversation ---------------- ## Security ### Security Login Features The Security tab lets you register additional authentication methods to protect your account. Three options are available: #### Multi-Factor Authentication (MFA) Add an extra layer of security with a time-based one-time password (TOTP). Click **Setup MFA** and use an authenticator app such as Microsoft Authenticator or Google Authenticator #### CAC / Smart Card Register your Common Access Card or smart card for certificate-based authentication. Automatically enables CUI dataset classification #### YubiKey / Security Key Register a YubiKey or other hardware security key for authentication. Click **Register** to add your device ---------------- ## API Keys ### API Key Management Generate and manage API keys for authenticating with the Ask Sage API. Enter a name in the **Enter API key name...** field, optionally restrict it to one or more scopes, and click **+ Create Key** to generate a new key. ![API Keys tab in Settings, showing the key name field, scopes dropdown, and Create Key button](/assets/images/account-settings-api-keys.png) Each key in the list shows a masked value and four action icons: - **Show** — Reveal the full key value - **Copy** — Copy the key to clipboard - **Revoke** — Disable the key without deleting it - **Delete** — Permanently remove the key #### API Key Scopes By default, a new key has **full access** to the Ask Sage API. To limit what a key can do, select one or more scopes before creating it — the key will only be able to call endpoints covered by the selected scopes. | Scope | Grants access to | | --- | --- | | `query` | Core chat and completion endpoints, such as `/query` and `/query_with_file` | | `plugins` | Plugin discovery and execution endpoints, such as `/get-plugins` and `/execute-plugin` | | `mcp` | MCP server management endpoints, such as adding, listing, and removing MCP servers | | `passthrough` | Ask Sage's OpenAI/Anthropic-compatible passthrough proxy, used when configuring Ask Sage as a custom model provider in third-party tools | | `agent_builder` | Triggering Agent Builder workflows programmatically via `POST /execute-agent` | **Tip:** Scopes can be combined on a single key. If no scopes are selected, the key keeps full access to every endpoint. **API Documentation:** Links to the full API Docs and your account domain are shown at the bottom of the API Keys tab. To learn more about using the Ask Sage API, visit: [Ask Sage API Documentation](/docs/v2/api-documentation/api-documentation.html) ---------------- ## Usage & Billing ### Token Usage & Subscription The Usage & Billing tab shows your current subscription plan, token reset date, and real-time token consumption with progress bars for each token type. #### Current Plan Displays your active subscription (e.g., **enterprise**) and the next token reset date. Click **Manage Subscription** to update your plan #### Inference Tokens Shows tokens used vs. total available for inference (prompt and response generation), with a progress bar and percentage used #### Training Tokens Shows tokens used vs. total available for training workloads, with a progress bar and percentage used **Enterprise Accounts:** If you are part of an enterprise account, contact your Ask Sage administrator to increase your token volume. To learn more about tokens, visit [Ask Sage Tokens](/docs/v2/asksage-tokens/asksage-tokens.html). To manage your subscription, visit [Subscription Management](/docs/v2/subscription-management/subscription-management.html). **Org-Pooled Tokens:** Some enterprise accounts draw from a shared organizational pool instead of per-user Inference/Training allowances. On these accounts, the Inference Tokens and Training Tokens cards above are replaced with a single notice: *"Your org manages token allocation — see your org admin for pool status. Personal monthly token limits do not apply."* The Current Plan card (plan name, reset date, Manage Subscription) still displays normally either way. ---------------- ## MCP Servers ### Model Context Protocol Servers The MCP Servers tab is where you add and manage Model Context Protocol servers that extend the AI with external tools and data sources. Click **+ Add Server** to configure a new MCP connection. **Security Warning:** MCP servers can access external systems. Only add servers you trust. Contact [support@asksage.ai](mailto:support@asksage.ai) if you have questions. **Learn More:** To learn more about MCPs and how to use them within Ask Sage, visit: [Model Context Protocols (MCPs)](/docs/v2/mcp-documentation/mcp-documentation.html) ---------------- ## Integrations ### Third-Party Integrations Connect external accounts to access files and services directly within Ask Sage. Click **Connect** next to any integration to authorize it: #### Google Connect your Google account for Drive and Calendar access #### GitHub Connect your GitHub account for repository access #### Microsoft Connect your Microsoft account for OneDrive and Teams access ---------------- ## Data & Privacy ### Data & Privacy #### **Recent Logins** A log of your recent login activity, showing the **Date & Time**, **Status** (Success or failure), and a **Comment** column for each login event. Use this to monitor for unexpected access to your account. A **View Prompt Logs** button at the bottom of the panel links to your prompt/response log history (see [Prompt Logs](#prompt-logs) below). ---------------- ## Widgets ### Embeddable Widgets The Widgets tab opens a separate page (indicated by the external-link icon) for configuring embeddable Ask Sage widgets, such as the SharePoint widget, that surface Ask Sage capabilities inside third-party tools. ---------------- ## Prompt Logs ### Prompt & Response Logs The Prompt Logs tab opens a separate page (indicated by the external-link icon) showing a history of your prompts and responses, useful for auditing past usage. ---------------- ### What You've Learned You now have a complete overview of the Ask Sage Settings panel — from personalizing your profile and appearance, to securing your account, managing API keys, monitoring token usage, and connecting external integrations. **Next Steps:** Proceed to the next sections to learn more about Ask Sage and unlock its full potential! --- # Conversation Context Source: /docs/v2/asksage-platform/getting-started/conversation-context.html # Conversation Context Understand the context window, read the Conversation Context panel, and know why long chats start to "forget" **The short version:** Every model can only hold a limited amount of content in view at once — that's its **context window**. The **Conversation Context** panel in Ask Sage Chat shows how much of that window your current conversation is using. This is *not* your Ask Sage token balance. ---------------- ## What Is a Context Window? ### The model's working memory A **context window** is the total amount of content a model can hold in view at once, measured in tokens. Tokens can represent not just text but also images, audio, tool calls, and system instructions — anything the model processes. Think of the context window as the model's working memory for a single conversation: everything the model needs to answer your question has to fit inside it, and anything that falls outside it is no longer accessible to the model unless it's stored elsewhere and pulled back in. Because models are **stateless between turns**, they don't remember your earlier messages on their own. A conversation appears to have memory only because the client resends the entire history — the system prompt, all prior turns, and your new message — with every turn. That's why long conversations grow slower and more expensive, and why they eventually hit the window's limit. **Tokens, briefly:** For text, a token is roughly 3.7 English characters — a bit under a word, so a 1,000-word document lands somewhere near 1,300 tokens. Other content types are converted to tokens too, at rates that vary by model and media type. See [Ask Sage Tokens](/docs/v2/asksage-tokens/asksage-tokens.html) for more. ---------------- ## The Conversation Context Panel ### Where to find it Ask Sage Chat shows a token badge in the **bottom-right corner** of the chat window. Click it to open the **Conversation Context** panel, which breaks down exactly how much of the model's context window your current conversation is consuming. What the badge opens depends on the model you've selected. Chat models show **Conversation Context**, described below. Image and video generation models show a simpler [Prompt Size](#image-and-video-models-the-prompt-size-panel) panel instead, because they have no conversation to track. ![Conversation Context panel showing model, window, reserve, budget, messages, and used tokens](/assets/images/asksage-platform-v2-conversation-context-modal.png) The panel's own summary says it plainly: *"How much of the model's context window this conversation is using. As you get close to 100% the oldest messages will be dropped."* ### Reading the Panel ### What each field means | Field | Example | What it means | | --- | --- | --- | | **MODEL** | `Auto → GPT-5.6 Luna` | The model the window belongs to. When you're on `Auto`, the arrow shows which model your request actually resolved to. Every number below follows that model, so they change if Auto routes elsewhere or you switch models mid-chat. | | **WINDOW** | `1,000,000 tok` | The resolved model's total context window — the hard ceiling on everything it can hold in view at once. | | **RESERVE** | `8,000 tok` | A fixed safety margin, held back on every model. `USED` is an estimate rather than an exact count, and the reserve is the cushion that absorbs the error — see [A note on the numbers](#a-note-on-the-numbers) below. | | **BUDGET** | `992,000 tok` | `WINDOW − RESERVE`. This is what's actually available to your conversation, and it's the number the percentage is measured against. | | **MESSAGES** | `2` | How many messages are currently being carried in context. Your prompt and the model's reply each count as one, so a single completed exchange shows `2`. Text still sitting unsent in the prompt box isn't a message yet and doesn't count here. | | **USED** | `55 tok` | An *estimate* of how many tokens the conversation is consuming, calculated in your browser rather than by the model. Read it as an approximate gauge — see [A note on the numbers](#a-note-on-the-numbers) below. | | **DRAFT** | `+2,000 tok` | What the message you're currently typing will add. It appears only when there's unsent text in the prompt box, and it's already folded into `USED` — so you can see a long prompt's cost *before* you commit to sending it. | | **Percentage bar** | `0.0%` | `USED` as a share of `BUDGET` — not of `WINDOW`. As this approaches 100%, the oldest messages start dropping out. | **Why the numbers change mid-chat:** The window belongs to the *model*, not the conversation. Switching from a 200K-token model to a 1M-token model changes `WINDOW` and `BUDGET` instantly, and the same conversation will show a much smaller percentage. With `Auto`, the **Allow switching** toggle controls whether Auto can re-route between turns — see [Model Selection](/docs/v2/asksage-platform/getting-started/model-persona-prompt-templates.html). ### A Note on the Numbers ### Why USED is an estimate, and what RESERVE is for There is no single, universal definition of a token. Every model family splits text into tokens slightly differently, so the same sentence genuinely costs a different number of tokens depending on which model is reading it. Ask Sage has to know how big your conversation is *before* it sends anything, and it can't run every model's tokenizer in your browser to find out. So it uses one deliberately conservative approximation for all models. The figure you see is a working estimate of the conversation's size, not an exact accounting of everything in the request. That's what `RESERVE` is for. It's a fixed 8,000-token margin, held back on every model, that covers the gap between the estimate and reality. Together they let Ask Sage manage the conversation on its own terms: - **Estimate high** — Assume the conversation is bigger than it probably is. - **Hold back a reserve** — Stop at `BUDGET` rather than at the model's true ceiling. - **Trim before sending** — When the conversation would exceed `BUDGET`, Ask Sage drops the oldest messages itself, on the way out. The point of the margin is to keep that trimming decision on the Ask Sage side, where it's predictable. If the estimate ran low and an oversized request reached the model, the drop would happen further downstream and with less control over what gets cut. **What this means in practice:** Treat the percentage as a gauge rather than a precise readout. It's the right number for spotting a conversation that's getting heavy, and the right prompt to start a fresh chat — just don't plan down to the last few percent, and give yourself room before a long or important task. ### Image and Video Models: the Prompt Size Panel ### A different panel for generated media Select an image or video generation model and the same badge opens a different panel: **Prompt Size**. Media models don't hold a conversation — each request stands alone — so there's no history to track and nothing to drop. What's limited is the length of the prompt itself. ![Prompt Size panel showing model, prompt limit, and prompt token count for an image generation model](/assets/images/asksage-platform-v2-prompt-size-modal.png) | Field | Example | What it means | | --- | --- | --- | | **MODEL** | `Nano Banana 2` | The media model your prompt will be sent to. | | **PROMPT LIMIT** | `32,768 tok` | The longest prompt this model accepts. This varies enormously between media models — Nano Banana 2 allows 32,768 tokens, while FLUX 2 Pro allows 1,024. Check the panel rather than assuming, especially when switching models. | | **PROMPT** | `11 tok` | How much of that limit your current prompt uses, updating live as you type. | | **Percentage bar** | `0.0%` | `PROMPT` as a share of `PROMPT LIMIT`. There's no reserve to subtract here. | **The generated media doesn't count:** As the panel says, the output is an image or video, not tokens — so it never counts against the prompt limit. Only the text you write does. This is the practical difference from a chat model, where the model's reply becomes history that eats into the next turn. **If you hit the limit:** Tighten the prompt rather than starting over. On a tight-limit model, a long, discursive description can run out of room at a length that would be unremarkable in chat — the panel is the quickest way to see how close you are before you send. ---------------- ## Context Window vs. Ask Sage Tokens ### Two different numbers, often confused This is the single most common point of confusion on the platform. They are unrelated limits that happen to both be measured in tokens. ### Context Window A **per-conversation** capacity set by the model you're using. - Resets to zero on every new chat - Costs nothing on its own - Changes when you change models - Shown in the Conversation Context panel ### Ask Sage Tokens Your **monthly plan allowance** — the platform currency you spend to run prompts. - Shared across all your chats - Depletes as you use the platform - Resets on the 1st of each month - Shown in Settings → Tokens **How they interact:** They're separate limits, but they pull on each other. Because the whole conversation is re-sent with every turn, a chat that's filled most of its context window sends a very large prompt each time you hit send — so it *spends* far more plan tokens per message than a fresh chat does. A long-running conversation gets more expensive the longer it runs, even when your latest message is one sentence. **Learn more:** See [Ask Sage Tokens](/docs/v2/asksage-tokens/asksage-tokens.html) for how inference and training tokens are billed, when they reset, and where to check your balance. ---------------- ## What Fills the Window ### Everything shares one budget It isn't just your messages. All of the following compete for the same space: - **Your prompt** — The question or instructions you type. - **Chat history** — Every prior turn in this conversation, yours and the model's, re-sent on each send. - **Attachments** — Files you attach to a prompt (up to 5 at a time). A handful of large PDFs can fill a small window on its own. - **Dataset chunks** — When a Dataset is attached, the retrieved passages are inserted into the prompt. - **Persona & prompt templates** — The instructions behind your selected Persona or template, sent with every turn. A long, detailed Persona takes up real room in the window. - **Plugins & MCP tools** — Enabled tool definitions occupy space before you ever call one, and each tool result adds more. - **The model's response** — Once written, it becomes part of the history carried into the next turn. **Rule of thumb:** If you attach five 40-page PDFs to a single prompt, you'll fill the context window of most models. Either choose a large-context model or ingest the documents into a [Dataset](/docs/v2/asksage-platform/dataset/dataset.html), where only the relevant chunks get retrieved. ---------------- ## What Happens When It Fills Up ### Why the model "forgets" As `USED` approaches `BUDGET`, Ask Sage starts **dropping the oldest messages** from what it sends, to make room for new ones. Nothing is deleted from your saved chat history — you can still scroll up and read the whole thing — but the dropped messages are no longer going to the model, so it can no longer see them. This is the explanation behind the most common complaint about long chats: - The model contradicts an instruction you gave it 40 messages ago. - It asks for information you already provided. - It loses track of a document you attached early in the conversation. - Answers get vaguer or drift off-topic the longer the chat runs. None of these mean the model is malfunctioning. They mean the earliest part of the conversation has aged out of the window. Checking the Conversation Context panel will usually confirm it — a high percentage is the tell. ---------------- ## Managing Your Context Window ### Practical steps - **Start a new chat when the topic changes** — The single most effective habit. A fresh chat starts at 0% and isn't carrying irrelevant history that both costs tokens and subtly influences answers. - **Switch to a larger-window model** — Every model card in **Browse Models** lists its context window size. Open the model picker and click **See All Models** to compare. - **Use Datasets instead of re-attaching files** — Ingest a reference document once, then query it. Only the relevant chunks enter the window rather than the whole file, every time. - **Turn off Plugins and MCP tools you aren't using** — Their definitions consume window space on every send whether or not you call them. - **Check the panel before a long task** — If you're about to attach a large document to an already-long chat, open the panel first. Starting fresh is cheaper than discovering mid-task that half your setup got dropped. **Best Practice:** Always start a new chat session when changing topics or contexts. Continuing a session with a different subject hinders the model's ability to generate accurate results. If a model starts misbehaving, starting a new chat session is also a good first debugging step — prior chat history may be influencing its responses. ---------------- ## Summary ### What You've Learned The **context window** is the model's working memory for a single conversation, and the **Conversation Context** panel in the bottom-right corner of the chat window shows how much of it you're using. `WINDOW` is the model's ceiling, `RESERVE` is a fixed safety margin that absorbs the imprecision in Ask Sage's token estimate, and `BUDGET` is what's left for your conversation. When usage nears 100%, the oldest messages are dropped — which is why long chats start to "forget." Most importantly: this is **not** your Ask Sage token balance. The context window is a per-conversation capacity that resets with every new chat; your tokens are a monthly plan allowance tracked in Settings. **Related:** [Ask Sage Tokens](/docs/v2/asksage-tokens/asksage-tokens.html) · [Model Selection](/docs/v2/asksage-platform/getting-started/model-persona-prompt-templates.html) · [Datasets](/docs/v2/asksage-platform/dataset/dataset.html) · [FAQs](/docs/v2/faq/faq.html) --- # Datasets Source: /docs/v2/asksage-platform/dataset/dataset.html # Ingesting Data into Ask Sage Transform your data into powerful AI insights with Ask Sage datasets. Ingest once, use everywhere across all GenAI models ![Data being ingested into Ask Sage platform](/assets/images/asksage-platform-v2-data-ingested.png) **Key Benefits:** - Ingest data in any format—text, images, audio—to generate tailored responses - Upload once, use across multiple GenAI models on the platform - Share datasets organization-wide for seamless collaboration ---------------- ## Understanding Datasets, Tokens, and Embeddings ### Understanding Datasets, Tokens, and Embeddings #### **Purpose of Ingesting Data into an Ask Sage Dataset** When users ingest data into an Ask Sage dataset, that information is stored and made available as a reference source. When a user submits a prompt, the platform automatically retrieves the most relevant content from the selected dataset(s) and combines it with the user's prompt. This enriched prompt is then sent to the AI model, enabling it to generate responses that are grounded in your specific data rather than relying solely on its general training knowledge. This approach is particularly advantageous for organizations seeking tailored responses based on their unique data and knowledge. This method, known as **Retrieval Augmented Generation (RAG)**, enhances GenAI models by incorporating external information. This results in more accurate and contextually relevant outputs. **Learn More:** For a deeper understanding of RAG, scroll to the bottom of this page where we explore how RAG functions and its applications within Ask Sage. #### **Ask Sage Training Tokens** Think of training tokens as a form of currency that allows you to input data into the platform. Each month, users receive a specific number of training tokens based on their subscription plan. When users ingest data into Ask Sage, the platform utilizes **training tokens** to convert that data into embeddings, which are then stored in an Ask Sage dataset. #### **Ask Sage Inference Tokens** Inference Tokens are the tokens consumed on the Ask Sage platform whenever you submit prompts, generate responses, use plugins/agents, or interact with any AI model to process text data and produce predictions or outputs. To view your available tokens, navigate to your name in the bottom left corner of the screen, then click on **Settings** and then **Usage & Billing**. Here, you will find the counts for both **Inference Tokens** and **Training Tokens** along with a percentage of usage. ![Usage & Billing Overview showing inference and training token counts](/assets/images/asksage-platform-v2-settings-token-volume.png) #### Inference Tokens Consumed when generating text using GenAI models on Ask Sage #### Training Tokens Required when ingesting data into a dataset on Ask Sage **Important:** Tokens reset at the beginning of each month and do not carry over to the next month. #### **What is a Token?** A token is a unit of text that the model processes, which can range from a single character to a whole word. For instance, the word "hello" is a single token, while the phrase "I love programming!" consists of five tokens: "I", "love", "programming", "!", and a space. When you ingest data into Ask Sage, the platform uses tokens to represent the text, converting it into a format that the model can understand. The more tokens you have, the more data you can ingest into an Ask Sage dataset and the more you can interact with AI models. #### **What is an Embedding?** An embedding is a numerical representation of data that captures its meaning in a way that a model can interpret. Essentially, embeddings transform complex data—such as text or images—into a format that allows algorithms to analyze it effectively. Tokens and embeddings are closely related: once the text is tokenized, each token is mapped to a corresponding embedding. This mapping allows the model to understand the relationships and meanings of the tokens in a more nuanced way, enabling it to generate relevant responses based on the ingested data. ---------------- ## Steps to Ingest Data into Ask Sage ### Steps to Ingest Data into Ask Sage #### **Create a Dataset** The first step is to create a `dataset` in Ask Sage. A `dataset` is equivalent to a folder where you can store all the data you want to ingest into Ask Sage. You can create multiple `datasets` to organize your data based on specific use cases or projects. To create a `dataset`, follow these steps: ![Ask Sage interface showing Prompt Tools, Data & Settings, and Upload New Files buttons](/assets/images/asksage-platform-v2-ingest-files-button.png) - Click the `Tools menu` button, then select `Datasets`. - Click on the `+ Add Dataset` button. Enter a dataset name. Only alphanumeric characters and hyphens are allowed. No spaces or special characters are allowed (e.g., `my-dataset12345`). - Classify the dataset as `Unclassified`, or `CUI` (Controlled Unclassified Information). - Click on the `Create Dataset` button. (If successful, you will see `Dataset created`) **CAC/PIV Card Access:** Users with a CAC/PIV card can label datasets as either `CUI` or `Unclassified`. Users without a CAC/PIV card are limited to labeling datasets as `Unclassified`. If you need to label a dataset as `CUI` but do not possess a CAC/PIV card, please contact Support at [support@asksage.ai](mailto:support@asksage.ai) for assistance. ![Dataset creation success confirmation](/assets/images/asksage-platform-v2-create-dataset-saving-2.png) After creating a `dataset`, you can now start ingesting data into Ask Sage. **Best Practices:** - Use a clear naming convention for your datasets to easily identify them when ingesting data - On your local machine, create a folder with the same name as the dataset you created in Ask Sage to help organize your data locally and easily upload it ---------------- ### Upload/Ingest Data **Warning:** Please refrain from ingesting data into Ask Sage [Workbooks](/docs/v2/workbook/workbook.html) through the dataset management page. Workbooks should only be managed via the Workbook user interface. Attempting to ingest data through the dataset management page will not be successful. ### Supported File Types After creating a `dataset`, you can now upload/ingest data into Ask Sage. You can ingest data in any format and as listed in the table below: | Data Type | File Format | Example | Max Size Per File | | --- | --- | --- | --- | | Text | .txt, .docx, .pdf, .pptx, .ppt, .csv, .cc, .sql, .cs, .hh, .c, .php, .js, .py, .html, .xml, .msg, .odt, .epub, .eml, .rtf, .doc, .json, .md, .tsv, .yaml, .yml, .java, .rb, .sh, .bat, .ps1 | `example.txt` | 50MB | | Image | .jpg, .jpeg, .png | `example.jpg` | 50MB | | Audio | .wav, .mp3, .mp4, .mpeg, .mpga, .m4a, .webm | `example.wav` | 500MB | | Compressed | .zip | `example.zip` | 50MB | | Spreadsheet | .xlsx, .tsv | `example.xlsx` | 50MB | | Presentation | .pptx, .ppt | `example.pptx` | 50MB | | Code | .cc, .sql, .cs, .hh, .c, .php, .js, .py, .java, .rb, .sh, .bat, .ps1 | `example.py` | 50MB | | E-book | .epub | `example.epub` | 50MB | | Email | .eml, .msg | `example.eml` | 50MB | | Rich Text | .rtf | `example.rtf` | 50MB | | Markup | .md, .html, .xml | `example.html` | 50MB | | Data Interchange | .json, .yaml, .yml | `example.json` | 50MB | **Note:** Be aware that images in text file documents will not be extracted. You will need to upload the images separately. **Additional File Types:** Ask Sage is capable of ingesting other file types as well. If you have any specific requirements, please reach out to the Ask Sage team for assistance at [support@asksage.ai](mailto:support@asksage.ai). ---------------- ### Upload Steps To upload data into Ask Sage, navigate to the `Datasets` section and follow these steps: 1. Select the dataset you created from the dropdown list. 2. Drag and drop the files you want to upload into the designated box under `File Ingest` on the right, or click `Choose files` to select from your local machine. 3. Once the files are selected, their names will appear in the box. Review the list to ensure accuracy, select the X next to `File Ingest` to clear the list. 4. Click the `Upload File(s)` button to begin the upload process. 5. If the upload is successful, it will display in the middle section of the dataset. ![Successful file ingestion](/assets/images/asksage-platform-v2-file-ingest-success.png) **Vector Embeddings:** The purpose of an Ask Sage dataset is to store embeddings rather than the original files. Consequently, the original files will not be included in the dataset. Instead, embeddings will be stored in a vector database optimized for rapid retrieval and search. This design enables the use of Ask Sage datasets with Retrieval Augmented Generation (RAG) to generate text based on the ingested data. **Tip:** Vector embedding databases, like those provided by Ask Sage, are not intended for ingesting large tabular data, such as spreadsheets. If you have tabular data and wish to utilize GenAI for analysis, you can simply attach the spreadsheet to your prompt by clicking on the `Tools menu` and then `Add photos and files`. Ask Sage will then use Python libraries to analyze the data and generate text based on that analysis. This approach allows you to effectively leverage GenAI for data analysis without the need to ingest the data into a dataset (or use Training tokens). ---------------- ## Using the Dataset with Ask Sage Models ### Using the Dataset with Any Ask Sage Models After ingesting data into an Ask Sage Dataset, you can now use the vector dataset with any of the GenAI models available on the platform. To use the data with the GenAI models, follow these steps: - Click the `Tools Menu` and then mouse over Datasets - Select the `dataset(s)` you want to reference/use when prompting questions. Note: You can select multiple datasets or all. ![Dataset selection interface showing available datasets](/assets/images/asksage-platform-v2-dataset-selection.png) - Update any other settings as needed (e.g., `Model`, `Persona`, `Temperature`, etc.) - Enter a prompt and click `send`. Here is an example of when a dataset is selected and used within Ask Sage: ![Ask Sage interface showing dataset being used in a prompt](/assets/images/asksage-platform-v2-pfc-example.png) The `dataset(s)` selected will appear under the prompt window so users can easily identify the dataset(s) used with the prompt. **Best Practice:** For optimal results with the ingested data, we recommend keeping the `Temperature` setting at its default value of `0.0` and ensuring that the `Live` setting is turned `off`. Incorrect settings may result in subpar outcomes or data contamination. **Warning:** The `Live` feature is not CUI compliant and cannot be used with CUI labeled datasets. ![Ask Sage explainability feature showing data sources](/assets/images/asksage-platform-v2-pfc-explanability.png) The inference/response generated by the GenAI model utilizes the dataset assigned to the prompt. **Explainability Feature:** Ask Sage users benefit from the `Show Explainability` feature, which provides users with a detailed reference to the data used to generate the text when using a `dataset` and/or the `live` feature. This is useful for understanding the context of the generated text and ensuring the text is relevant and not a hallucination. **Tip:** If you do not need to use an Ask Sage dataset, select `None` from the dropdown list. This will allow you to use the GenAI models without any dataset reference. This will also save inference tokens, as the model will not need to reference any dataset. ## How RAG Works ### How RAG Works ![RAG Flow Chart showing the retrieval and augmentation process](/assets/images/asksage-platform-v2-rag-flow-chart.png) Retrieval Augmented Generation (RAG) is a two-step process that enhances the capabilities of GenAI models by incorporating external information: 1. Retrieve Relevant Context The model identifies and retrieves information from a database or knowledge base that is pertinent to the user's query or task. This context provides essential background or specific details that may not be present in the model's training data. → 2. Augment Prompt with Retrieved Data The retrieved information is combined with the original user prompt. This enriched prompt is then fed into the GenAI model, enabling it to generate responses that are more accurate, contextually relevant, and informative. #### **Example** **User Prompt**: "What are the best practices for securing a web application?" 1. **Retrieve Relevant Context**: The RAG system searches a database and finds relevant articles, guidelines, and facts about web application security, such as: Use HTTPS to encrypt data in transit 2. Implement input validation to prevent injection attacks 3. Regularly update software dependencies to patch vulnerabilities 4. **Augment Prompt**: The system combines the original prompt with the retrieved information: 5. **Augmented Prompt**: "What are the best practices for securing a web application? Use HTTPS to encrypt data in transit, implement input validation to prevent injection attacks, and regularly update software dependencies to patch vulnerabilities." 6. **Generate Response**: The GenAI model processes the augmented prompt and generates a more informed response: 7. "Securing a web application involves several best practices. First, always use HTTPS to encrypt data in transit, ensuring that sensitive information is protected from eavesdroppers. Second, implement robust input validation to prevent injection attacks, such as SQL injection or cross-site scripting (XSS). Lastly, regularly update your software dependencies to patch known vulnerabilities and reduce the risk of exploitation." ### What You've Learned In this section, we guided you through the process of ingesting data into Ask Sage. Understanding this process is crucial to generating relevant and accurate results relevant to your work/organization. Now that you have a better understanding of how to ingest data into Ask Sage, you are ready to start utilizing the platform and leveraging the power of GenAI! **Next Steps:** Proceed to the next sections to learn more about Ask Sage and unlock its full potential! --- # Dataset Management Source: /docs/v2/asksage-platform/dataset/dataset-management.html # Dataset Management Organize, manage, and share datasets seamlessly across your organization with powerful collaboration tools ![Dataset management interface overview](/assets/images/asksage-platform-v2-data-management.png) ---------------- ## Manage Datasets ### Manage Datasets Ask Sage provides a user-friendly interface for effective dataset management. You can perform a variety of actions, including sharing, deleting, and copying data between datasets. To get started, click the `Tools menu`, then select the `Datasets` option. ![Manage Datasets interface showing available options](/assets/images/asksage-platform-v2-manage-datasets.png) **Warning:** DO NOT share or upload data sources in [Workbooks](/docs/v2/workbook/workbook.html) via the Dataset Management page. Workbooks should only be shared through the Workbook user interface. Attempting to share workbooks through the Dataset Management page will not be effective. #### **Share Dataset** In the `Manage Datasets` section, you can share datasets with other users in your organization. This feature enhances collaboration and allows team members to access and leverage the same datasets for their projects. To share a dataset, click on the share icon: ![Dataset share icon in the management interface](/assets/images/asksage-platform-v2-share-dataset-icon-2.png) ##### **Sharing with Specific Users** The `Share Dataset` section will display on the right, where you can enter the email addresses of the users you want to share the dataset with separated by a comma or new line. Please note that dataset sharing is contingent upon its classification as either `CUI` (Controlled Unclassified Information) or `Unclassified`. Only users with `CUI` access enabled on their accounts can view `CUI` datasets. If you attempt to share a `CUI` dataset with users lacking the necessary classification, you will encounter an error message. **CAC/PIV Card Access:** Users with a CAC/PIV card have the ability to label datasets as either `CUI` or `Unclassified`. However, users without a CAC/PIV card are restricted to labeling datasets as `Unclassified`. If you need to label a dataset as `CUI` but do not possess a CAC/PIV card, please reach out to Support at [support@asksage.ai](mailto:support@asksage.ai) for assistance. ![Share Dataset dialog window with email input fields](/assets/images/asksage-platform-v2-share-dataset-ui-2.png) Enter the email addresses of the user(s) you want to share the dataset with, select the type of permission you want them to have (Read, Edit, Admin) and click on the `Share` button. - Users can add an email one at a time in the text box or paste in a comma or new line separated list of email addresses. - More users can be added by repeating the above step. - Select the permission you want the users to have. - Lastly, click on the `Share` button to share the dataset with the selected users. - Dataset sharing is now complete. Users can access the shared dataset from their Ask Sage account. To unshare a dataset, click on the `X` icon next to the user's email address. **Note:** Datasets can only be modified by the owner of the dataset. Users with whom the dataset is shared can view the dataset but cannot make any changes to it. ##### **Permissions** When sharing a dataset, you can assign permissions to the users you are sharing the dataset with. The permissions include: #### Read User can query the dataset but cannot make changes or view contents #### Edit User can query the dataset and add more files to it #### Admin User can query, add files, and share the dataset with other users ##### **Sharing with All Users** To share a dataset with all users in your organization, click on the `Organization Sharing` button. The dataset will be shared with all users in your organization. ### Delete Dataset/Files **Note:** Only the owner of the dataset can delete the dataset or files within the dataset. To delete a `dataset` or `files` within a `dataset`, click on the `Delete` icon next to the dataset or file name. The dataset or file will be permanently deleted from Ask Sage. ---------------- ## Dataset Commands ### Dataset Commands Ask Sage provides a comprehensive set of commands to help you effectively manage and interact with your datasets. ![Dataset commands interface in Ask Sage](/assets/images/asksage-platform-v2-data-management-commands.png) **How to Use:** To access these commands, simply type the `/` character in the prompt field, which will display a list of available commands. Once you select a command, ensure you enter the dataset name exactly as it appears after the command. Example: `/add-dataset sample-dataset-2025` #### **List of Dataset Commands** | Index | Command | Description of Dataset Command | | --- | --- | --- | | 1 | /add-dataset | Creates a new dataset | | 2 | /delete-dataset | Deletes a dataset | | 3 | /stats-dataset | Get stats from a dataset (token count, character count, and files ingested) | | 4 | /assign-dataset | Assign a dataset to an email | | 5 | /deassign-dataset | Deassign a dataset from an email | | 6 | /get-datasets | Lists your datasets | | 7 | /train | Train text/plain content into dataset | | 8 | /get | Retrieves matching content from ALL your custom datasets in vector database | | 9 | /get-results-dataset | Retrieves all results from a specific dataset | | 10 | /get-files-dataset | Retrieves the names of files ingested in a specific dataset | | 11 | /delete | Deletes a training from your custom datasets in vector database | --- # Agent Builder Source: /docs/v2/agent-builder/agent-builder.html # Agent Builder Design and deploy sophisticated AI agents without code ---------------- ## Overview ### Build Powerful AI Agents Visually The Agent Builder is one of Ask Sage's most powerful features, enabling you to design and deploy sophisticated AI agents without writing a single line of code. Think of it as creating a specialized version of AI workers that can perform complex multi-step tasks, process data, and generate detailed reports, all directed by a visual workflow you create. ![Agent Builder canvas showing a completed multi-node workflow in Run mode with execution logs in the Activity panel](/assets/images/agent-builder-v2-hero.png) **No Code Required:** The Agent Builder provides a visual interface where you can drag and drop nodes to create complex workflows. Connect different components together to build agents that can automate tasks, analyze data, and make decisions based on your specific requirements. **Beta Feature:** The Agent Builder is currently in beta. New features and improvements are being added regularly. Check back often for updates to this guide. ---------------- ## What is the Agent Builder? ### Understanding Agent Workflows The Agent Builder is built around two distinct concepts that work together: an **Agent** is the persona that runs (name, system prompt, default model, agent-level variables), and a **Workflow** is the visual node graph the agent executes. Each Agent runs exactly one Workflow. Workflows are composed of nodes — discrete operations like LLM calls, decision routing, loops, file reads, or RAG ingestion — connected together to form a logical flow. ### Agents The persona configuration: who is running and how they behave - Name, description, system prompt - Default model and temperature - Agent-level variables ### Workflows The visual node graph the agent executes (up to 50 nodes) - Drag-and-drop canvas - 9+ node types across AI, Control Flow, Data - Exportable as JSON **Skip the blank canvas:** Start from a pre-built [Template](templates) or let [AI Assist](ai-assist) generate a workflow from a natural-language description. ---------------- ## The Main Dashboard: Your Command Center ### Dashboard Overview When you navigate to the Agent Builder, you land on the main dashboard. This is your central hub for creating, organizing, and launching agents. ![Agent Builder dashboard with Agents and Templates tabs](/assets/images/agent-builder-v2-dashboard-tabs.png) The Agent Builder dashboard with its tab navigation The dashboard is organized into two tabs: - **Agents** — every agent in your workspace, with quick actions to open, run, duplicate, or delete. Use the **New Agent** button to start a new agent. - **Workflows** — every workflow in your workspace, plus a gallery of pre-built [Templates](templates) (which are themselves just ready-to-use workflows you can copy as a starting point). A **Getting Started** panel on the dashboard surfaces three ways to begin a new workflow: - **Build with AI** — describe what you want and let [AI Assist](ai-assist) generate the workflow for you. - **Start from a template** — copy one of the pre-built [Templates](templates) as a starting point. - **Start blank** — open an empty canvas and build node-by-node. ---------------- ## Core Concepts: The Building Blocks of Logic ### Understanding the Fundamentals Understanding the core concepts of the Agent Builder is essential for creating effective workflows. The system is built around nodes, connections, and execution flows that determine how your agent processes information and makes decisions. 1. Add Nodes Select and place nodes on the canvas → 2. Connect Link nodes to create execution flow → 3. Configure Set parameters for each node → 4. Execute Run and test your workflow ---------------- ## Building Your First Agent: Step-by-Step ### Create Your First Workflow Creating your first agent is an exciting process. We'll guide you through each step, from initial setup to deployment. **Time Investment:** Your first workflow might take some time to build as you familiarize yourself with the interface. Start with simple workflows and gradually increase complexity as you gain confidence. ---------------- ## Detailed Node Reference ### Available Node Types The Agent Builder provides a variety of nodes that serve different purposes in your workflow. Each node type has specific capabilities and configuration options. **Node Categories:** Nodes are organized into categories such as Input/Output, Logic & Control, Data Processing, AI Operations, and Integrations. Browse through each category to discover the available options for your workflows. ---------------- ## Running, Testing, and Debugging ### Test and Debug Your Agents Testing and debugging your agents is crucial to ensure they perform as expected. Learn how to test workflows, interpret results, and troubleshoot issues. 1. Test Run Execute workflow with test data → 2. Review Results Analyze output and behavior → 3. Debug Issues Identify and fix problems ---------------- ## Advanced: Performance Optimization ### Optimize Your Workflows Once you're comfortable with basic agent creation, you can optimize your workflows for better performance, cost efficiency, and reliability. **Performance Tips:** Consider factors like node execution order, data caching, and token usage when optimizing your workflows. Small improvements can lead to significant gains in efficiency and cost savings. ---------------- ## Mastering Your Workflows ### Advanced Techniques Take your agent building skills to the next level by mastering advanced techniques, best practices, and workflow patterns. ### Conditional Logic Create dynamic workflows that adapt based on conditions - IF/THEN logic - Switch statements - Loop controls ### Integrations Connect your workflows to external systems and data sources - API connections - Database queries - File operations ---------------- ## Troubleshooting Guide ### Common Issues and Solutions Common issues and their solutions to help you resolve problems quickly and get your agents running smoothly. **Need Help?** If you encounter issues not covered in this guide, reach out to the Ask Sage support team at [support@asksage.ai](mailto:support@asksage.ai). We're here to help you succeed with the Agent Builder. ---------------- ## Explore the Documentation ### Dive Deeper into Agent Builder Explore comprehensive guides covering every aspect of the Agent Builder, from fundamental concepts to advanced techniques. [Core Concepts Master the building blocks of workflows and nodes →](core-concepts) [First Workflow Tutorial Build your first AI workflow in minutes →](first-workflow) [Workflows & Nodes Master workflow design and node catalog →](workflows-and-nodes) [AI Assist Generate and modify workflows from natural-language prompts →](ai-assist) [Templates Pre-built workflows you can copy and customize →](templates) [Use Cases & Examples Under Construction Real-world workflows and templates →](use-cases) [API & Integration Under Construction Programmatic access and integrations →](api-integration) [Advanced Techniques Under Construction Optimize and debug sophisticated workflows →](advanced-techniques) [Troubleshooting Solutions to common workflow issues →](troubleshooting) --- # Core Concepts Source: /docs/v2/agent-builder/core-concepts.html # Core Concepts Master the building blocks of workflows and nodes ---------------- ## Agents vs Workflows ### Two Concepts, One System Agent Builder distinguishes between an **Agent** (the persona that runs) and a **Workflow** (the visual logic the persona executes). One Agent runs exactly one Workflow. ### Agent The configurable persona - Name and description - System prompt - Default model and temperature - Agent-level variables ### Workflow The visual logic the agent runs - Directed graph of nodes - Up to 50 nodes per workflow - Edited on the canvas - Exported as JSON **Quick mental model:** Think of the Agent as *who* is running and the Workflow as *what* it does. The editor's **Agent** tab configures the persona; the canvas and **Palette** tab define the workflow. ---------------- ## What Are Workflows? ### Understanding Workflows A workflow is a visual representation of your agent's logic - a sequence of connected nodes that define how data flows and transforms through your agent. ### Key Characteristics - **Visual Design**: Workflows are created using a drag-and-drop canvas - **Node-Based**: Composed of individual nodes, each performing a specific function - **Data Flow**: Information flows from node to node through connections - **Reusable**: Workflows can be saved, shared, and reused ### Sharing Workflows While in-platform sharing is currently in development, you can share your workflow builds with others using the Import/Export functionality: - **Export**: Use the Import/Export button to download your workflow as a JSON file - **Share**: Send the exported JSON file to other users - **Import**: Recipients can use the Import/Export button to load your workflow into their Agent Builder ![Import/Export Workflow Interface](/assets/images/agent-builder-v2-importexport.png) Import/Export interface for sharing workflows **Coming Soon:** Native in-platform workflow sharing is under development, which will make it even easier to collaborate and share your builds with the community. ### Workflow Components ### Nodes Individual processing units - Perform specific tasks - Have inputs and outputs - Configurable parameters ### Connections Links between nodes - Define data flow direction - Pass data between nodes - Create execution order **Think of it this way:** A workflow is like a recipe - nodes are the steps, connections show the order, and data is the ingredients flowing through each step. ---------------- ## Understanding Nodes ### Node Fundamentals Nodes are the building blocks of workflows. Each node performs a specific operation and can be configured to meet your needs. ![Agent Builder Nodes Palette](/assets/images/agent-builder-v2-node-palette.png) Nodes palette with available node types ### Node Types Nodes are organized into categories based on their function: - **Input/Output**: Handle data entering and leaving the workflow - **Logic & Control**: Make decisions and control execution flow - **Data Processing**: Transform and manipulate data - **AI Operations**: Leverage AI models for intelligent processing - **Integration**: *(Coming Soon)* Connect to external systems and APIs. Currently, you can deploy agents and workflows outside of Ask Sage and integrate Ask Sage agents into other systems ### Node Structure Every node has: 1. **Input Ports**: Where data enters the node 2. **Output Ports**: Where processed data exits 3. **Configuration Panel**: Settings and parameters 4. **Status Indicator**: Shows execution state (available when running the workflow in agent mode) ### Node Properties - **Name**: Identify the node in your workflow - **Type**: Determines what the node does - **Parameters**: Configure the node's behavior - **Connections**: Links to other nodes **Node Reference:** For a complete catalog of all available node types, see the Node Reference section. ---------------- ## Connections and Data Flow ### How Data Flows Connections define how data moves through your workflow. Understanding data flow is crucial for building effective agents. ![Agent Builder Workflows](/assets/images/agent-builder-v2-workflows.png) Example of a workflow showing connections and data flow between nodes ### Connection Basics 1. Source Node Data originates from output port → 2. Connection Data travels along the connection → 3. Target Node Data arrives at input port ### Data Types Connections can carry different types of data: - **Text/String**: Textual information - **Number**: Numeric values - **Boolean**: True/false values - **Object**: Complex structured data - **Array**: Lists of items - **Any**: Flexible data type ### Connection Rules - Every workflow must have exactly one starter node - Workflows execute in a single direction from start to finish - Output types must match input types - Circular connections are not allowed (unless using loop nodes) - Disconnected nodes won't execute - No parallel processing - nodes execute sequentially in order **Type Matching:** Always ensure the output data type matches the expected input type. Use conversion nodes when needed. ---------------- ## Variables and Data Passing ### Working with Variables Variables allow you to store and reuse data throughout your workflow, making your agents more flexible and powerful. ![Agent Builder Output Save](/assets/images/agent-builder-v2-output-save.png) Saving output data to variables in the workflow ### Variable Basics - **Definition**: Named storage for data values - **Scope**: Can be workflow-wide or node-specific - **Types**: Support all data types (text, number, object, etc.) - **Reference**: Access variables from any node ### Using Variables 1. **Set Variables**: Store data for later use 2. **Get Variables**: Retrieve stored data 3. **Update Variables**: Modify existing values 4. **Delete Variables**: Remove when no longer needed ### Best Practices - Use descriptive variable names - Initialize variables before use - Clean up unused variables - Document complex variable usage **Naming Convention:** Use camelCase or snake_case for variable names (e.g., userInput, response_data). ---------------- ## Conditional Logic ### Making Decisions Conditional logic allows your workflow to make decisions and take different paths based on conditions. ![Agent Builder Conditional Logic](/assets/images/agent-builder-v2-conditional-logic.png) Example of conditional logic in a workflow ### Types of Conditional Nodes ### IF/THEN/ELSE Basic conditional branching - Test a condition - Two execution paths - Simple decision logic ### Switch Multiple path branching - Match multiple cases - Many execution paths - Default fallback option ### Common Conditions - **Comparison**: Equal, not equal, greater than, less than - **Logical**: AND, OR, NOT - **Existence**: Is null, is empty, exists - **Pattern**: Matches regex, contains text **Complex Logic:** Combine multiple conditional nodes to create sophisticated decision trees for your workflows. ---------------- ## Loops and Iterations ### Repeating Operations Loops allow you to repeat operations multiple times or process collections of data efficiently. ![Agent Builder Loop Example](/assets/images/agent-builder-v2-loop.png) Example of a loop in a workflow ### Loop Types 1. **For Each Loop**: Iterate over items in a collection 2. **Count Loop**: Repeat a specific number of times ### Loop Components - **Iteration Variable**: Current item being processed - **Loop Body**: Nodes executed on each iteration ### Best Practices - Avoid infinite loops - Process data in batches for large collections - Monitor performance with loops **Performance Tip:** Be cautious with loops in workflows - processing large collections can consume significant tokens and time. ---------------- ## Error Handling ### Handling Errors Gracefully Proper error handling ensures your workflows handle unexpected situations gracefully and provide useful feedback. ![Agent Builder Execution Logs](/assets/images/agent-builder-v2-execution-logs.png) Agents in the UI display execution logs showing how the workflow is operating, including error details and execution status for each node **Exporting Logs:** Logs can be exported in full or one section at a time as a Word document - see [Exporting Logs and Results](first-workflow) in the First Workflow tutorial. ### Error Handling Strategies 1. Try Attempt operation → 2. Catch Handle errors → 3. Finally Cleanup actions ### Error Types - **Validation Errors**: Invalid input data - **Connection Errors**: Network or API failures - **Processing Errors**: Node execution failures - **Timeout Errors**: Operations taking too long ### Recovery Options - **Retry**: Attempt the operation again - **Fallback**: Use alternative path or default value - **Log and Continue**: Record error and proceed - **Fail Gracefully**: Stop execution with informative message **Best Practice:** Always include error handling for external API calls and user input validation. ---------------- ## Execution Flow ### How Workflows Execute Understanding how workflows execute helps you design more efficient and predictable agents. ### Execution Order Workflows execute in a specific order: 1. **Start Nodes**: Nodes with no inputs execute first 2. **Sequential Execution**: Nodes execute when all inputs are ready 3. **Completion**: Workflow finishes when all paths complete ### Execution States - **Pending**: Waiting to execute - **Running**: Currently executing - **Success**: Completed successfully - **Failed**: Encountered an error - **Skipped**: Bypassed due to conditions ### Performance Considerations - **Token Usage**: AI operations consume tokens - **Execution Time**: Complex workflows take longer - **Resource Limits**: Stay within platform limits **Optimization:** For performance optimization techniques, see the Advanced Techniques section. ---------------- ## Best Practices ### Workflow Design Best Practices ### Design Principles 1. **Keep It Simple**: Start with simple workflows and add complexity gradually 2. **Modular Design**: Break complex workflows into reusable components 3. **Clear Naming**: Use descriptive names for nodes and variables 4. **Test Incrementally**: Test as you build, not just at the end ### Avoid Common Pitfalls - Don't create overly complex workflows - Don't skip error handling - Don't ignore data type mismatches - Don't forget to test edge cases - Don't create circular dependencies ### Organization Tips - Group related nodes together - Use consistent naming conventions - Keep workflows focused on single tasks - Create reusable sub-workflows **Learn More:** Check out the Building Workflows section for practical application of these concepts. ---------------- ## Next Steps ### Continue Learning Now that you understand the core concepts, explore these topics: [Workflows & Nodes Explore all available node types and their capabilities →](workflows-and-nodes) [First Workflow Tutorial Apply these concepts to build real workflows →](first-workflow) [Use Cases & Examples Under Construction See these concepts in action with real examples →](use-cases) --- # First Workflow Tutorial Source: /docs/v2/agent-builder/first-workflow.html # First Workflow Tutorial Build your first AI workflow in minutes ---------------- ---------------- ### Accessing the Agent Builder ### How to Access To access the Agent Builder feature: 1. Log In Sign in to your Ask Sage account → 2. Navigate Navigate to "Agents" in the sidebar → 3. Start Building Create your first workflow ![Agents Sidebar](/assets/images/agent-builder-v2-sidebar.png) Agents option in the sidebar **Prerequisites:** Make sure you have an active Ask Sage account with access to the Agent Builder feature. Some organizations may need to enable this feature first. ### Understanding the Interface ### Interface Overview The Agent Builder editor has two primary surfaces: a **side panel** on the left and the **workflow canvas** on the right. The side panel is organized into three tabs that you'll move between as you build: ### Palette tab Drag nodes onto the canvas - Browse all node types - AI Operations, Control Flow, Data ### Agent tab Configure the persona that will run this workflow - Name, system prompt, model - Temperature and variables ### AI Assist tab Generate or modify the workflow with natural language - Build from a description - Edit the current canvas ![Agent Builder editor showing side panel tabs and canvas](/assets/images/agent-builder-v2-editor-palette.png) The editor: side panel tabs (Palette / Agent / AI Assist) on the left, canvas on the right, node Inspector on the right when a node is selected **Want a shortcut?** Ask [AI Assist](ai-assist) to "Build a workflow that extracts key info from an uploaded RFP and generates a project plan," or browse the [Templates](templates) gallery for a related starting point like **Read and Summarize a File**. This tutorial still walks the manual path so you understand exactly what those shortcuts produce. ### Creating Your First Workflow ### Step-by-Step Tutorial Let's create an RFP/RFI Analysis workflow that extracts key information from solicitation documents and generates a comprehensive response plan: **Quick Import Option:** If you encounter any issues while following this tutorial, you can import the complete workflow by copying the JSON code at the [bottom of this page](#workflow-json-export) and using the Import feature in Agent Builder. This will create the entire workflow automatically. ![Create New Workflow](/assets/images/agent-builder-v2-create-new-workflow.png) Click the New Workflow button to get started #### Step 1: Create a New Workflow - Click the "New Workflow" button in the dashboard - Give your workflow a descriptive name (for this tutorial, we'll use "RFP-RFI Analysis and Response Plan") - Add a description: "This is a comprehensive AI-powered workflow designed to analyze Request for Proposal (RFP) or Request for Information (RFI) documents and generate a structured response plan." ![Workflow Name and Description](/assets/images/agent-builder-v2-name-description.png) Enter the workflow name and description **Note:** Starting a new workflow automatically sets the workflow to Edit status. Edit mode is required when building a new workflow or modifying an existing workflow. You'll switch to Run mode later when you're ready to test and execute your workflow. #### Step 2: Add the First LLM Node for Data Extraction - From the Node Palette, locate and drag an "LLM" node onto the canvas ![LLM Node Configuration](/assets/images/agent-builder-v2-workflow-example-llm-node.png) The right side panel is where you configure the settings for the node you are working on - Label it "rfi_rfp_data_extraction" - Set the model to "GPT-4.1-mini" and temperature to 0.2 for consistent extraction - In the **Attached Files (max 5)** section, configure "input.source_data_1" to accept the input document - Enter the following prompt template: Please conduct a comprehensive review of the provided solicitation document and extract the following critical information: **Primary Solicitation Details:** 1. **Solicitation Title** - Full official title and solicitation number 2. **Points of Contact (POCs)** - Names, titles, email addresses, and phone numbers for all listed contacts 3. **Contract Type** - (e.g., FFP, CPFF, T&M, IDIQ, etc.) 4. **Contractor Eligibility Requirements** - Including business size standards, certifications (e.g., 8(a), SDVOSB, HUBZone), registration requirements (SAM.gov, CAGE code), and any other qualifying criteria 5. **Scope of Work/Statement of Work** - Detailed description of required services or products 6. **Period of Performance** - Base period duration with specific start/end dates if provided 7. **Option Periods** - Number of option periods, duration of each, and conditions for exercise 8. **Submission Deadline** - Date and time (including time zone) for proposal submission 9. **Requiring Activity** - Agency, department, or office requesting the procurement 10. **Submission Requirements** - Required format, page limits, number of copies, electronic vs. hard copy, and any mandatory templates or forms 11. **Security Clearance Requirements** - Facility clearance level and personnel clearance levels required **Note:** There are other configuration options and settings available for LLM nodes, but they will not be covered within this example. For more advanced configurations, refer to the [Workflows & Nodes](workflows-and-nodes) documentation. #### Step 3: Add a Save Variable Node - Drag a "Save Variable" node onto the canvas to the right of the first LLM node - Label it "rfi_rfp_metadata" - In the source field, enter "rfi_rfp_data_extraction.response" - In the variable name field, enter "evaluation" - Connect the output of the first LLM node to the input of this Save Variable node ![Save Variable Node Configuration](/assets/images/agent-builder-v2-workflow-example-variable-node.png) Save Variable node storing the extraction results #### Step 4: Add a Second LLM Node for Questionnaire Analysis - Add another "LLM" node and label it "rfi_rfp_questionnaire" - Set the model to "GPT-4.1-mini" and temperature to 0.2 - In the **Attached Files (max 5)** section, configure "input.source_data_1" - Connect the output of "rfi_rfp_metadata" to this node's input - Enter the following prompt template: ![Second LLM Node Configuration](/assets/images/agent-builder-v2-workflow-example-llm-node-2.png) Workflow after Step 4 — second LLM node (`rfi_rfp_questionnaire`) added and connected downstream of the prior Save Variable node. 1. **Evaluation Criteria** - What factors will be used to evaluate proposals? (e.g., technical approach, past performance, price, small business participation) Include relative importance or weighting if specified. 2. **Mandatory Requirements** - What are the "go/no-go" compliance requirements that could result in proposal rejection? 3. **Key Milestones and Deliverables** - What are the critical delivery dates, performance milestones, and required deliverables throughout the contract period? 4. **Budget/Funding Information** - Is there an estimated contract value, ceiling amount, or funding limitation disclosed? #### Step 5: Add Another Save Variable Node - Add a "Save Variable" node labeled "rfi_rfp_analysis" - In the source field, enter "rfi_rfp_questionnaire.response" - Configure it to save the questionnaire response to a variable named "evaluation_questions" - Connect the output from the questionnaire LLM node #### Step 6: Add a Third LLM Node for Project Planning - Add a third "LLM" node labeled "rfi_rfp_project_plan" - Set the model to "google-claude-45-sonnet" for advanced planning capabilities - Set temperature to 1 for more creative planning output - In the **Attached Files (max 5)** section, configure "source_data_1" - Connect it to receive input from the previous Save Variable node - Enter the following prompt template: Create a comprehensive RFI/RFP project plan to respond to the opportunity and generate a Gantt chart. Use Today's date as the start. # Requirements: 1. **Include RFI/RFP project planning best practices and required milestones.** 2. **Incorporate the following teams in the process:** - **Green Team:** Focuses on pricing and financial aspects, ensuring competitiveness and alignment with the client's budget. Identifies potential cost concerns and suggests pricing strategy adjustments. - **Yellow Team:** Reviews the proposal for clarity and completeness, highlighting gaps in information, areas for improvement, and sections that may not fully meet RFP requirements. - **Red Team:** Acts as a critical review group, identifying major issues or non-compliance with RFP criteria that could impact the proposal's viability. {{evaluation}}, {{evaluation_questions}} **Important:** The prompt includes variable references `{{evaluation}}` and `{{evaluation_questions}}` at the end. These double curly braces reference data from earlier nodes, allowing the project plan to incorporate all previously extracted information. When you copy the prompt, these will be included correctly. #### Step 7: Add Final Save Variable - Add a "Save Variable" node labeled "RFI_RFP_Response_Timeline" - In the source field, enter "rfi_rfp_project_plan.response" - Configure it to save the project plan response to a variable named "project_plan" - Connect it to the project planning LLM node #### Step 8: Add a Return Response Node - From the Node Palette, drag a "Return Response" node onto the canvas - Label it "Return Response" - Configure the response template to output all three variables: {{evaluation}}, {{evaluation_questions}}, {{project_plan}} - Connect it to the final Save Variable node to complete the workflow ![Completed RFI/RFP Workflow](/assets/images/agent-builder-v2-workflow-example-final.png) Your completed workflow should look like this, with all nodes connected in sequence. The workflow is intentionally stacked vertically to make it clear and easy to see all components. **Time Estimate:** Your first workflow typically takes 15-20 minutes to create. You'll get faster with practice! ### Creating Your First Agent ### Agent Configuration Now that your workflow is complete, you need to configure the agent that will execute it. An agent is the persona — name, model, default behavior, and variables — that runs your workflow. Each workflow has exactly one agent. **Where to Find It:** Open the **Agent** tab in the editor's left side panel (the tab next to **Palette** and **AI Assist**). In Run mode, the side panel switches to the agent execution interface so you can submit input and see results. #### Configure Your Agent - Set the dropdown to **(New agent)** - In the **Name** field, enter: `RFI-RFP-Agent` - In the **Model** field, select: `GPT-4.1-mini` - In the **Temperature** field, enter: `0` - Click the **"+ Add Variable"** button - Change the type from **"Text"** to **"File"** - Update the key from `Key_1` to `source_data_1` - Click **"Save"** to save your agent configuration ![New Agent Configuration](/assets/images/agent-builder-v2-new-agent.png) Configure your new agent with the appropriate settings **Note:** The message variable can be ignored for this use case. It's an optional field that you can use for other workflows that require text-based instructions. **Customization Tip:** These configuration values can be modified to whatever you like based on your specific needs. Once your agent is created, you can simply select it from the dropdown menu for future workflows instead of creating a new agent each time. ### Running Your Workflow ### Testing and Execution Once your workflow is built and your agent is configured, follow these steps to execute your workflow: #### Step 1: Save Your Workflow Before running your workflow, make sure all your changes are saved. Click the **Save** button to preserve your workflow configuration, node connections, and agent settings. **Best Practice:** Get into the habit of saving frequently while building your workflow. This ensures you don't lose any progress if something unexpected happens. #### Step 2: Switch to Run Mode To execute your workflow, you need to switch from **Edit** mode to **Run** mode. Click the mode toggle to change from Edit to Run. In Run mode, the left panel transforms into the agent execution interface where you can interact with your workflow. ![Save, Edit, and Run Mode Controls](/assets/images/agent-builder-v2-save-edit-run-mode.png) Use the Save, Edit, and Run mode controls to manage your workflow execution #### Step 3: Select Your Agent Once in Run mode, ensure your agent is selected from the dropdown menu on the left side panel. If you just created your agent, it should already be selected. If you have multiple agents, choose the **RFI-RFP-Agent** that we configured earlier. ![Selecting the Agent](/assets/images/agent-builder-v2-execute-agent.png) Select your agent from the dropdown menu on the left side panel #### Step 4: Provide Input Data Your workflow is configured to accept a file as input (the `source_data_1` variable we set up). Click the **Attach file** button to upload an RFP or RFI document. This can be a PDF, Word document, or any text-based file containing solicitation information. **Tip:** For best results with this tutorial workflow, use an actual RFP or RFI document. The workflow is designed to extract specific information like solicitation details, points of contact, and submission requirements. #### Step 5: Run the Agent With your document attached, click the blue **Run Agent** button to execute the agent. The workflow will process through each node sequentially, extracting data, analyzing the questionnaire requirements, and generating a project plan. ![Adding Document and Running Agent](/assets/images/agent-builder-v2-run-agent.png) Attach your document and click the run button to execute the agent **Processing Time:** Depending on the complexity of your document and the models selected, execution may take 30 seconds to a few minutes. You'll see progress indicators as each node completes. #### Step 6: Review the Output Once execution completes, review the results in the execution logs on the right side panel. ##### Execution Logs (Right Side Panel) The right side panel displays the **Activity** log showing the execution progress, completion status, and final output for each workflow node: - **workflow_started** - Indicates the workflow has begun execution - **rfi_rfp_data_extraction** - Shows "Started" then "Completed" for the first LLM node - **rfi_rfp_metadata** - Variable assignment node status - **rfi_rfp_questionnaire** - Second LLM node execution status - **rfi_rfp_analysis** - Variable assignment for questionnaire results - **rfi_rfp_project_plan** - Third LLM node generating the project plan - **event** entries - Show detailed execution warnings or information about source data population Each node will show its status as "Started" and then "Completed" as the workflow progresses. You can also access **Previous Runs** from the dropdown at the top to review past execution logs. ![Activity Logs Panel](/assets/images/agent-builder-v2-activity-logs.png) The Activity log shows the execution progress and status of each workflow node **Detailed Execution Logs:** Click the **Expand** button at the top of the Activity panel, directly beneath the **Previous Runs** drop-down, to open the Execution Logs modal. This provides a comprehensive view of all execution details including input parameters, file information, timestamps, and complete JSON data for each step of your workflow. ![Expand button at the top of the Activity panel](/assets/images/agent-builder-v2-logs-expand-button.png) The Expand button sits at the top of the Activity panel, just below the Previous Runs drop-down ![Execution Logs Full View](/assets/images/agent-builder-v2-execution-logs-full-view.png) The Execution Logs modal provides detailed information about each workflow step ##### Exporting Logs and Results Once a run has finished and the Execution Logs modal is expanded, you can export what you see. There are two scopes to choose from: - **The complete log** - use the copy icon () or the DOCX icon in the modal header, at the top right. This captures every event in the run, including input parameters, token counts, and the full JSON for each node. - **A single section** - scroll to the section you want, such as an **Agent response**, and use that section's own copy and **Save to DOCX** controls in its header. This is the option to use when you only want the finished report and not the surrounding execution detail. ![Copy and Save to DOCX controls in the Execution Logs modal](/assets/images/agent-builder-v2-logs-export-icons.png) The modal header exports the whole log; each section carries its own copy and Save to DOCX controls ![Word document produced by the section export](/assets/images/agent-builder-v2-logs-docx-output.png) The section export produces a Word document containing only that section's content **Why DOCX:** The DOCX export preserves headings, tables, and formatting from the agent's response, so it is the best artifact to share with teammates or attach to a support request. See [Troubleshooting](troubleshooting) for what to include when contacting support. **Success Indicators:** Look for "Completed" status for each node in the Activity log to confirm successful execution. The final workflow output, including the extracted solicitation data, questionnaire analysis, and project plan, will be displayed in the Execution Logs. If you see errors or warnings, click on the event entries to view detailed error messages and refer to the [Troubleshooting](troubleshooting) section. ### Common Beginner Tips ### Best Practices for Beginners #### Start Simple - Begin with a 3-5 node workflow - Add complexity gradually as you learn - Test frequently as you build #### Use Templates - Browse the pre-built workflows on the dashboard and copy one to your workspace - Modify your copy to fit your needs - Use AI Assist to extend or restructure it from a description **Templates & AI Assist:** See [Templates](templates) for the full gallery and [AI Assist](ai-assist) for natural-language workflow authoring. #### Name Things Clearly - Give nodes descriptive names - Use clear workflow titles #### Save Often - Save your work regularly #### Test Incrementally - Test after adding each major component - Don't wait until the entire workflow is built - Fix issues immediately when they appear **Learning Resources:** Check out the [Use Cases & Examples](use-cases) section for real-world workflow templates you can learn from and adapt. ### Common Mistakes to Avoid ### What to Watch Out For #### Missing Connections - Every node needs proper input/output connections - Disconnected nodes won't execute - Check for loose or missing connections #### Incorrect Data Types - Ensure output types match input expectations - Use conversion nodes when needed #### Missing Required Parameters - Configure all required fields in each node - Workflows won't run with missing requirements **Need Help?** If you encounter errors, check the [Troubleshooting](troubleshooting) section for solutions to common problems. ---------------- ### Workflow JSON Export ### Import Example Workflow If you encounter any issues building the workflow or want to see how the complete workflow should look, you can import this example JSON directly into Agent Builder. Use the Import feature to load this configuration: #### RFP/RFI Analysis Workflow JSON This is the complete workflow configuration that matches the tutorial above. You can import this JSON to create the entire workflow automatically. ```json { "nodes": [ { "id": "a9aea009-de53-4856-8479-8350104f115e", "type": "llm", "position": { "x": 110.43673959206248, "y": -1319.9453248055145 }, "config": { "file_variables": "input.source_data_1", "is_terminal": false, "live_search": 0, "model": "gpt-4.1-mini", "persona": 1, "temperature": 0.2, "prompt_template": "Please conduct a comprehensive review of the provided solicitation document and extract the following critical information:\n\n**Primary Solicitation Details:**\n\n1. **Solicitation Title** - Full official title and solicitation number\n2. **Points of Contact (POCs)** - Names, titles, email addresses, and phone numbers for all listed contacts\n3. **Contract Type** - (e.g., FFP, CPFF, T&M, IDIQ, etc.)\n4. **Contractor Eligibility Requirements** - Including business size standards, certifications (e.g., 8(a), SDVOSB, HUBZone), registration requirements (SAM.gov, CAGE code), and any other qualifying criteria\n5. **Scope of Work/Statement of Work** - Detailed description of required services or products\n6. **Period of Performance** - Base period duration with specific start/end dates if provided\n7. **Option Periods** - Number of option periods, duration of each, and conditions for exercise\n8. **Submission Deadline** - Date and time (including time zone) for proposal submission\n9. **Requiring Activity** - Agency, department, or office requesting the procurement\n10. **Submission Requirements** - Required format, page limits, number of copies, electronic vs. hard copy, and any mandatory templates or forms\n11. **Security Clearance Requirements** - Facility clearance level and personnel clearance levels required\n" }, "label": "rfi_rfp_data_extraction", "key": "" }, { "id": "64e8c839-b3b4-4fcc-ac97-36ec2b9e793d", "type": "variable_assignment", "position": { "x": 353.7554690090619, "y": -1172.8723188257104 }, "config": { "source": "rfi_rfp_data_extraction.response", "variable_name": "evaluation" }, "label": "rfi_rfp_metadata", "key": "" }, { "id": "72d456c8-b0ef-4deb-82e7-454bb6282d48", "type": "llm", "position": { "x": 617.3576644281344, "y": -1174.5799904213595 }, "config": { "file_variables": "input.source_data_1", "is_terminal": false, "live_search": 0, "model": "gpt-4.1-mini", "persona": 1, "temperature": 0.2, "prompt_template": "1. **Evaluation Criteria** - What factors will be used to evaluate proposals? (e.g., technical approach, past performance, price, small business participation) Include relative importance or weighting if specified.\n2. **Mandatory Requirements** - What are the \"go/no-go\" compliance requirements that could result in proposal rejection?\n3. **Key Milestones and Deliverables** - What are the critical delivery dates, performance milestones, and required deliverables throughout the contract period?\n4. **Budget/Funding Information** - Is there an estimated contract value, ceiling amount, or funding limitation disclosed?" }, "label": "rfi_rfp_questionnaire", "key": "" }, { "id": "e1e1d0c2-97ae-46f2-96af-f13c6a09acf4", "type": "variable_assignment", "position": { "x": 853.9245138504396, "y": -1178.6502335700566 }, "config": { "source": "rfi_rfp_questionnaire.response", "variable_name": "evaluation_questions" }, "label": "rfi_rfp_analysis", "key": "" }, { "id": "e7a7d627-b597-40ee-9a6e-aa86d74cb588", "type": "flat_response", "position": { "x": 726.5549219248967, "y": -892.1963473527438 }, "config": { "response_type": "text", "response_template": "{{evaluation}},\n{{evaluation_questions}}, \n{{project_plan}}" }, "label": "Return Response", "key": "" }, { "id": "3684d9f8-edc6-4f52-bf22-3159b5dc412e", "type": "llm", "position": { "x": 1116.4845766441988, "y": -1176.5930556908138 }, "config": { "file_variables": "source_data_1", "is_terminal": false, "live_search": 0, "model": "google-claude-45-sonnet", "persona": 1, "temperature": 1, "prompt_template": "Create a comprehensive RFI/RFP project plan to respond to the opportunity and generate a Gantt chart. Use Today's date as the start.\n# Requirements:\n1. **Include RFI/RFP project planning best practices and required milestones.**\n2. **Incorporate the following teams in the process:**\n- **Green Team:** Focuses on pricing and financial aspects, ensuring competitiveness and alignment with the client's budget. Identifies potential cost concerns and suggests pricing strategy adjustments.\n- **Yellow Team:** Reviews the proposal for clarity and completeness, highlighting gaps in information, areas for improvement, and sections that may not fully meet RFP requirements.\n- **Red Team:** Acts as a critical review group, identifying major issues or non-compliance with RFP criteria that could impact the proposal's viability.\n\n{{evaluation}},\n{{evaluation_questions}}\n\n" }, "label": "rfi_rfp_project_plan", "key": "" }, { "id": "3c52f320-fd8b-4047-bd5d-85af3ead0950", "type": "variable_assignment", "position": { "x": 1325.8426686663436, "y": -1169.4092293140811 }, "config": { "source": "rfi_rfp_project_plan.response", "variable_name": "project_plan" }, "label": "RFI_RFP_Response_Timeline", "key": "" } ], "edges": [ { "id": "xy-edge__a9aea009-de53-4856-8479-8350104f115eout-64e8c839-b3b4-4fcc-ac97-36ec2b9e793din", "source": "a9aea009-de53-4856-8479-8350104f115e", "target": "64e8c839-b3b4-4fcc-ac97-36ec2b9e793d", "sourceHandle": "out", "targetHandle": "in" }, { "id": "xy-edge__72d456c8-b0ef-4deb-82e7-454bb6282d48out-e1e1d0c2-97ae-46f2-96af-f13c6a09acf4in", "source": "72d456c8-b0ef-4deb-82e7-454bb6282d48", "target": "e1e1d0c2-97ae-46f2-96af-f13c6a09acf4", "sourceHandle": "out", "targetHandle": "in" }, { "id": "xy-edge__64e8c839-b3b4-4fcc-ac97-36ec2b9e793dout-72d456c8-b0ef-4deb-82e7-454bb6282d48in", "source": "64e8c839-b3b4-4fcc-ac97-36ec2b9e793d", "target": "72d456c8-b0ef-4deb-82e7-454bb6282d48", "sourceHandle": "out", "targetHandle": "in" }, { "id": "xy-edge__e1e1d0c2-97ae-46f2-96af-f13c6a09acf4out-3684d9f8-edc6-4f52-bf22-3159b5dc412ein", "source": "e1e1d0c2-97ae-46f2-96af-f13c6a09acf4", "target": "3684d9f8-edc6-4f52-bf22-3159b5dc412e", "sourceHandle": "out", "targetHandle": "in" }, { "id": "xy-edge__3684d9f8-edc6-4f52-bf22-3159b5dc412eout-3c52f320-fd8b-4047-bd5d-85af3ead0950in", "source": "3684d9f8-edc6-4f52-bf22-3159b5dc412e", "target": "3c52f320-fd8b-4047-bd5d-85af3ead0950", "sourceHandle": "out", "targetHandle": "in" }, { "id": "xy-edge__3c52f320-fd8b-4047-bd5d-85af3ead0950out-e7a7d627-b597-40ee-9a6e-aa86d74cb588in", "source": "3c52f320-fd8b-4047-bd5d-85af3ead0950", "target": "e7a7d627-b597-40ee-9a6e-aa86d74cb588", "sourceHandle": "out", "targetHandle": "in" } ] } ``` **How to Import:** Copy the JSON above and use the Import feature in Agent Builder to load this workflow configuration. This will create all nodes and connections automatically. ---------------- ## Next Steps ### Continue Your Learning Journey Now that you've created your first workflow, explore these topics to deepen your knowledge: [Core Concepts Understand the fundamental principles behind workflows and nodes →](core-concepts) [Workflows & Nodes Learn advanced workflow building and explore the complete node catalog →](workflows-and-nodes) [Use Cases & Examples Under Construction See real-world examples and template workflows in action →](use-cases) --- # Workflows & Nodes Source: /docs/v2/agent-builder/workflows-and-nodes.html # Workflows & Nodes Master workflow design and node catalog **Living Documentation:** This page is actively maintained and updated as new node types and features are released. Last updated: May 2026 ---------------- ---------------- ## Node Catalog at a Glance ### All Available Nodes Quick overview of all node types in Agent Builder. Click any node to jump to its detailed documentation below. #### LLM Node AI-powered text generation, analysis, and vision processing type: llm AI Operations #### Decision Tree Node AI-powered classification and intelligent routing type: decision_tree AI Operations #### Return Response Node Final output delivery and workflow termination type: flat_response Control Flow #### If/Else Node Conditional branching based on boolean logic type: if_else Control Flow #### Loop Node Batch processing and iteration over collections type: loop Control Flow #### Save Variable Node Store data for use in downstream nodes type: variable_assignment Data #### Transform Variables Node Combine, extract, and reshape data type: variable_transform Data #### Read File Node Load file contents into a variable for downstream nodes type: read_file Data #### Train File Node Ingest a file into a RAG dataset for retrieval type: train_file AI Operations #### Train Array Node Ingest an array of text items into a RAG dataset type: train_array AI Operations #### Text to Speech Node Generate spoken audio from text using TTS models type: text_to_speech AI Operations ---------------- ## Node Reference ### Complete Node Catalog Nodes are the building blocks of Agent Builder workflows. Each node type performs a specific function, from calling AI models to controlling execution flow and managing data. Understanding these nodes is essential to designing effective workflows. Nodes are organized into three functional categories based on their primary purpose. Click any category below to explore the available node types. ### AI Operation Nodes ### AI Operation Nodes Leverage AI models for intelligent processing, content generation, and decision-making. #### LLM Node AI-powered text generation and analysis with multimodal capabilities - Text processing & generation - Document & image analysis - RAG & web search support - Data analysis (CSV/Excel) #### Decision Tree Node AI classification and intelligent multi-path routing - Intent detection - Content categorization - Confidence-based routing - Multi-category classification #### Train File Node Ingest files into a RAG dataset for retrieval - Upload to named dataset - Per-file context tags - Pairs with LLM RAG Datasets #### Train Array Node Bulk-index an array of text items into a RAG dataset - Array-based ingestion - Optional custom filename - Great for LLM-generated chunks #### Text to Speech Node Generate audio from text using OpenAI-style TTS models - Multiple voices - HD model option - Audio output variable **Quick Feature Comparison** | Feature | LLM Node | Decision Tree Node | | --- | --- | --- | | File Attachments | Yes (max 5 files) | No | | RAG Dataset Support | Yes | No | | Live Web Search | Yes | No | | MCP Tools | Yes | No | | Multiple Output Paths | No (single output) | Yes (per category) | | Classification Methods | N/A | LLM, Keyword, Regex | | Best For | Open-ended AI tasks | Structured routing & classification | #### LLM Node Calls a language model to generate text-based responses from prompts and file inputs. This is one of the most powerful and versatile nodes in Agent Builder. type: llm **Primary Use Cases:** - Document analysis and extraction - Question answering and information retrieval - Content generation and summarization - Natural language processing tasks **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **MCP Tools (Optional)**: Enable Model Context Protocol tools for this LLM call. Format: `{server_id: [[tool_name, require_approval], ...]}` - **Attached Files (max 5)**: File variables to attach (e.g., `{{input.source_data}}` or `input.document`). CSV/Excel files enable data analysis, images enable vision - **Terminal Node**: If true, return this LLM's response directly to user without further processing (toggle) - **Live Web Search**: Enable live web search to answer questions about recent events (dropdown: Live/disabled) - **Max Output Tokens**: Maximum tokens in the response. Model-specific limits apply - **Model**: Select the language model to use (e.g., Google Anthropic Claude 4.5 Opus, GPT-4.1-mini) - Required field - **Persona (Optional)**: Select a persona to guide the LLM's behavior and tone. Defaults to persona 1 if not specified - **Prompt**: Double-click to open editor. Use `{{variable}}` to reference previous node outputs. Example: `Process: {{input.message}}` - Required field - **RAG Datasets (Optional)**: Select datasets for retrieval-augmented generation to provide additional context - **System Prompt (Optional)**: Double-click to open editor. Instructions that set the behavior of the model - **Temperature**: Controls randomness. Lower = more deterministic, Higher = more creative **Input/Output:** - **Input**: Text prompts, variables from previous nodes, file attachments - **Output**: `[node_name].response` containing the generated text **Performance:** Use the Terminal Node toggle to return LLM responses directly to users without additional processing - this skips the need for a separate Return Response node. **Example Scenario:** Extract key information from an RFP document by providing the document as a file variable and a prompt like "Analyze this RFP and extract: 1) Project scope, 2) Budget, 3) Timeline, 4) Key requirements" **Learn More:** See the [First Workflow Tutorial](first-workflow) for a complete example of using LLM nodes to extract and analyze RFP documents. #### Decision Tree Node Classifies user input into predefined categories using AI-powered classification. Ideal for routing, intent detection, and categorization tasks. type: decision_tree **Primary Use Cases:** - Intent detection and request routing - Sentiment analysis and classification - Category assignment for incoming data - Multi-path workflow branching based on content **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Categories**: Click "Edit" to configure categories. Each category has: **Description**: Help the LLM understand this category - **Keywords (for keyword method)**: Keywords to match for classification - **Category Name**: Name of the category (used for output handles) - **Regex Pattern (for regex method)**: Regular expression pattern (e.g., `^urgent|URGENT$`) - **Classification Method**: Choose classification approach - Required field - **llm**: AI-based classification using language models - **keyword**: Simple pattern matching using keywords - **regex**: Regular expression-based pattern matching - **Confidence Threshold**: Minimum confidence to accept classification (0-1). Default: 0.7 - **Default Category**: Category to use if no match found - Required field - **Node Description**: Double-click to open editor. A general description of the classification task to help the LLM - **Input Variable**: Variable containing text to classify (e.g., `input.message`, `llm_1.response`) - Required field - **LLM Model (for llm method)**: Model to use for LLM-based classification (e.g., Google Anthropic Claude 4.5 Opus) **Input/Output:** - **Input**: Text input variable to classify - **Output**: Classification result (category name) and confidence score, with separate output handles for each category **Example Scenario:** Route customer support tickets by classifying them into categories like "Technical Issue", "Billing Question", "Feature Request", or "General Inquiry" #### Train File Node Ingests a file variable into an Ask Sage RAG dataset so it can be retrieved later by an LLM node's **RAG Datasets** setting. Use this to build or extend knowledge bases as part of a workflow. type: train_file **Primary Use Cases:** - Automated ingestion of uploaded documents into a dataset - Building per-user or per-tenant knowledge bases - Pre-processing pipelines that train on cleaned/extracted files **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **File Variable**: File to ingest (e.g., `input.document` or a file produced by an upstream node) - Required field - **Target Dataset**: Name of the RAG dataset to train into. The dataset is created if it does not already exist - Required field - **Context (Optional)**: Free-form text attached to the ingested file to improve retrieval relevance **Input/Output:** - **Input**: A file variable from `input.*` or an upstream node that produces a file - **Output**: Training status and the dataset name for downstream confirmation steps **Pairs With:** After a Train File node runs, reference the same dataset in an [LLM Node](#llm-node)'s *RAG Datasets* setting to query the newly ingested content. **Example Scenario:** A user uploads a policy PDF. The workflow uses Train File to ingest it into the `company_policies` dataset with a context tag like "HR policies, effective 2026-01-01", then a downstream LLM node answers questions against that dataset. #### Train Array Node Ingests an array of text items (for example, the output of an LLM that produced chunks, or a list extracted by a Loop) into a RAG dataset as a single trained artifact. type: train_array **Primary Use Cases:** - Indexing LLM-generated summaries or extracted snippets - Bulk-loading rows from a CSV or scraped list into RAG - Building synthetic knowledge bases from structured data **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Source Variable**: Variable containing the array of text items to ingest (e.g., `llm_1.response` or a Loop-aggregated variable) - Required field - **Target Dataset**: Name of the RAG dataset to train into - Required field - **Context (Optional)**: Free-form context tag applied to the ingested batch - **Filename (Optional)**: Custom filename used to label the ingested artifact in the dataset. Defaults to an auto-generated name **Input/Output:** - **Input**: Array variable from an upstream node - **Output**: Training status and the dataset name **Example Scenario:** An LLM node returns an array of FAQ entries generated from a knowledge dump. A Train Array node ingests that array into the `support_faq` dataset with filename `faq_2026Q2.txt`, making it immediately available to support-agent workflows. #### Text to Speech Node Converts text into spoken audio using an OpenAI-style TTS model. Produces an audio variable that can be returned to the user or passed to downstream nodes. type: text_to_speech **Primary Use Cases:** - Voice responses for accessibility - Generating narration for content workflows - Audio briefings and read-aloud summaries **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Text Variable**: Text content to synthesize (e.g., `{{llm_1.response}}` or a string literal) - Required field - **Model**: TTS model to use. Default: `tts-hd` - **Voice**: Voice preset. Default: `alloy` **Input/Output:** - **Input**: Text string from a previous node or variable - **Output**: Audio file accessible to downstream nodes (e.g., for return to the user) **Example Scenario:** After an LLM generates a meeting summary, a Text to Speech node produces an audio version using the `tts-hd` model and the `alloy` voice, which a Return Response node delivers to the user as a listenable briefing. ### Control Flow Nodes ### Control Flow Nodes Control the execution path of your workflow with conditionals, loops, and terminal responses. #### Return Response Node Final output delivery and workflow termination - Always ends execution - Template-based responses - JSON or text output - Metadata support #### If/Else Node Binary conditional branching - Boolean expressions - Two execution paths - Validation & error handling - Dynamic workflow logic #### Loop Node Batch processing and iteration - Array iteration - CSV file processing - Configurable limits - Row/column modes **Quick Feature Comparison** | Feature | Return Response | If/Else | Loop | | --- | --- | --- | --- | | Terminates Workflow | Always | No | No | | Output Paths | None (terminal) | 2 (if/else) | 1 (complete) | | Template Support | Yes | No | No | | Conditional Logic | No | Boolean expressions | No | | Iteration Support | No | No | Yes (arrays, CSV) | | Max Iterations | N/A | N/A | 1-1000 (default: 100) | | Best For | Final user output | Validation & branching | Batch processing | #### Return Response Node Returns a predefined response and terminates the workflow. This node ALWAYS ends workflow execution and is used to deliver the final output to users. type: flat_response **Primary Use Cases:** - Final answer delivery to users - Workflow termination with custom messages - Error message delivery **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Metadata (Optional)**: Additional metadata to include with the response (max 10KB). Click "Edit JSON" to configure - **Response Template**: Double-click to open editor. Use `{{variable}}` to include data from previous nodes. Example: `Hello {{user.name}}!` - Required field - **Response Type**: Format of the response (dropdown) - options: text, json **Input/Output:** - **Input**: Variables from previous nodes to include in the response - **Output**: Final workflow output delivered to the user **Special Note:** *This node is ALWAYS terminal* - it ends workflow execution. No nodes after a Return Response node will execute. **Example Scenario:** After analyzing a document and extracting metadata, use a Return Response node with a template like: "Analysis Complete! Summary: {{summary}}, Key Points: {{key_points}}" **Learn More:** See the [First Workflow Tutorial](first-workflow) for examples of using Return Response nodes to format final outputs. #### If/Else Node Branches workflow execution based on a boolean condition. Use this node to create conditional logic and handle different scenarios. type: if_else **Primary Use Cases:** - Validation checks and error handling - Conditional processing based on data values - Dynamic workflow paths - Quality gates and approval flows **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Condition**: Boolean expression using variables - Required field. Examples: `score > 80` - Numeric comparison - `category == 'urgent'` - String equality - `(x > 5 and y < 10) or z == 'yes'` - Complex logic **Input/Output:** - **Input**: Variables referenced in the condition expression - **Output**: Two execution paths - "if" handle (condition true) and "else" handle (condition false) **Syntax Note:** Reference variables directly without `{{}}` in conditions. Use `score > 80` not `{{score}} > 80`. Supports operators: `>`, `<`, `==`, `!=`, `and`, `or`. **Example Scenario:** Check if a confidence score is above 0.8: `confidence > 0.8`. If true, proceed with automated processing via the "if" output. If false, route to human review via the "else" output. #### Loop Node Iterates over data collections, executing downstream nodes for each item. Essential for batch processing and multi-item workflows. Supports both array iteration and CSV file processing. type: loop **Primary Use Cases:** - Batch processing of multiple documents - CSV file processing row-by-row - Multi-item analysis and aggregation - Repetitive operations on collections **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **CSV Delimiter**: Column separator for CSV data (default: ",") - **CSV Has Headers**: Whether first row contains column headers (toggle) - **CSV Iteration Mode**: How to iterate over CSV (dropdown) - options: rows, columns, specific row, or specific column - **CSV Row/Column Reference**: For row_ref/col_ref: column name, row index, or variable like `{{llm_1.column}}` - **Max Iterations**: Maximum items to process (1-1000). Default: 100 - **Source Type**: Type of data to parse (dropdown: auto) - 'auto' will detect based on content - **Source Variable**: Variable containing data to iterate (e.g., `input.file`, `llm_1.response`) - Required field **Input/Output:** - **Input**: Array, collection, or CSV file to iterate over - **Output**: "complete" handle triggers after all iterations finish, with aggregated results available **Performance Tip:** Set `max_iterations` carefully to balance thoroughness and execution time. Default is 100 items. For large datasets, consider filtering or sampling data before the loop. **Example Scenario:** Process a CSV file containing 50 customer reviews by looping over each row and extracting sentiment, key themes, and overall rating. The loop will process each row up to the max_iterations limit (100). ### Data Nodes ### Data Nodes Manage, transform, and pass data between nodes in your workflow. #### Save Variable Node Store node output for downstream use - Simple assignment - Named variables - Workflow-wide access - Data persistence #### Transform Variables Node Combine, extract, and reshape data - Template interpolation - JSON extraction - Array operations - Type casting #### Read File Node Load file contents into a workflow variable - Text, JSON, or line-by-line output - Works with any file variable - Feeds downstream LLM/Loop nodes **Quick Feature Comparison** | Feature | Save Variable | Transform Variables | | --- | --- | --- | | Primary Purpose | Simple storage | Data manipulation | | Operations | Assignment only | Template, extract, append, concat | | Template Support | No | Yes ({{variable}} syntax) | | JSON Extraction | No | Yes (JSON path) | | Array Operations | No | Yes (append, concat) | | Type Casting | No | Yes (string, number, boolean, etc.) | | Multiple Operations | One per node | Multiple transformations per node | | Best For | Storing raw outputs | Data formatting & reshaping | #### Save Variable Node Saves node output to a named variable for use in downstream nodes. Essential for passing data between workflow stages. type: variable_assignment **Primary Use Cases:** - Intermediate result storage - Data passing between workflow stages - Creating reusable data references - Building structured data objects **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Source**: Node output to save (e.g., `classifier_1.category`, `llm_1.response`) - Required field - **Variable Name**: Name for the new variable (letters, numbers, underscores only). Used to reference this value in downstream nodes - Required field **Input/Output:** - **Input**: Data from previous node's output - **Output**: Stored variable accessible throughout the workflow using `{{variable_name}}` syntax **Example Scenario:** After an LLM node extracts metadata from a document, use a Save Variable node to store it as `document_metadata`, then reference it later with `{{document_metadata}}` **Learn More:** See the [First Workflow Tutorial](first-workflow) for practical examples of storing and referencing variables in multi-stage workflows. #### Transform Variables Node Combines, extracts, or transforms data using template syntax. Perfect for data formatting, string manipulation, and JSON construction. type: variable_transform **Primary Use Cases:** - String concatenation and formatting - JSON object construction - Data type conversions - Template-based data transformation **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **Transformations**: Click "Edit" to configure transformation operations - Required field. Each transformation has: **Operation**: Choose transformation type (dropdown) - Required **template**: Use `{{variable}}` syntax for variable interpolation - **append**: Add value to end of target array - **extract_json**: Extract data from JSON using JSON path - **concat_array**: Concatenate multiple arrays together - **Template (for template op)**: Template string using `{{variable}}` syntax - **Value to Append (for append op)**: Value to add to array - **Target Array (for append op)**: Array to append value to - **Source Variable (for extract_json op)**: Variable containing JSON data - **JSON Path (for extract_json op)**: Path to extract from JSON - **Default Value (for extract_json op)**: Fallback if path not found - **Arrays to Concatenate (for concat_array op)**: Arrays to combine - **Type Cast (Optional)**: Convert output type - options: string, number, boolean, object, array - **Variable Name**: Name for the transformed result - Required **Input/Output:** - **Input**: Variables from previous nodes referenced in transformations - **Output**: New variables created by each transformation, accessible as `{{variable_name}}` **Template Syntax:** Use `{{variable}}` syntax in templates to reference any previous node output. Chain multiple transformations in a single node for complex data reshaping. **Example Scenarios:** - **Template:** Create formatted string: `Summary: {{llm_1.response}}, Status: Complete` - **Extract JSON:** Extract `$.user.email` from JSON response to get user email - **Append:** Add new item to existing results array for aggregation - **Concat Array:** Combine multiple result arrays into single output #### Read File Node Reads the contents of a file variable into a string, JSON object, or array of lines so it can be referenced by downstream nodes without re-attaching the file each time. type: read_file **Primary Use Cases:** - Loading text or JSON config files into the workflow - Splitting a file into lines for a Loop node - Pre-parsing input before passing structured data to an LLM **Configuration & Usage** **Key Parameters:** - **Label**: Display name for this node in the workflow canvas - **File Variable**: File to read (e.g., `input.document`) - Required field - **Output Format**: How to interpret the file contents - options: **text**: Raw string (default for plain-text files) - **json**: Parsed JSON object - **lines**: Array of lines, ideal for feeding a Loop node **Input/Output:** - **Input**: A file variable from `input.*` or an upstream node - **Output**: `[node_name].content` containing the parsed contents in the chosen format **Example Scenario:** Read an uploaded `.txt` changelog with **Output Format = lines**, then feed the resulting array into a Loop node that summarizes each line with an LLM before aggregating. ---------------- ## Choosing the Right Node ### Node Selection Decision Guide Not sure which node to use? This decision guide helps you quickly identify the right node for your specific task. | If you need to... | Use this node | Why | | --- | --- | --- | | Generate text, analyze documents, or process with AI | **[LLM Node](#llm-node)** | Most versatile AI node with support for vision, RAG, file attachments, and web search | | Classify input into categories and route accordingly | **[Decision Tree Node](#decision-tree-node)** | AI-powered multi-category classification with confidence scoring and multiple routing paths | | Return final results to the user | **[Return Response Node](#return-response-node)** | Always terminates workflow and delivers formatted output | | Create conditional logic based on values | **[If/Else Node](#if-else-node)** | Binary branching with boolean expressions for validation and decision-making | | Process multiple items or iterate over a collection | **[Loop Node](#loop-node)** | Batch processing for arrays, CSV files, and collections with configurable iteration modes | | Store data to reference later in the workflow | **[Save Variable Node](#save-variable-node)** | Simple variable assignment for passing data between workflow stages | | Combine, format, or reshape data | **[Transform Variables Node](#transform-variables-node)** | Powerful data manipulation with template syntax, JSON extraction, and array operations | | Load a file's contents into a variable | **[Read File Node](#read-file-node)** | Parses files as text, JSON, or lines so downstream nodes can work with the content directly | | Ingest a file into a RAG dataset | **[Train File Node](#train-file-node)** | Adds a file to a named dataset that LLM nodes can query via RAG Datasets | | Bulk-index an array of text into a dataset | **[Train Array Node](#train-array-node)** | Trains a RAG dataset from an array variable (e.g., LLM-generated chunks) | | Produce spoken audio from text | **[Text to Speech Node](#text-to-speech-node)** | Converts text into an audio variable using TTS models and selectable voices | **Pro Tip:** Most workflows use a combination of nodes. Start with your core processing needs (usually an LLM or Decision Tree), then add control flow and data nodes as needed. ---------------- ## Building Workflows ### Workflow Design Patterns **Note:** Refer to the [Node Reference](#node-reference) above for detailed documentation on each node type. Effective workflows combine multiple nodes to create powerful automated processes. Understanding how to select and connect nodes is key to building successful workflows. #### Node Selection Strategies When designing your workflow, consider these questions: - **What type of processing do you need?** Use AI Operation nodes for intelligent analysis, Control Flow nodes for logic, and Data nodes for storage - **Do you need conditional logic?** Use If/Else nodes for binary decisions, Decision Tree nodes for multi-category classification - **Are you processing multiple items?** Use Loop nodes for batch processing and iteration - **How will data flow between stages?** Use Save Variable nodes to pass data and Transform Variables nodes to reshape it #### Workflow Design Process 1 Identify Need → 2 Select Nodes → 3 Connect Flow → 4 Configure → 5 Test & Refine #### Common Workflow Patterns #### Sequential Processing Chain nodes together for step-by-step operations - Linear execution flow - Data passes between stages - Example: Input → LLM → Save → Response #### Conditional Branching Create different execution paths based on conditions - If/Else for binary decisions - Decision Tree for multi-path routing - Example: Classify → Route A or B #### Iterative Processing Process collections of items systematically - Loop nodes for batch operations - Process each item individually - Example: Loop → LLM → Aggregate #### Multi-Stage Analysis Combine multiple AI operations for complex tasks - Multiple LLM nodes - Variable storage between stages - Example: Extract → Analyze → Summarize #### Best Practices **Start Simple:** Build your workflow incrementally. Begin with the core functionality and add complexity only as needed. Test each stage before connecting to the next. **Naming Convention:** Use descriptive, meaningful variable names that clearly indicate their purpose. Good: `customer_email`, `extracted_summary`. Avoid: `var1`, `temp`. **Error Handling:** Consider edge cases and add error handling with If/Else nodes. Validate data before expensive operations and provide fallback paths for unexpected inputs. #### Performance Optimization **Minimize Variables:** Only save data you'll actually reuse. Unnecessary variable assignments add complexity without benefit. **Early Filtering:** Place conditional checks and validation early in your workflow to avoid unnecessary processing of invalid data. **Prepare Data First:** Use Transform Variables nodes to format and prepare data before expensive LLM calls. Clean, well-formatted inputs produce better results. **Next Steps:** Ready to build your first workflow? Check out the [First Workflow Tutorial](first-workflow) for step-by-step guidance on creating an RFP analysis workflow. ---------------- ## Additional Resources ### Learn More Explore these related resources to deepen your understanding of Agent Builder: [Core Concepts Understand the fundamental principles of workflows and nodes →](core-concepts) [First Workflow Tutorial Build your first workflow with step-by-step guidance →](first-workflow) [Use Cases & Examples Under Construction Learn from real-world workflow implementations →](use-cases) --- # Templates Source: /docs/v2/agent-builder/templates.html # Templates Pre-built workflows you can copy and customize ---------------- ## What Are Templates? ### Reusable Starting Points Templates are **pre-built workflows** curated by Ask Sage. They aren't a separate concept from workflows — they're regular workflows that ship as starting points so you can skip the blank canvas and start customizing immediately. Everything is editable after you pick one — nodes, prompts, and models. ![Agent Builder Template Gallery](/assets/images/agent-builder-v2-template-gallery.png) The "Start from a template" gallery, opened from the Getting Started panel on the Agent Builder dashboard ---------------- ## Using a Template ### Copy in Three Steps 1. From the Agent Builder dashboard, click **Start from a template** in the Getting Started panel to open the template gallery. 2. Pick a starter workflow that matches your use case. 3. The template is copied into a new workflow in your workspace. Open it in the editor, configure the persona on the **Agent** tab, and edit nodes directly on the canvas. **Your copy is independent:** Editing your copy never affects the original template, and template updates do not propagate to copies you've already made. ---------------- ## Available Templates ### Gallery Overview The template gallery is updated regularly. The list below reflects the current set; open **Start from a template** from the dashboard for the latest additions. ### Simple QA *Beginner* — A single LLM call that answers the user prompt and returns the response. - Smallest viable workflow - Good for prompt iteration - Easy to extend ### Read and Summarize a File *Files* — Read an uploaded file, summarize the contents with an LLM, then return the summary. - Read File + LLM - Returns a clean summary - Works with PDFs, docs, text ### Train a Dataset for RAG *RAG* — Ingest an uploaded file into a dataset so it can be retrieved by future agents. - Read File + Train File - Builds a knowledge base - Pairs with LLM RAG queries ### If-Else Routing *Logic* — Classify the user intent then send the request down one of two LLM branches. - Decision Tree classification - Two downstream LLM paths - Pattern for triage and routing ### Multi-step Research *Advanced* — Refine the user question, then synthesize a researched answer in a second LLM pass. - Two-stage LLM reasoning - Question refinement first - Synthesized final answer **Don't see what you need?** Start from **Simple QA** or use [AI Assist](ai-assist) to generate a workflow from a description, then refine on the canvas. ---------------- ## Related Pages ### Learn More [First Workflow Tutorial Build the RFP analyzer manually to understand what the template ships with →](first-workflow) [AI Assist Generate a workflow from a natural-language description →](ai-assist) [Workflows & Nodes Reference for every node you'll see inside a template →](workflows-and-nodes) --- # AI Assist Source: /docs/v2/agent-builder/ai-assist.html # AI Assist Generate, refine, and explain workflows with natural language ---------------- ## What Is AI Assist? ### An AI Co-Pilot for the Canvas AI Assist is a side-panel chat surface inside the Agent Builder editor. It can **generate new workflows from a natural-language description**, **add or modify nodes on the current canvas**, and **explain** what an existing workflow does — all without manually dragging nodes from the palette. ![Agent Builder AI Assist panel](/assets/images/agent-builder-v2-ai-assist.png) AI Assist tab in the editor side panel ---------------- ## Opening AI Assist ### Where to Find It AI Assist lives in the editor's left-hand side panel alongside the node Palette and the Agent settings. 1. Open any agent in the editor (from the dashboard, click **New Agent** or open an existing one). 2. In the left side panel, click the **AI Assist** tab. 3. Type a prompt at the bottom of the panel and submit. **Side-panel tabs:** The editor's side panel exposes three tabs — **Palette** (drag nodes onto the canvas), **Agent** (persona settings: name, system prompt, model, temperature, variables), and **AI Assist** (this feature). ---------------- ## What You Can Ask For ### Common Prompts ### Generate Create a new workflow from scratch - "Build me a workflow that summarizes uploaded PDFs" - "Create a support ticket triage agent" ### Modify Edit the current canvas - "Add a Decision Tree to route urgent vs normal" - "Wire the LLM output into a Return Response node" ### Explain Understand an existing workflow - "Walk me through what this workflow does" - "Why is this node disconnected?" ---------------- ## Working Effectively with AI Assist ### Prompting Tips - **Be specific about inputs and outputs.** "Take an uploaded CSV and return a summary email" is much easier to act on than "make a CSV agent". - **Name the nodes you want.** If you already know the node type (LLM, Loop, Decision Tree, Train File, etc.), reference it by name. - **Iterate.** Start with a rough generation, then ask follow-ups like "replace the Decision Tree with an If/Else on `confidence > 0.8`". - **Review every change.** AI Assist edits the canvas directly. Inspect the node graph and parameters before saving or running. **Always verify:** AI Assist is a productivity accelerator, not a substitute for review. Confirm node configurations (especially file variables, model selection, and prompts) before running an agent in production. ---------------- ## Related Pages ### Learn More [Workflows & Nodes Reference for every node AI Assist can place on the canvas →](workflows-and-nodes) [First Workflow Tutorial Build a workflow manually to understand what AI Assist generates →](first-workflow) [Templates Start from a pre-built workflow instead of generating one from scratch →](templates) --- # Use Cases & Examples Source: /docs/v2/agent-builder/use-cases.html # Use Cases & Examples Real-world workflows and templates you can download and use today ---------------- ---------------- Each example below is fully documented, includes sample outputs, and ships with a downloadable JSON template you can import directly into Agent Builder. More examples are added regularly. Template Workflows ### PowerPoint Generator Transform source documents into professional, presentation-ready PowerPoint files — automatically. This multi-step workflow extracts key content from your uploaded documents, suggests enhancements, builds a detailed slide-by-slide outline, and generates downloadable PowerPoint code — all in a single run. 8 Nodes 4 LLM Steps ~10 min runtime Accepts file uploads [How It Works](#pptx-how-it-works) · [Workflow](#pptx-workflow) · [Sample Output](#pptx-sample-output) [Download Workflow Template](/assets/downloads/agent-builder/powerpoint_gen_template.json) Import via the Agent Builder's **Import/Export** menu — sets up the full workflow and agent configuration automatically ### How It Works The workflow chains together four AI-powered stages, each building on the last: 1. **Extract Source Content** Analyzes your uploaded documents to pull out key themes, data points, stakeholder quotes, and visual opportunities. 2. **Suggest Enhancements** Reviews the extracted content and recommends structural improvements, missing information, and audience-specific adjustments. 3. **Generate Outline** Creates a detailed slide-by-slide outline with headers, key points, speaker notes, and visual element descriptions. 4. **Generate PowerPoint** Produces PptxGenJS code that renders into a polished, downloadable `.pptx` file with professional formatting. ### Workflow Overview Below is the full node flow inside the Agent Builder. Each node passes its output to the next, creating a seamless pipeline from raw documents to finished slides. ![PowerPoint Generator workflow showing 8 connected nodes: Extract Content, Save, Suggest Enhancements, Save, Generate Outline, Save, Generate PPTX Code, and Return Response](/assets/images/agent-builder-v2-pptx-workflow.png) ### Sample Output Here is an example presentation generated from a cybersecurity posture review — the workflow produced a complete 12-slide briefing deck with data visualizations, executive summaries, and a Zero Trust roadmap, all from source documents alone. ![Generated title slide — Cybersecurity Posture Review Q1 FY2026](/assets/images/agent-builder-v2-pptx-slide-title.png) ![Generated agenda slide showing 8 briefing sections](/assets/images/agent-builder-v2-pptx-slide-agenda.png) ![Generated threat landscape slide with vector breakdown and incident details](/assets/images/agent-builder-v2-pptx-slide-threats.png) ![Generated Zero Trust Architecture roadmap slide](/assets/images/agent-builder-v2-pptx-slide-zerotrust.png) ### Presentation Guide In addition to the slides, the workflow returns a comprehensive guide with enhancement suggestions, a full slide outline, and next steps — giving you everything you need to review and customize the final product. ![PowerPoint Generator output guide showing enhancement suggestions and presentation structure](/assets/images/agent-builder-v2-pptx-guide.png) ### Customizable Inputs The workflow accepts several variables you can tailor to your needs: | Variable | Description | Example | | --- | --- | --- | | `source_documents` | Upload the files you want to turn into a presentation | PDF reports, Word docs, text files | | `presentation_topic` | The subject of your presentation (or leave blank to auto-detect) | Cybersecurity Posture Review — Q1 FY2026 | | `audience_context` | Who will be viewing the presentation | Senior leadership and ISSO community | | `slide_count` | Target number of slides | 12 | | `style_preferences` | Color scheme, fonts, and design direction | Navy blue (#003366), gold accent, minimal design | | `additional_instructions` | Any extra guidance for the AI | Include a Zero Trust slide; end with Decisions Required | ### CSV Data Query Turn raw spreadsheet data into actionable insights — row by row. This workflow loops through every row of an uploaded CSV, runs an AI analysis on each record individually, appends a new column with the findings, and then produces an overall portfolio-level summary. Upload any dataset and define what you want analyzed — budget execution, compliance posture, operational performance, or anything else. 4 Nodes 2 LLM Steps Loop Node CSV Output [How It Works](#csv-how-it-works) · [Workflow](#csv-workflow) · [Sample Output](#csv-sample-output) [Download Workflow Template](/assets/downloads/agent-builder/csv_data_query.json) Import via the Agent Builder's **Import/Export** menu — sets up the full workflow and agent configuration automatically ### How It Works The workflow uses a Loop node to iterate through each row of the CSV, running an LLM analysis on every record before reassembling the results into an enriched dataset. 1. **Loop Rows** Iterates through each row of the uploaded CSV, sending one record at a time to the processing node and collecting all results. 2. **Process Row** Analyzes the individual record against your query — evaluating metrics, flagging anomalies, and generating a written assessment for that row. 3. **Format as CSV** Reassembles all original columns plus the new `Analysis` column into a clean CSV format ready for download. 4. **Return Response** Delivers the enriched CSV along with a portfolio-level summary covering totals, averages, and cross-record trends. ### Workflow in Agent Builder ![CSV Data Query workflow showing Loop Rows node connected to Process Row and Format as CSV nodes, ending with Return Response](/assets/images/agent-builder-v2-csv-workflow.png) ### Sample Enriched Output Below is a sample of the enriched CSV — the original data columns are preserved and a new **Analysis** column is appended with a per-row assessment. Click **Show All Columns** to reveal the full dataset, or view the condensed version with just the facility identifiers and analysis. | Facility Name | Region | Division | FY2025 Enacted | YTD Obligations | YTD Expenditures | Unliquidated | Unobligated Bal. | FTEs Auth. | FTEs Onboard | Outsourced Svc. | Direct Svc. Vol. | Analysis | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | Southwest | Division A | 200,000,000 | 182,000,000 | 165,000,000 | 17,000,000 | 18,000,000 | 1,500 | 1,380 | 22,000 | 410,000 | Facility demonstrates disciplined budget execution with 91.0% obligation rate and 90.7% expenditure rate. Staffing fill rate is 92.0% with outsourced leakage controlled at 5.4% of service volume. Operating within expected parameters. | | Bayside Health Complex | Southeast | Division C | 130,000,000 | 119,600,000 | 108,500,000 | 11,100,000 | 10,400,000 | 1,100 | 1,005 | 15,000 | 285,000 | Solid financial management with 92.0% obligation rate and 90.7% expenditure rate. Staffing fill rate of 91.4% is near target. Outsourced services at 5.3% suggest manageable contractor dependency. No significant anomalies identified. | | Bravo Regional Hospital | West | Division B | 200,000,000 | 190,000,000 | 174,800,000 | 15,200,000 | 10,000,000 | 1,400 | 1,260 | 18,500 | 380,000 | Strong execution with 95.0% obligation rate and 92.0% expenditure rate — ahead of schedule on budget absorption. Staffing fill rate of 90.0% is slightly below target. Outsourced leakage at 4.9% is within acceptable range. | | Cedar Valley Clinic | Midwest | Division A | 75,000,000 | 68,200,000 | 62,400,000 | 5,800,000 | 6,800,000 | 650 | 598 | 7,500 | 145,000 | Responsible fiscal management with 90.9% obligation rate and 91.5% expenditure rate. Staffing fill rate of 92.0% and controlled outsourcing at 5.2% of service volume. Stable operations with effective cost containment. | | Delta Medical Center | Pacific | Division B | 175,000,000 | 142,700,000 | 127,500,000 | 15,200,000 | 32,300,000 | 1,200 | 1,110 | 14,100 | 290,000 | Requires attention — obligation rate of 81.5% leaves $32.3M unobligated. Expenditure rate of 89.4% is acceptable. Staffing fill rate of 92.5% is strong. Recommend reviewing unobligated balance for potential reprogramming or year-end execution plan. | ### Portfolio-Level Summary In addition to the row-by-row analysis, the workflow produces an overall summary with aggregated totals and computed averages across the entire dataset. The screenshot below is a sample — the full output includes top risks, top performers, trend analysis, and a portfolio-level recommendation. ![Portfolio-level summary showing totals for FY2025 enacted budget, obligations, expenditures, FTEs, and computed average rates across all facilities](/assets/images/agent-builder-v2-csv-output.png) Industry Examples ### Proposal Evaluation Agent Automate your Go/No-Go decision process for government and commercial proposals. This workflow ingests opportunity documents alongside your company's capabilities, strategic priorities, and team capacity, then scores the opportunity across 10 weighted criteria and routes the result through a decision tree — automatically generating a tailored pursuit plan, risk assessment, or decline package depending on the outcome. 13 Nodes 7 LLM Steps Decision Tree .docx Output [How It Works](#proposal-how-it-works) · [Workflow](#proposal-workflow) · [Sample Output](#proposal-sample-output) [Download Workflow Template](/assets/downloads/agent-builder/proposal_evaluation_agent.json) Import via the Agent Builder's **Import/Export** menu — sets up the full workflow and agent configuration automatically ### How It Works The workflow uses a branching architecture — every opportunity follows the same intake and scoring pipeline, then a Decision Tree node routes execution down one of three paths based on the score. ![High-level logic flow: Upload Document, Extract Details, Score Opportunity, Decision Tree branching to GO (Pursuit Plan), MAYBE (Risk Assessment), or NO-GO (Decline Package), then Final Assessment Report saved as .docx](/assets/images/agent-builder-v2-proposal-logic-diagram.png) 1. **Extract Opportunity Details** Parses the uploaded solicitation to pull out requirements, evaluation criteria, timeline, competitive landscape, and red flags. 2. **Score Against Criteria** Evaluates the opportunity across 10 weighted dimensions — strategic alignment, technical capability, past performance, competitive position, and more — producing a score out of 100. 3. **Decision Tree** Routes the workflow based on the score: **GO** (80+) generates a full pursuit plan, **MAYBE** (50–79) triggers a risk assessment, and **NO-GO** (<50) produces a decline package with a no-bid letter. 4. **Final Assessment Report** Compiles everything into a polished, multi-section report with scoring dashboards, compliance matrices, competitive analysis, and a complete action plan — ready to export as `.docx`. ### Workflow in Agent Builder Below is the full node graph showing the branching architecture. After scoring, the Decision Tree routes to one of three LLM paths — each producing decision-specific output that feeds into the final report. ![Proposal Evaluation Agent workflow in Agent Builder showing 13 nodes with Decision Tree branching to GO, MAYBE, and NO-GO paths](/assets/images/agent-builder-v2-proposal-workflow.png) ### Sample Report Output The agent produces a comprehensive assessment report covering the opportunity snapshot, executive summary, scope analysis, compliance matrix, scoring dashboard, competitive landscape, and a final Go/No-Go recommendation with action plan. ![Report overview and executive summary showing scoring result and NO-GO recommendation](/assets/images/agent-builder-v2-proposal-report-overview.png) ![Opportunity snapshot table with solicitation details, contract type, value, and timeline](/assets/images/agent-builder-v2-proposal-report-snapshot.png) ![Scope of work summary covering LIMS requirements, deliverables, and critical success factors](/assets/images/agent-builder-v2-proposal-report-scope.png) ![Competitive landscape analysis and final NO-GO decision with rationale](/assets/images/agent-builder-v2-proposal-report-decision.png) ### Customizable Inputs The workflow accepts several variables so it can evaluate any opportunity against your specific organization: | Variable | Description | Example | | --- | --- | --- | | `opportunity_document` | Upload the solicitation or RFP to evaluate | PDF or Word document from SAM.gov | | `company_capabilities` | Your organization's skills, certifications, and relevant experience | Core competencies, NAICS codes, clearances | | `strategic_priorities` | Current fiscal year goals and target markets | Grow DoD cloud portfolio to $100M+ | | `team_capacity` | Current proposal team availability and B&P budget | Proposal team committed through April | | `incumbent_info` | Intelligence on the current contractor (if recompete) | Incumbent name, contract value, performance | | `evaluation_criteria` | Custom scoring weights and thresholds | Eligibility compliance weighted 3x | | `go_threshold` | Minimum score to recommend GO (default: 80) | 80 | | `maybe_threshold` | Minimum score for MAYBE vs NO-GO (default: 50) | 50 | ---------------- ## Get Started Now ### Start Building While we're developing comprehensive examples, you can start building workflows right away: [First Workflow Tutorial Build your first workflow with our step-by-step guide →](first-workflow) [Core Concepts Understand the fundamentals of workflows and nodes →](core-concepts) [Workflows & Nodes Learn advanced workflow building techniques →](workflows-and-nodes) --- # API & Integration Source: /docs/v2/agent-builder/api-integration.html # API & Integration Execute Agent Builder workflows programmatically with the Ask Sage API ---------------- ---------------- Overview ### Executing Agents via API Any workflow you build in Agent Builder can be triggered programmatically using the `POST /execute-agent` endpoint. Pass your agent's ID, a message, optional input variables, and optional conversation history — and get back the full execution result. POST https://api.asksage.ai/server/execute-agent For full endpoint details — including request parameters, response schema, authentication, and streaming options — see the [Ask Sage API Reference](../api-documentation/api-endpoints). ---------------- Use Case ### Multi-File Monthly Comparison This example uses the [CSV Data Query](use-cases#csv-data-query) agent to compare facility financial data across two months — February and March. A Python script calls `/execute-agent` for each month's CSV, enriches every row with AI-generated analysis, then runs a third call that compares the results and produces a portfolio-level trend summary. **Prerequisites:** This use case requires the CSV Data Query workflow imported into your Agent Builder. Download the workflow JSON template from the [Use Cases & Examples](use-cases#csv-download) page and import it via the Agent Builder's **Import/Export** menu. 2 Input Files 3 API Calls Per-Row Enrichment Cross-Month Comparison 1. **Authenticate** Get a 24-hour access token with your API key. 2. **Run Agent on February Data** Call `/execute-agent` with the February CSV. The agent loops through every row, calculates financial metrics, and appends a written analysis per facility. 3. **Run Agent on March Data** Same call with the March CSV. Each facility gets its own assessment based on that month's numbers. 4. **Cross-Month Comparison** A third API call passes both months' results via `conversation_history`. The agent calculates month-over-month deltas, identifies trends, and produces a portfolio summary. ![High-level logic flow: February and March data are each analyzed and enriched separately, then both results feed into a cross-month comparison that produces a trend summary](/assets/images/agent-builder-v2-api-multifile-flow.svg) ### Input Data Two CSV files with identical structure — one per month. Each row represents a facility with budget, obligation, expenditure, staffing, and service volume data. Download the sample datasets below and try it yourself — import the [CSV Data Query](use-cases#csv-data-query) template into Agent Builder, then run the script against your own Ask Sage account. [February CSV](/assets/downloads/agent-builder/facilities_feb.csv) [March CSV](/assets/downloads/agent-builder/facilities_mar.csv) #### February | Facility Name | Region | Monthly Budget | Obligations | Expenditures | Unliquidated | Unobligated Bal. | FTEs Onboard | Outsourced Svc. | Direct Svc. Vol. | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | Southwest | 16,700,000 | 15,200,000 | 13,800,000 | 1,400,000 | 1,500,000 | 1,380 | 1,800 | 34,200 | | Bayside Health Complex | Southeast | 10,800,000 | 9,700,000 | 8,900,000 | 800,000 | 1,100,000 | 1,005 | 1,250 | 23,800 | | Bravo Regional Hospital | West | 16,700,000 | 15,800,000 | 14,500,000 | 1,300,000 | 900,000 | 1,260 | 1,540 | 31,700 | | Cedar Valley Clinic | Midwest | 6,250,000 | 5,700,000 | 5,200,000 | 500,000 | 550,000 | 598 | 625 | 12,100 | | Delta Medical Center | Pacific | 14,600,000 | 11,700,000 | 10,400,000 | 1,300,000 | 2,900,000 | 1,110 | 1,175 | 24,200 | #### March | Facility Name | Region | Monthly Budget | Obligations | Expenditures | Unliquidated | Unobligated Bal. | FTEs Onboard | Outsourced Svc. | Direct Svc. Vol. | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | Southwest | 16,700,000 | 15,500,000 | 14,200,000 | 1,300,000 | 1,200,000 | 1,390 | 1,750 | 35,100 | | Bayside Health Complex | Southeast | 10,800,000 | 10,100,000 | 9,400,000 | 700,000 | 700,000 | 1,020 | 1,180 | 24,500 | | Bravo Regional Hospital | West | 16,700,000 | 15,400,000 | 13,900,000 | 1,500,000 | 1,300,000 | 1,240 | 1,680 | 30,900 | | Cedar Valley Clinic | Midwest | 6,250,000 | 5,800,000 | 5,350,000 | 450,000 | 450,000 | 602 | 610 | 12,300 | | Delta Medical Center | Pacific | 14,600,000 | 12,500,000 | 11,200,000 | 1,300,000 | 2,100,000 | 1,095 | 1,320 | 23,800 | ### Python Implementation The complete script below authenticates, runs the CSV Data Query agent on each monthly file, then passes both results into a third call for cross-month comparison. ```python """ Ask Sage Agent Builder — Multi-File Monthly Comparison Runs the CSV Data Query agent on February and March facility data, then generates a cross-month trend analysis. """ import requests import json # ─── Configuration ──────────────────────────────────────────── API_BASE = "https://api.asksage.ai" EMAIL = "your_email@organization.com" API_KEY = "your_api_key" AGENT_ID = 12 # Your CSV Data Query agent ID (from Agent Builder) # ─── Step 1: Authenticate ──────────────────────────────────── token_resp = requests.post( f"{API_BASE}/user/get-token-with-api-key", json={"email": EMAIL, "api_key": API_KEY} ) TOKEN = token_resp.json()["response"]["access_token"] headers = { "x-access-tokens": TOKEN, "Content-Type": "application/json" } print("Authenticated successfully.\n") # ─── Step 2: Define monthly files ──────────────────────────── months = [ {"file": "facilities_feb.csv", "label": "February"}, {"file": "facilities_mar.csv", "label": "March"}, ] results = {} # ─── Step 3: Run the agent on each month ───────────────────── for month in months: payload = { "agent_id": AGENT_ID, "message": ( f"Analyze budget execution, staffing efficiency, and " f"outsourced service dependency for {month['label']}. " f"Flag facilities below 85% obligation rate or above " f"7% outsourced service ratio." ), "streaming": False, "variables": { "source_data": month["file"], "analysis_query": ( "For each facility: calculate obligation rate " "(obligations / budget), expenditure rate " "(expenditures / obligations), and outsourced " "service ratio. Provide a written assessment " "per facility with key metrics and flags." ) } } resp = requests.post( f"{API_BASE}/server/execute-agent", headers=headers, json=payload ) result = resp.json() results[month["label"]] = result print( f" {month['label']}: {result['execution_status']} " f"({result['duration_ms']}ms, " f"{len(result['node_executions'])} nodes)" ) # ─── Step 4: Cross-month comparison ────────────────────────── comparison_payload = { "agent_id": AGENT_ID, "message": ( "Compare facility performance between February and " "March. Calculate month-over-month deltas for " "obligation rates, expenditure rates, FTE changes, and " "outsourced ratios. Identify the top performer, any " "watch-list facilities, and recovering facilities. " "Produce a portfolio-level aggregate summary." ), "streaming": False, "variables": { "source_data": "facilities_feb.csv,facilities_mar.csv", "analysis_query": ( "Cross-month comparison with per-facility trend " "indicators and portfolio-level totals." ) }, "conversation_history": [ { "message": results["February"]["response"]["response"], "user": "me" }, { "message": results["March"]["response"]["response"], "user": "me" } ] } comparison = requests.post( f"{API_BASE}/server/execute-agent", headers=headers, json=comparison_payload ) comp_result = comparison.json() print( f"\n Comparison: {comp_result['execution_status']} " f"({comp_result['duration_ms']}ms)\n" ) # ─── Step 5: Output results ────────────────────────────────── for label, result in results.items(): print(f"\n{'='*60}") print(f" {label} — Enriched Results") print(f"{'='*60}") print(result["response"]["response"]) print(f"\n{'='*60}") print(f" Cross-Month Comparison") print(f"{'='*60}") print(comp_result["response"]["response"]) ``` #### Console Output ```text Authenticated successfully. February: completed (8423ms, 4 nodes) March: completed (7891ms, 4 nodes) Comparison: completed (6204ms) ``` ### Enriched Output Each API call returns the original CSV data with a new **Analysis** column appended. The agent evaluates every row individually — calculating obligation rates, expenditure rates, outsourced service ratios, and flagging anomalies. #### February — Enriched | Facility Name | Region | Monthly Budget | Obligations | Expenditures | FTEs | Analysis | | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | Southwest | 16,700,000 | 15,200,000 | 13,800,000 | 1,380 | Obligation rate 91.0%, expenditure rate 90.8%. Staffing at 1,380 FTEs. Outsourced ratio 5.0% of total service volume. Solid execution within expected parameters — no flags. | | Bayside Health Complex | Southeast | 10,800,000 | 9,700,000 | 8,900,000 | 1,005 | Obligation rate 89.8%, expenditure rate 91.8%. Staffing at 1,005 FTEs. Outsourced ratio 5.0%. Obligation rate trending below 90% target — recommend monitoring for acceleration in March. | | Bravo Regional Hospital | West | 16,700,000 | 15,800,000 | 14,500,000 | 1,260 | Obligation rate 94.6%, expenditure rate 91.8%. Staffing at 1,260 FTEs. Outsourced ratio 4.6%. Strong execution — ahead of pace on budget absorption with low outsourced dependency. | | Cedar Valley Clinic | Midwest | 6,250,000 | 5,700,000 | 5,200,000 | 598 | Obligation rate 91.2%, expenditure rate 91.2%. Staffing at 598 FTEs. Outsourced ratio 4.9%. Stable, disciplined fiscal management with balanced service delivery. | | Delta Medical Center | Pacific | 14,600,000 | 11,700,000 | 10,400,000 | 1,110 | Obligation rate 80.1% — below 85% threshold. Expenditure rate 88.9%. $2.9M unobligated balance remains. Recommend immediate execution acceleration plan and root cause analysis for obligation shortfall. | #### March — Enriched | Facility Name | Region | Monthly Budget | Obligations | Expenditures | FTEs | Analysis | | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | Southwest | 16,700,000 | 15,500,000 | 14,200,000 | 1,390 | Obligation rate 92.8% (+1.8pp MoM), expenditure rate 91.6%. Staffing +10 FTEs. Outsourced ratio improved to 4.7%. Continued strong execution with positive trajectory across all metrics. | | Bayside Health Complex | Southeast | 10,800,000 | 10,100,000 | 9,400,000 | 1,020 | Obligation rate 93.5% (+3.7pp MoM), expenditure rate 93.1%. Staffing +15 FTEs. Outsourced ratio improved to 4.6%. Significant recovery — obligation rate now well above 90% target. | | Bravo Regional Hospital | West | 16,700,000 | 15,400,000 | 13,900,000 | 1,240 | Obligation rate 92.2% (-2.4pp MoM), expenditure rate 90.3%. Staffing -20 FTEs. Outsourced ratio increased to 5.2%. Staffing losses correlating with rising outsourced dependency — monitor closely. | | Cedar Valley Clinic | Midwest | 6,250,000 | 5,800,000 | 5,350,000 | 602 | Obligation rate 92.8% (+1.6pp MoM), expenditure rate 92.2%. Staffing +4 FTEs. Outsourced ratio 4.7%. Consistent improvement across all metrics — no concerns. | | Delta Medical Center | Pacific | 14,600,000 | 12,500,000 | 11,200,000 | 1,095 | Obligation rate 85.6% (+5.5pp MoM) — recovered to threshold but still borderline. Staffing -15 FTEs. Outsourced ratio increased to 5.3%. Budget execution improving but staffing attrition driving outsourced growth. | ### Cross-Month Comparison The third API call produces a facility-by-facility trend analysis and a portfolio-level aggregate. This is the output of passing both months' enriched results via `conversation_history`. #### Per-Facility Trend Summary | Facility | Feb Oblig. Rate | Mar Oblig. Rate | Delta | Feb Outsrc. % | Mar Outsrc. % | Delta | FTE Change | Trend | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Aurora Medical Center | 91.0% | 92.8% | +1.8pp | 5.0% | 4.7% | -0.3pp | +10 | Improving | | Bayside Health Complex | 89.8% | 93.5% | +3.7pp | 5.0% | 4.6% | -0.4pp | +15 | Improving | | Bravo Regional Hospital | 94.6% | 92.2% | -2.4pp | 4.6% | 5.2% | +0.6pp | -20 | Declining | | Cedar Valley Clinic | 91.2% | 92.8% | +1.6pp | 4.9% | 4.7% | -0.2pp | +4 | Improving | | Delta Medical Center | 80.1% | 85.6% | +5.5pp | 4.6% | 5.3% | +0.7pp | -15 | Mixed | #### Portfolio-Level Summary Total Monthly Budget $65,050,000 Unchanged MoM Avg. Obligation Rate 89.3% → 91.2% +1.9pp improvement Avg. Expenditure Rate 90.9% → 91.1% +0.2pp improvement Total FTEs 5,353 → 5,347 Net loss of 6 FTEs Portfolio Outsourced % 4.8% → 4.9% +0.1pp increase Unobligated Balance $6.95M → $5.75M -$1.2M (improved absorption) **Top Performer** Bayside Health Complex — obligation rate jumped +3.7pp to 93.5%, added 15 FTEs, and reduced outsourced dependency. Strongest month-over-month improvement in the portfolio. **Watch List** Bravo Regional Hospital — obligation rate declined 2.4pp, lost 20 FTEs, and outsourced ratio rose to 5.2%. Staffing attrition appears to be driving increased contractor dependency. **Recovering** Delta Medical Center — obligation rate improved +5.5pp from 80.1% to 85.6%, clearing the 85% threshold. However, continued FTE losses (-15) and rising outsourced ratio (5.3%) warrant monitoring. ---------------- ## Learn More ### Related Resources [CSV Data Query Template Download the workflow template and see the full node-by-node breakdown →](use-cases#csv-data-query) [Workflows & Nodes Learn about Loop nodes, Save nodes, and other building blocks →](workflows-and-nodes) [Full API Reference Complete endpoint documentation including /execute-agent parameters and responses →](../api-documentation/api-endpoints) --- # Advanced Techniques Source: /docs/v2/agent-builder/advanced-techniques.html # Advanced Techniques Under Construction Optimize and debug sophisticated workflows **Under Construction:** This page is currently being developed. Check back soon for comprehensive guides on advanced workflow techniques and optimization strategies. ---------------- ---------------- ## Performance Optimization ### Maximize Workflow Efficiency Coming soon: Detailed guidance on optimizing workflow performance and resource usage. ### Planned Topics - Token management strategies - Parallel processing techniques - Caching and result reuse - Batch operation optimization - Resource limit management - Execution time reduction ---------------- ## Complex Workflow Patterns ### Advanced Design Patterns Coming soon: Sophisticated workflow patterns for complex use cases. ### Pattern Categories - Dynamic workflow branching - State management patterns - Error recovery strategies - Recursive workflows - Multi-stage processing pipelines - Conditional execution flows ---------------- ## Debugging Strategies ### Advanced Debugging Coming soon: Pro-level debugging techniques and tools. ### Debugging Topics - Workflow execution analysis - Performance profiling - Data flow tracing - Error pattern identification - Testing strategies - Monitoring and logging best practices ---------------- ## Related Resources ### Learn More Explore these foundational topics to prepare for advanced techniques: [Core Concepts Master the fundamentals before tackling advanced topics →](core-concepts) [Workflows & Nodes Understand workflow building and available nodes →](workflows-and-nodes) [Troubleshooting Debug common issues and errors →](troubleshooting) --- # Troubleshooting Source: /docs/v2/agent-builder/troubleshooting.html # Troubleshooting Guide Solutions to common workflow issues ---------------- ---------------- ## Quick Troubleshooting Checklist ### Before Requesting Help Start here! Most workflow issues can be resolved by verifying these essentials: ### Workflow Setup - Workflow saved before running - In Run mode (not Edit mode) - Agent created and selected - All nodes connected properly ### Node Configuration - File variables match agent config (e.g., input.source_data_1) - Required parameters filled - Appropriate model selected in LLM nodes - Variables saved before referenced downstream ### Syntax & Data - Template syntax correct ({{variable}} for saved variables) - Variable names match exactly - Files or text provided if workflow requires them **Quick Fix:** Check the Execution/Activity Log on the right panel for specific error messages. Each "event" entry contains details about what went wrong. ---------------- ## Common Mistakes to Avoid ### What to Watch Out For ### Missing Connections - Every node needs proper input/output connections - Disconnected nodes won't execute - Check for loose or missing connections ### Incorrect Data Types - Ensure output types match input expectations - Use conversion nodes when needed ### Missing Required Parameters - Configure all required fields and relevant parameters for your use case in each node - Workflows won't run with missing required fields or may generate inaccurate results with incomplete configuration **Quick Fix:** Most workflow errors can be identified by looking for red indicators on nodes or broken connection lines. ---------------- ## Node Configuration Issues ### Configuration Problems & Solutions Incorrect node configuration is one of the most common causes of workflow failures. Here are specific configuration issues and how to fix them: ### LLM Node Configuration Errors #### File Variable Naming Issues **Problem:** File variable configured incorrectly causes "Source '[entered source value]' not found" errors **Critical Syntax:** - **Correct:** `input.source_data_1` (with `input.` prefix) - **Wrong:** `source_data_1` (missing prefix) - **Wrong:** `{{input.source_data_1}}` (don't use curly braces in file_variables field) - **Multiple Sources:** Use comma as delimiter: `input.source_data_1, input.source_data_2` **Where to check:** - LLM node configuration → "Attached Files" field - Agent configuration → File variable key must match (e.g., `source_data_1`) - All LLM nodes in workflow should use consistent naming **Solution:** Always use `input.source_data_1` format in LLM node file_variables field #### Model Selection **Important:** While a model is selected by default, you should choose the appropriate model for your specific use case **Best Practices:** - Review the default model and select one that matches your task requirements - Consider model capabilities (reasoning, speed, cost) for each node's purpose - Different nodes can use different models optimized for their specific tasks #### Temperature Settings **What it does:** Controls randomness in AI responses - **Low (0.0-0.3):** Deterministic, consistent - use for data extraction and analysis - **Medium (0.4-0.7):** Balanced - use for general tasks - **High (0.8-1.0):** Creative, varied - use for content generation and brainstorming **Best Practice:** Use lower temperatures (0.1-0.2) for extraction tasks and higher temperatures (0.8-1.0) for creative planning, as shown in the [First Workflow Tutorial](first-workflow#step-2-add-the-first-llm-node-for-data-extraction). ### Variable Assignment Node Issues #### Source Field Errors **Problem:** "Variable not found" or empty variables downstream **Correct Format:** - `llm_node_name.response` (for LLM node output) - `decision_tree_node.category` (for Decision Tree classification) - `loop_node.complete` (for Loop node aggregated results) #### Variable Naming Rules **Valid:** Letters, numbers, underscores only - `evaluation` - `evaluation_questions` - `project_plan_2024` **Invalid:** - `evaluation-questions` (hyphens not allowed) - `project plan` (spaces not allowed) - `evaluation.questions` (dots reserved for node.property syntax) ### Return Response Node Problems #### Template Syntax Errors **Problem:** Variables show as empty or template doesn't render **Correct Template Syntax:** ``` {{evaluation}}, {{evaluation_questions}}, {{project_plan}} ``` **Common Mistakes:** - Typo in variable name: `{{evalution}}` instead of `{{evaluation}}` - Missing curly braces: `evaluation` instead of `{{evaluation}}` - Variable not saved: Referencing a variable that was never created with Save Variable node #### Response Type Mismatches **Problem:** Output format doesn't match response type setting - **Text:** Use for plain text or markdown output - **JSON:** Use when returning structured data - template must produce valid JSON **Pro Tip:** Test your workflow incrementally after configuring each node. This helps identify configuration issues immediately rather than debugging the entire workflow later. ---------------- ## Error Handling ### Handling Errors Gracefully Proper error handling ensures your workflows handle unexpected situations gracefully and provide useful feedback. ### Error Handling Strategies 1. Try Attempt operation → 2. Catch Handle errors → 3. Finally Cleanup actions ### Error Types - **Validation Errors**: Invalid input data - **Processing Errors**: Node execution failures - **Timeout Errors**: Operations taking too long ### Recovery Options - **Retry**: Attempt the operation again - **Log and Continue**: Record error and proceed - **Fail Gracefully**: Stop execution with informative message **Best Practice:** Always include error handling for external API calls and user input validation. ---------------- ## Variable Reference & Template Syntax ### Syntax Rules & Common Mistakes Understanding when and how to reference variables is critical for workflow success. Different contexts require different syntax: ### Syntax Quick Reference | Context | Correct Syntax | Example | Wrong Syntax | | --- | --- | --- | --- | | **File Variables (LLM Node)** | `input.source_data_1` | Attached Files field: `input.source_data_1` | `{{input.source_data_1}}` `source_data_1` | | **Save Variable Source** | `node_name.response` | Source: `llm_1.response` | `{{llm_1.response}}` `llm_1` | | **Saved Variables in Templates** | `{{variable_name}}` | Prompt: `Analyze: {{evaluation}}` | `evaluation` `{{evaluation` | | **Node Outputs in Templates** | `{{node_name.response}}` | Template: `{{llm_1.response}}` | `llm_1.response` `{{llm_1}}` | | **If/Else Conditions** | `variable_name > 80` | Condition: `confidence > 0.8` | `{{confidence}} > 0.8` `"confidence" > 0.8` | | **Agent File Variable Key** | `source_data_1` | Key: `source_data_1` (without input.) | `input.source_data_1` `{{source_data_1}}` | ### Common Syntax Mistakes #### Mistake 1: Using Curly Braces in Wrong Context **Wrong:** In LLM file_variables field: `{{input.source_data_1}}` In Save Variable source field: `{{llm_1.response}}` In If/Else condition: `{{score}} > 80` **Correct:** In LLM file_variables field: `input.source_data_1` In Save Variable source field: `llm_1.response` In If/Else condition: `score > 80` **Rule:** Only use `{{}}` in template fields (prompts, Return Response templates) #### Mistake 2: Missing Input Prefix for Files **Wrong:** LLM Node file_variables: `source_data_1` **Result:** "File not populated" error **Correct:** LLM Node file_variables: `input.source_data_1` **Note:** Agent configuration uses `source_data_1` (without "input."), but LLM nodes use `input.source_data_1` #### Mistake 3: Variable Name Typos **Problem:** Variable names in templates must match EXACTLY what was saved **Common Typos:** - `{{evalution}}` instead of `{{evaluation}}` - `{{project-plan}}` instead of `{{project_plan}}` - `{{evaluation_question}}` instead of `{{evaluation_questions}}` (missing 's') **Solution:** Copy variable names directly from Save Variable nodes to avoid typos #### Mistake 4: Wrong Node Output Property Different node types have different output properties: | Node Type | Output Property | Example | | --- | --- | --- | | LLM Node | `.response` | `llm_1.response` | | Decision Tree Node | `.category` | `classifier_1.category` | | Loop Node | `.complete` | `loop_1.complete` | | Save Variable Node | Variable name directly | `{{evaluation}}` (not `save_1.evaluation`) | **Learn More:** See the [Save Variable Node documentation](workflows-and-nodes#save-variable-node) for detailed examples of variable referencing. ---------------- ## Debugging Workflows ### Finding and Fixing Issues ### Debugging Techniques 1. **Test Incrementally**: Run your workflow after adding each node 2. **Check Node Status**: Look for error indicators on individual nodes 3. **Review Execution Logs**: Examine detailed logs for error messages 4. **Isolate Problem Areas**: Copy workflow and run only sections that work up to the point of failure 5. **Verify Data Flow**: Check that data is being passed correctly between nodes ### Common Debug Patterns ### Inspection Nodes Add debug nodes to inspect data - Log intermediate results - Verify data structure - Track execution flow ### Test Data Use controlled inputs for testing - Known input values - Expected outputs - Edge case scenarios **Debugging Tip:** Start with the simplest possible workflow and add complexity only after confirming each part works correctly. ---------------- ## Workflow Execution Problems ### Running & Executing Workflows Problems that occur when trying to execute your workflow: ### Edit vs Run Mode Issues #### Understanding the Modes ### Edit Mode Build and configure your workflow - Add and configure nodes - Draw connections - Configure agent settings - Cannot execute workflow ### Run Mode Execute and test your workflow - Upload files - Run agent - View execution logs - Cannot edit nodes **Problem:** "Why can't I execute?" or "Why can't I edit?" **Solution:** 1. **To Execute:** Save workflow → Switch to Run mode → Select agent → Click Run Agent 2. **To Edit:** Switch to Edit mode → Make changes → Save → Switch back to Run mode 3. **Important:** Always save before switching modes **Mode Reference:** See [Running Your Workflow](first-workflow#running-your-workflow) for detailed steps on mode switching and execution. ### Agent Configuration Problems #### Missing Agent Setup **Problem:** Workflow won't run, no agent in dropdown **Solution - Create Agent:** 1. Switch to Edit mode 2. Locate agent configuration section (below Node Palette on left) 3. Set dropdown to "(New agent)" 4. Configure: **Name:** Descriptive name (e.g., "RFI-RFP-Agent") 5. **Model:** Select from dropdown 6. **Temperature:** 0-1 (default: 0) 7. **Variables:** Add file variables if workflow uses files 8. Click "Save" #### Variable Type Mismatches **Problem:** File upload doesn't work or file not found **Cause:** Agent variable configured as "Text" instead of "File" **Solution:** - Agent configuration → "+ Add Variable" - Change type from "Text" to "File" - Set key to match file variable name: `source_data_1` (without "input." prefix) - Save agent configuration #### File Variable Key Naming **Critical:** Agent and LLM nodes use different naming conventions: | Location | Syntax | Example | | --- | --- | --- | | Agent Configuration → Variable Key | `source_data_1` | No "input." prefix | | LLM Node → file_variables | `input.source_data_1` | With "input." prefix | ### File Upload Issues #### File Limits - **Max files per LLM node:** 5 files - **Supported formats:** Many file types including PDF, Word, Excel, CSV, images (for vision models), text files, and more - **Special handling:** CSV/Excel files enable data analysis capabilities #### File Not Reaching Node **Problem:** File uploaded but LLM node can't access it **Checklist:** 1. Agent variable type is "File" (not "Text") 2. Agent variable key matches: `source_data_1` 3. LLM node file_variables uses: `input.source_data_1` 4. File was uploaded in Run mode (not Edit mode) 5. All LLM nodes in workflow use same file variable **File Flow:** Files flow from agent upload → all LLM nodes that reference `input.source_data_1`. Each LLM node receives the same uploaded file(s). ---------------- ## Workflow Won't Run ### Execution Issues ### Checklist for Non-Running Workflows - All nodes are connected properly - Required parameters are filled in - No disconnected nodes exist - Data types match between connections - No circular dependencies present - Workflow has been saved **Quick Start:** Try running one of the example workflows to verify your environment is set up correctly. ---------------- ## Real-World Examples from Tutorials ### Common Problems from Tutorial Workflows These are actual issues users encounter when following the [First Workflow Tutorial](first-workflow). Each example includes the problem, cause, and solution: ### Example 1: Empty Variables in Third LLM Node **Problem:** "My third LLM node (rfi_rfp_project-plan) shows empty variables for {{evaluation}} and {{evaluation_questions}}" **Cause:** Save Variable nodes (Steps 3 and 5 in tutorial) were skipped or misconfigured **What Happened:** - User configured the three LLM nodes correctly - But forgot to add Save Variable nodes between them - Variables `evaluation` and `evaluation_questions` were never created - Third LLM prompt references variables that don't exist **Solution:** 1. Add Save Variable node after first LLM node (rfi_rfp_data_extraction) Source: `rfi_rfp_data_extraction.response` 2. Variable name: `evaluation` 3. Add Save Variable node after second LLM node (rfi_rfp_questionnaire) Source: `rfi_rfp_questionnaire.response` 4. Variable name: `evaluation_questions` 5. Connect nodes properly: LLM → Save Variable → Next LLM 6. Verify variable names match EXACTLY in prompt template **Tutorial Reference:** [Step 3](first-workflow#step-3-add-a-save-variable-node) and [Step 5](first-workflow#step-5-add-another-variable-assignment-node) in the First Workflow Tutorial ### Example 2: File Not Found in Third LLM Node **Problem:** "The rfi_rfp_project-plan node shows 'file not populated' in execution logs" **Cause:** File variable inconsistency in Step 6 of the tutorial **What Happened:** - First two LLM nodes correctly use `input.source_data_1` - Tutorial Step 6 says to use `source_data_1` (missing `input.` prefix) - This inconsistency causes the third node to not receive the uploaded file **Solution:** - **Correct configuration:** Use `input.source_data_1` in ALL three LLM nodes - Open third LLM node (rfi_rfp_project-plan) - Change file_variables from `source_data_1` to `input.source_data_1` - Save workflow and test again **Tutorial Note:** [Step 6](first-workflow#step-6-add-a-third-llm-node-for-project-planning) has this inconsistency. Always use `input.source_data_1` format for file variables in LLM nodes. ### Example 3: Workflow Won't Execute **Problem:** "When I click Run Agent, nothing happens" or "Can't find the Run Agent button" **Cause:** Still in Edit mode or workflow not saved **What Happened:** - User built the workflow in Edit mode - Tried to execute without switching to Run mode **Solution:** 1. Click the **"Save"** button (top of screen) 2. Switch from **"Edit"** to **"Run"** mode using the toggle 3. Left panel transforms to show agent interface 4. Select your agent from dropdown (RFI-RFP-Agent) 5. Upload your RFP/RFI document using the file attachment button 6. Click the blue **"Run Agent"** button **Tutorial Reference:** [Running Your Workflow](first-workflow#step-2-switch-to-run-mode) section explains the mode switching process ### Example 4: Return Response Shows Nothing **Problem:** "Workflow completes but Return Response node output is empty or shows raw variable names" **Cause:** Variable names in template don't match saved variable names **What Happened:** - User typed `{{evalution}}` instead of `{{evaluation}}` (typo) - Or used `{{project-plan}}` with hyphens instead of `{{project_plan}}` with underscores - Variable names must match EXACTLY (case-sensitive, spelling, punctuation) **Solution:** 1. Check Return Response node template matches these EXACT names: `{{evaluation}}` 2. `{{evaluation_questions}}` 3. `{{project_plan}}` 4. Verify each Save Variable node uses these exact names 5. Look for typos: missing letters, extra spaces, wrong punctuation 6. Copy-paste variable names from Save Variable nodes to avoid typos **Pro Tip:** Copy variable names directly from Save Variable nodes instead of retyping them in templates. This prevents typos and ensures exact matches. ---------------- ## Getting Help ### When You Need Additional Support ### Before Contacting Support 1. Review this troubleshooting guide 2. Check the [Core Concepts](core-concepts) documentation 3. Try running example workflows to isolate the issue 4. Collect error messages and execution logs - expand the Execution Logs modal and use the DOCX export to capture the full run in a single file 5. Note the steps that led to the problem ### Information to Provide When requesting help, include: #### 1. Workflow Context - **Description:** What you're trying to accomplish - **Tutorial/Example:** Which tutorial or example you're following (if any) - **Workflow JSON:** Export your workflow using the Import/Export feature - **Node count:** How many nodes in your workflow #### 2. Reproduction Steps - Exact steps taken before the issue occurred - Which node the issue occurs at - Whether issue is consistent or intermittent - What you expected to happen vs. what actually happened #### 3. Error Information - **Error messages:** Exact text from Activity log - **Execution Logs:** Open the **Expand** button at the top of the Activity panel and export the full log with the DOCX icon in the modal header - see [Exporting Logs and Results](first-workflow) - **Failed node name:** Which node shows error - **Error timing:** When in execution the error occurs #### 4. Configuration Details - **Screenshots:** Workflow canvas showing all nodes and connections - **Node configuration:** Screenshot of failed node's settings panel - **Agent configuration:** Agent settings (model, temperature, variables) - **File details:** If using files, what type/size/format #### 5. Environment - Browser and version - When the issue started (new workflow or existing that stopped working) - Whether this workflow worked before **Export Workflow:** To export your workflow JSON, use the Import/Export feature in Agent Builder. This allows support to recreate your exact setup and identify the issue faster. ### Additional Resources [Core Concepts Understanding fundamentals can prevent common issues →](core-concepts) [Node Reference Detailed documentation for each node type →](workflows-and-nodes) [Working Examples Under Construction Learn from successful workflow implementations →](use-cases) **Beta Feature:** As Agent Builder is in beta, we're continuously improving it. Your feedback on issues helps us make it better for everyone! --- # Ask Sage API Source: /docs/v2/api-documentation/api-documentation.html # Ask Sage API Build custom applications with programmatic access to Ask Sage's powerful AI models ![Ask Sage API](/assets/images/api-v2-hero.png) ---------------- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. ---------------- ## API Documentation ### Interactive API Documentation The Ask Sage API provides comprehensive Swagger documentation for seamless integration. Choose the API surface that matches your needs: [Server API Core server-side operations and model access (v1.56) →](/api-docs/swagger.html) [User API User management and authentication endpoints (v1.21) →](/api-docs/swagger.html) **Pro Tip:** Swagger documentation provides interactive API exploration with request/response examples, parameter details, and authentication requirements. ![Swagger Documentation Interface](/assets/images/api-v2-swagger.png) ---------------- ## Creating an API Key ### Generate Your API Key Follow these steps to generate your API key: 1. **Navigate to Settings** in the Ask Sage platform 2. Switch to the **API Keys** tab 3. Enter a name for your key and, optionally, select one or more **scopes** to restrict what it can access 4. Click **+ Create Key** to generate your new API key ### Restricting Access with Scopes A key created with no scopes selected has **full access** to the Ask Sage API. Selecting one or more scopes limits the key to only the endpoints covered by those scopes: ![Scopes dropdown open in the API Keys tab, showing agent_builder, mcp, passthrough, plugins, and query options](/assets/images/api-v2-key-scopes.png) | Scope | Grants access to | | :--- | :--- | | `query` | Core chat and completion endpoints, such as `/query` and `/query_with_file` | | `plugins` | Plugin discovery and execution endpoints, such as `/get-plugins` and `/execute-plugin` | | `mcp` | MCP server management endpoints (add, list, update, delete) | | `passthrough` | Ask Sage's OpenAI/Anthropic-compatible passthrough proxy, used when configuring Ask Sage as a custom model provider in third-party tools | | `agent_builder` | Triggering Agent Builder workflows programmatically via `POST /execute-agent` | **Security Notice:** Keep your API key secure and never share it publicly. Treat it like a password, rotate keys regularly, and prefer a scoped key over a full-access key whenever your integration only needs a subset of the API. ---------------- ## Getting Started ### Choose Your Integration Method Pick the integration approach that fits your workflow: [API Endpoints Direct REST API integration with detailed endpoint documentation →](/docs/v2/api-documentation/api-endpoints.html) [Python Client Official Python SDK for rapid development and easy integration →](/docs/v2/api-documentation/ask-sage-python-client.html) ---------------- ## Open Source Community ### Join Our GitHub Community Explore code samples, tutorials, and community contributions. We welcome your feedback and contributions! ![Ask Sage GitHub Repository](/assets/images/api-v2-python-repo.png) [View Repository Browse code samples, examples, and community contributions on GitHub →](https://github.com/Ask-Sage/AskSage-Open-Source-Community) **Stay Updated:** The repository is continuously updated with new examples, best practices, and community resources. Star the repo to stay informed! --- # API Endpoints Source: /docs/v2/api-documentation/api-endpoints.html # Ask Sage API Endpoints Comprehensive guide to the Ask Sage REST API surface ![Ask Sage API Base URL](/assets/images/api-v2-base-url.png) ---------------- ## Overview ### Two-Surface Architecture The Ask Sage API is a modern RESTful API providing comprehensive access to the Ask Sage platform. Our API architecture is divided into two specialized components, each designed for specific functionalities — the **Server API** and the **User API**. Each has its own base URL, purpose, and set of endpoints. The Server API focuses on core AI operations, model queries, and server management, while the User API handles user management, authentication, and dataset operations. This separation ensures optimized performance and security for different types of interactions with the Ask Sage platform. ---------------- User API ## User API Endpoints ### Purpose & Base URL User management, authentication, and dataset operations. BASE api.{instance}.ai/user/ **Instance-Specific Base URL:** The base URL shown reflects the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and `/user/` suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against. **Swagger Documentation:** [View User API Documentation →](/api-docs/swagger.html) **Scoped API Keys:** If you're calling these endpoints with a scoped API key, make sure the key includes the scope that covers the endpoint you need — see [Restricting Access with Scopes](/docs/v2/api-documentation/api-documentation.html#restricting-access-with-scopes). ### Available Endpoints | Method | Endpoint | Description | | :----- | :------- | :---------- | | `POST` | `/get-token-with-api-key` | Get an access token with API Key and email | | `POST` | `/get-user-logins` | Get your last logins (limited to 5 by default) | | `POST` | `/get-user-logs` | Get your last prompts | | `POST` | `/add-dataset` | Add a new dataset | | `POST` | `/delete-datasets` | Delete a dataset | | `POST` | `/get-chats` | Get all chat sessions for user | | `POST` | `/get-chat-session` | Get specific chat session | | `POST` | `/delete-chat-session` | Delete chat session | | `POST` | `/deassign-dataset` | Remove dataset from user | | `POST` | `/update-permission-dataset` | Update dataset permissions | | `POST` | `/get-datasets-with-permissions` | Get user datasets with permissions | | `POST` | `/get-user-api-keys` | Get user API keys | | `POST` | `/user-api-key` | Create new API key | | `DELETE` | `/user-api-key` | Delete API key | ---------------- Server API ## Server API Endpoints ### Purpose & Base URL Core AI operations, model queries, and server management. BASE api.{instance}.ai/server/ **Instance-Specific Base URL:** The base URL shown reflects the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and `/server/` suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against. **Swagger Documentation:** [View Server API Documentation →](/api-docs/swagger.html) ### Available Endpoints | Method | Endpoint | Description | | :----- | :------- | :---------- | | `POST` | `/get-models` | Returns a list of available models | | `POST` | `/query` | Main endpoint for generating completions | | `POST` | `/query_with_file` | Query with file for generating completions | | `POST` | `/query-plugin` | Query with plugin for generating completions | | `POST` | `/execute-plugin` | Execute a plugin with provided content | | `POST` | `/follow-up-questions` | Generate follow-up questions | | `POST` | `/tokenizer` | Get tokens of string value | | `POST` | `/get-personas` | Get available personas | | `POST` | `/get-datasets` | Returns a list of available datasets | | `POST` | `/get-plugins` | Returns a list of available plugins | | `POST` | `/train` | Train the model based on user input | | `POST` | `/file` | Convert supported file to plain text | | `POST` | `/execute-plugin-with-file` | Execute plugin with file input | | `POST` | `/get-deep-agent` | Get streaming updates from deep agent | | `POST` | `/add-mcp-server` | Add new MCP server for user | | `PUT` | `/update-mcp-server` | Update existing MCP server configuration | | `GET` | `/list-mcp-servers` | Get list of all MCP servers for user | | `POST` | `/list-mcp-servers` | Get list of all MCP servers for user | | `GET` | `/list-mcp-whitelisted-servers` | Get list of whitelisted MCP servers | | `GET` | `/list-mcp-tools` | Get list of available MCP tools | | `DELETE` | `/delete-mcp-server` | Soft delete MCP server | | `DELETE` | `/dataset` | Delete specific dataset | | `POST` | `/delete-filename-from-dataset` | Remove specific file from dataset | | `POST` | `/get-all-files-ingested` | Returns list of all ingested files | | `POST` | `/copy-files-dataset` | Copy files from one dataset to another | | `POST` | `/vote-down` | Mark response as unhelpful or incorrect | | `GET` | `/count-monthly-tokens` | Returns count of tokens used this month | | `POST` | `/count-monthly-tokens` | Returns token count for specific app | | `GET` | `/count-monthly-teach-tokens` | Returns training tokens used this month | | `POST` | `/train-with-file` | Train model using file content | | `POST` | `/train-with-array` | Train model using array of content | | `GET` | `/get-secrets` | Returns list of stored secrets (keys only) | | `POST` | `/get-text-to-speech` | Generate audio from text using TTS | | `GET` | `/list-agents` | Returns a list of all agents available to the user | | `POST` | `/execute-agent` | Execute an agent with a message and optional variables | ---------------- Code Examples ## Code Examples ### Quick Start Each example below includes **Bash**, **Python**, and **JavaScript** code stacked sequentially. Replace `your_access_token` with a valid token obtained from the **Get Access Token** endpoint. ### Authentication ### Get Access Token Authenticate with your API key to receive an access token for subsequent requests. POST /user/get-token-with-api-key ```bash curl -X POST 'https://api.asksage.ai/user/get-token-with-api-key' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "email": "your_email@email.com", "api_key": "your_api_key" }'import requests url = 'https://api.asksage.ai/user/get-token-with-api-key' headers = { 'Accept': 'application/json', 'Content-Type': 'application/json' } data = { 'email': 'your_email@email.com', 'api_key': 'your_api_key' } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/user/get-token-with-api-key', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'your_email@email.com', api_key: 'your_api_key' }) }); const data = await response.json(); console.log(data); ``` ### Create API Key Generate a new API key for programmatic access. POST /user/user-api-key ```bash curl -X POST 'https://api.asksage.ai/user/user-api-key' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{"name": "My API Key"}'import requests url = 'https://api.asksage.ai/user/user-api-key' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = {'name': 'My API Key'} response = requests.post(url, headers=headers, json=data) if response.status_code == 200: print('Success:', response.json()) else: print('Error:', response.json())const response = await fetch('https://api.asksage.ai/user/user-api-key', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'My API Key' }) }); const data = await response.json(); console.log(data); ``` ### List API Keys Retrieve all API keys associated with your account. POST /user/get-user-api-keys ```bash curl -X POST 'https://api.asksage.ai/user/get-user-api-keys' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/user/get-user-api-keys' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers, json={}) if response.status_code == 200: print('Success:', response.json()) else: print('Error:', response.json())const response = await fetch('https://api.asksage.ai/user/get-user-api-keys', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({}) }); const data = await response.json(); console.log(data); ``` ### Core AI Operations ### Send Query Send a message to an AI model and receive a response. This is the primary endpoint for interacting with Ask Sage. POST /server/query ```bash curl -X POST 'https://api.asksage.ai/server/query' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{ "message": "What is Ask Sage?", "persona": 1, "dataset": ["dataset1", "dataset2"], "model": "gpt-4.1-mini", "temperature": 0.7, "limit_references": 5, "live": 1 }'import requests url = 'https://api.asksage.ai/server/query' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = { 'message': 'What is Ask Sage?', 'persona': 1, 'dataset': ['dataset1', 'dataset2'], 'model': 'gpt-4.1-mini', 'temperature': 0.7, 'limit_references': 5, 'live': 1 } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/query', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ message: 'What is Ask Sage?', persona: 1, dataset: ['dataset1', 'dataset2'], model: 'gpt-4.1-mini', temperature: 0.7, limit_references: 5, live: 1 }) }); const data = await response.json(); console.log(data); ``` ### Follow-Up Questions Generate contextual follow-up questions based on conversation history. POST /server/follow-up-questions ```bash curl -X POST 'https://api.asksage.ai/server/follow-up-questions' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{ "message": [ {"user": "me", "message": "What is Ask Sage?"} ], "model": "gpt-4.1-mini", "dataset": "none" }'import requests url = 'https://api.asksage.ai/server/follow-up-questions' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = { 'message': [ {'user': 'me', 'message': 'What is Ask Sage?'} ], 'model': 'gpt-4.1-mini', 'dataset': 'none' } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/follow-up-questions', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ message: [ {user: 'me', message: 'What is Ask Sage?'} ], model: 'gpt-4.1-mini', dataset: 'none' }) }); const data = await response.json(); console.log(data); ``` ### Get Available Models Retrieve the list of AI models available to your account. POST /server/get-models ```bash curl -X POST 'https://api.asksage.ai/server/get-models' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/server/get-models' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers) print(response.json())const response = await fetch('https://api.asksage.ai/server/get-models', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } }); const data = await response.json(); console.log(data); ``` ### Get Personas Retrieve the list of available AI personas. POST /server/get-personas ```bash curl -X POST 'https://api.asksage.ai/server/get-personas' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/server/get-personas' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers) print(response.json())const response = await fetch('https://api.asksage.ai/server/get-personas', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } }); const data = await response.json(); console.log(data); ``` ### Files & Datasets ### Upload File Upload a file for AI analysis. Supports PDF, DOCX, TXT, images, and more. POST /server/file ```bash curl -X POST 'https://api.asksage.ai/server/file' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: multipart/form-data' \ -F 'file=@/path/to/file.pdf'import requests url = 'https://api.asksage.ai/server/file' headers = { 'x-access-tokens': 'your_access_token' } files = { 'file': open('/path/to/file.pdf', 'rb') } response = requests.post(url, headers=headers, files=files) print(response.json())import FormData from 'form-data'; import fs from 'fs'; const form = new FormData(); form.append('file', fs.createReadStream('/path/to/file.pdf')); const response = await fetch('https://api.asksage.ai/server/file', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', ...form.getHeaders() }, body: form }); const data = await response.json(); console.log(data); ``` ### Train Dataset Add content to a dataset for training purposes. POST /server/train ```bash curl -X POST 'https://api.asksage.ai/server/train' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{ "context": "Product documentation", "content": "Your content here...", "summarize": true, "summarize_model": "gpt-4.1-mini", "force_dataset": "user_custom_123_MyDataset_content" }'import requests url = 'https://api.asksage.ai/server/train' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = { 'context': 'Product documentation', 'content': 'Your content here...', 'summarize': True, 'summarize_model': 'gpt-4.1-mini', 'force_dataset': 'user_custom_123_MyDataset_content' } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/train', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ context: 'Product documentation', content: 'Your content here...', summarize: true, summarize_model: 'gpt-4.1-mini', force_dataset: 'user_custom_123_MyDataset_content' }) }); const data = await response.json(); console.log(data); ``` ### List Datasets Retrieve all datasets available to your account. POST /server/get-datasets ```bash curl -X POST 'https://api.asksage.ai/server/get-datasets' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/server/get-datasets' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers) print(response.json())const response = await fetch('https://api.asksage.ai/server/get-datasets', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } }); const data = await response.json(); console.log(data); ``` ### Agents ### Execute Agent Execute an AI agent with a message and optional variables. Supports non-streaming, streaming, and file-upload modes. POST /server/execute-agent ```bash # Non-streaming request curl -X POST 'https://api.asksage.ai/server/execute-agent' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{ "agent_id": 1, "message": "What are the latest billing updates?", "streaming": false, "variables": { "priority": "high" } }' # Streaming request curl -X POST 'https://api.asksage.ai/server/execute-agent' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -N \ -d '{ "agent_id": 1, "message": "Summarize this quarter'\''s performance", "streaming": true }' # With file upload (multipart/form-data) curl -X POST 'https://api.asksage.ai/server/execute-agent' \ -H 'x-access-tokens: your_access_token' \ -F 'agent_id=1' \ -F 'message=Analyze this document' \ -F 'streaming=false' \ -F 'variables={"my_file_var": "report.pdf"}' \ -F 'file=@report.pdf'import requests import json # Non-streaming request url = 'https://api.asksage.ai/server/execute-agent' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = { 'agent_id': 1, 'message': 'What are the latest billing updates?', 'streaming': False, 'variables': { 'priority': 'high' } } response = requests.post(url, headers=headers, json=data) result = response.json() print(result['response']['response']) # Streaming request data['streaming'] = True response = requests.post(url, headers=headers, json=data, stream=True) for line in response.iter_lines(): if line: event = json.loads(line) print(f"Event: {event['event']}", event.get('data', '')) # With file upload files = {'file': open('report.pdf', 'rb')} form_data = { 'agent_id': '1', 'message': 'Analyze this document', 'streaming': 'false', 'variables': json.dumps({'my_file_var': 'report.pdf'}) } response = requests.post( url, headers={'x-access-tokens': 'your_access_token'}, data=form_data, files=files ) print(response.json())// Non-streaming request const response = await fetch('https://api.asksage.ai/server/execute-agent', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_id: 1, message: 'What are the latest billing updates?', streaming: false, variables: { priority: 'high' } }) }); const result = await response.json(); console.log(result.response.response); // Streaming request const streamResponse = await fetch('https://api.asksage.ai/server/execute-agent', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_id: 1, message: 'Summarize this quarter\'s performance', streaming: true }) }); const reader = streamResponse.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const text = decoder.decode(value); const events = text.split('\n').filter(line => line.trim()); for (const eventStr of events) { const event = JSON.parse(eventStr); console.log(`Event: ${event.event}`, event.data); } } ``` ### User Management ### Get Login History Retrieve login history for your account. POST /user/get-user-logins ```bash curl -X POST 'https://api.asksage.ai/user/get-user-logins' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json' \ -d '{"limit": 5}'import requests url = 'https://api.asksage.ai/user/get-user-logins' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } data = {'limit': 5} response = requests.post(url, headers=headers, json=data) if response.status_code == 200: print('Success:', response.json()) else: print('Error:', response.json())const response = await fetch('https://api.asksage.ai/user/get-user-logins', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({ limit: 5 }) }); const data = await response.json(); console.log(data); ``` ### Get Chat History Retrieve your chat session history. POST /user/get-chats ```bash curl -X POST 'https://api.asksage.ai/user/get-chats' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/user/get-chats' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers, json={}) if response.status_code == 200: print('Success:', response.json()) else: print('Error:', response.json())const response = await fetch('https://api.asksage.ai/user/get-chats', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({}) }); const data = await response.json(); console.log(data); ``` ### Get Usage Logs Retrieve your API usage logs. POST /user/get-user-logs ```bash curl -X POST 'https://api.asksage.ai/user/get-user-logs' \ -H 'x-access-tokens: your_access_token' \ -H 'Content-Type: application/json'import requests url = 'https://api.asksage.ai/user/get-user-logs' headers = { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' } response = requests.post(url, headers=headers, json={}) if response.status_code == 200: print('Success:', response.json()) else: print('Error:', response.json())const response = await fetch('https://api.asksage.ai/user/get-user-logs', { method: 'POST', headers: { 'x-access-tokens': 'your_access_token', 'Content-Type': 'application/json' }, body: JSON.stringify({}) }); const data = await response.json(); console.log(data); ``` ---------------- **Important Note:** Base URLs may vary depending on your environment. For assistance, please contact us at [support@asksage.ai](mailto:support@asksage.ai). --- # Python Client Source: /docs/v2/api-documentation/ask-sage-python-client.html # Ask Sage Python Client A powerful, easy-to-use Python library for seamless Ask Sage API integration ---------------- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. ---------------- ## Overview ### Pythonic Access to Ask Sage The Ask Sage Python Client provides a comprehensive, Pythonic interface to the Ask Sage API. Build AI-powered applications with minimal code while maintaining full control over advanced features. **Quick Install:** `pip install asksageclient` ---------------- ## Available Methods ### Client Method Reference The client exposes methods covering models, queries, training, datasets, plugins/agents, and usage tracking: | Method | Description | | --- | --- | | `get_models()` | Retrieve all available AI models | | `query()` | Send queries to AI models with full customization | | `query_with_file()` | Query with file attachments for context | | `train()` | Add content to your knowledge base | | `train_with_file()` | Train using file uploads | | `file()` | Upload and process files | | `add_dataset()` | Create new datasets | | `delete_dataset()` | Remove datasets | | `assign_dataset()` | Assign datasets to users | | `get_datasets()` | List all available datasets | | `get_personas()` | Retrieve available AI personas | | `get_plugins()` | List available plugins/agents | | `query_plugin()` | Execute queries using specific plugins | | `execute_plugin()` | Run plugins with custom content | | `follow_up_questions()` | Generate contextual follow-up questions | | `tokenizer()` | Calculate token counts for content | | `get_user_logs()` | Retrieve user activity logs | | `get_user_logins()` | Get user login history | | `count_monthly_tokens()` | Track monthly token usage | | `count_monthly_teach_tokens()` | Monitor training token consumption | ---------------- ## Example Notebook ### Interactive Tutorial Explore a comprehensive Jupyter notebook with examples and best practices for the Python client: [Open Example Notebook Walk through real Python client usage end-to-end on GitHub →](https://github.com/Ask-Sage/AskSage-Open-Source-Community/blob/main/examples/ex_1_api_endpoints/asksage_python_client_overview.ipynb) ---------------- ## Quick Start Guide ### Installation Install the Ask Sage Python Client using pip: ```bash pip install asksageclient ``` **Documentation:** Full package reference is available on [PyPI](https://pypi.org/project/asksageclient/). **Default Base URL — Update for Your Tenant:** Out of the box, `asksageclient` points at the `api.asksage.ai` instance. If your organization uses a different Ask Sage tenant, you **must** override the base URLs when initializing the client so requests are routed to the instance you authenticate against. Always use the instance approved by your organization and applicable regulatory requirements. Pass the matching URLs via the `user_base_url` and `server_base_url` arguments shown in **Step 2** below (for example, `user_base_url='https://api..ai/user'` and `server_base_url='https://api..ai/server'`). The `api.` prefix and `/user/` / `/server/` suffix stay the same — only the instance segment changes. ### Step 1 — Create Credentials File Create a JSON file with your API credentials: ```json { "credentials": { "api_key": "YOUR_API_KEY", "Ask_sage_user_info": { "username": "your.email@example.com" } } } ``` **Security:** Never commit credentials to version control. Add `credentials.json` to your `.gitignore` file. ### Step 2 — Initialize the Client Load credentials and create an Ask Sage client instance: ```python import json from asksageclient import AskSageClient # Load credentials from file def load_credentials(filename): """Load API credentials from JSON file.""" try: with open(filename) as file: return json.load(file) except FileNotFoundError: raise FileNotFoundError(f"Credentials file '{filename}' not found.") except json.JSONDecodeError: raise ValueError("Invalid JSON in credentials file.") # Initialize credentials credentials = load_credentials('credentials.json') api_key = credentials['credentials']['api_key'] email = credentials['credentials']['Ask_sage_user_info']['username'] # Create Ask Sage client client = AskSageClient( email=email, api_key=api_key, user_base_url='https://api.asksage.ai/user', # Optional: User API base URL server_base_url='https://api.asksage.ai/server' # Optional: Server API base URL ) print("Ask Sage client initialized successfully!") ``` ---------------- ## Additional Resources ### Where to Go Next [PyPI Package Versions, install instructions, and the latest release notes →](https://pypi.org/project/asksageclient/) [GitHub Repository Source code, sample notebooks, and community examples →](https://github.com/Ask-Sage/AskSage-Open-Source-Community) **Pro Tip:** Join the community to stay updated on new features, best practices, and to get help from other developers. --- # OpenAI-Style Endpoints Source: /docs/v2/api-documentation/OpenAI-Compatibility-Guide.html # OpenAI Compatibility Guide Seamlessly integrate Ask Sage using the standard OpenAI API format ---------------- **Important Note:** Base URLs may vary depending on your environment. For assistance, please contact us at [support@asksage.ai](mailto:support@asksage.ai). **Instance-Specific Base URL:** The base URL shown reflects the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against. ---------------- ## What's New? ### OpenAI Message Format Support Ask Sage now supports the **OpenAI message format**, making it incredibly easy to: **Easy Migration:** Switch from OpenAI to Ask Sage with minimal code changes. **Standard Format:** Use the same API format and patterns as OpenAI. **Familiar Interface:** Leverage the standard OpenAI API format you already know. **Responses API:** Use the newer OpenAI Responses API for stateful, tool-rich conversations. **Embeddings:** Generate vector embeddings via the standard `/embeddings` endpoint. ---------------- OpenAI-Compatible Endpoints ## Chat Completions ### Create a Chat Completion POST https://api.asksage.ai/server/openai/v1/chat/completions The main endpoint for conversational AI using the standard OpenAI format. **Authentication:** Use a Bearer token in the `Authorization` header. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | | `model` | string | Required | The AI model to use (e.g., `gpt-4.1-mini`, `claude-35-sonnet`) | | `messages` | array | Required | Array of message objects with `role` (`system`/`user`/`assistant`) and `content` | | `temperature` | number | Optional | Controls randomness (0.0–2.0). Default: 1.0 | | `max_tokens` | integer | Optional | Maximum number of tokens to generate | | `top_p` | number | Optional | Nucleus sampling parameter (0.0–1.0). Default: 1.0 | | `frequency_penalty` | number | Optional | Reduces likelihood of repeating tokens (-2.0 to 2.0). Default: 0.0 | | `presence_penalty` | number | Optional | Increases likelihood of new topics (-2.0 to 2.0). Default: 0.0 | | `tools` | array | Optional | Array of tool/function definitions for function calling | | `tool_choice` | string | Optional | `"none"`, `"auto"`, or specific tool. Default: `"auto"` | #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `id`, `object` (`chat.completion`), `created`, `model`, `choices` (with `index`, `message`, `finish_reason`), and `usage` | | `400 Error` | Invalid request format or missing required parameters | | `401 Error` | Authentication failure — invalid or missing API key | #### Example: Basic Chat Completion ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/chat/completions' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-4.1-mini", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is Ask Sage?"} ] }'import requests url = 'https://api.asksage.ai/server/openai/v1/chat/completions' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'gpt-4.1-mini', 'messages': [ {'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': 'What is Ask Sage?'} ] } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/openai/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'gpt-4.1-mini', messages: [ {role: 'system', content: 'You are a helpful assistant.'}, {role: 'user', content: 'What is Ask Sage?'} ] }) }); const data = await response.json(); console.log(data); ``` #### Example: Multi-Turn Conversation ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/chat/completions' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-4.1-mini", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "My name is Alice."}, {"role": "assistant", "content": "Nice to meet you, Alice!"}, {"role": "user", "content": "What'\''s my name?"} ], "temperature": 0.3 }'import requests url = 'https://api.asksage.ai/server/openai/v1/chat/completions' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'gpt-4.1-mini', 'messages': [ {'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': 'My name is Alice.'}, {'role': 'assistant', 'content': 'Nice to meet you, Alice!'}, {'role': 'user', 'content': "What's my name?"} ], 'temperature': 0.3 } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/openai/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'gpt-4.1-mini', messages: [ {role: 'system', content: 'You are a helpful assistant.'}, {role: 'user', content: 'My name is Alice.'}, {role: 'assistant', content: 'Nice to meet you, Alice!'}, {role: 'user', content: "What's my name?"} ], temperature: 0.3 }) }); const data = await response.json(); console.log(data); ``` #### Example: Function Calling **Tip:** Function calling enables the model to call external functions or tools to retrieve information. ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/chat/completions' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-4.1-mini", "messages": [ {"role": "user", "content": "What'\''s the weather like in San Francisco?"} ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather in a location", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location"] } } } ], "tool_choice": "auto" }'import requests url = 'https://api.asksage.ai/server/openai/v1/chat/completions' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'gpt-4.1-mini', 'messages': [ {'role': 'user', 'content': "What's the weather like in San Francisco?"} ], 'tools': [ { 'type': 'function', 'function': { 'name': 'get_weather', 'description': 'Get the current weather in a location', 'parameters': { 'type': 'object', 'properties': { 'location': {'type': 'string', 'description': 'The city and state, e.g. San Francisco, CA'}, 'unit': {'type': 'string', 'enum': ['celsius', 'fahrenheit']} }, 'required': ['location'] } } } ], 'tool_choice': 'auto' } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ---------------- ## Responses API ### Create a Response POST https://api.asksage.ai/server/openai/v1/responses OpenAI's Responses API — the newer, more flexible endpoint for stateful conversations, advanced tool use, custom tool types, and richer output formats (including reasoning). Use this when your client SDK calls `client.responses.create(...)` instead of `client.chat.completions.create(...)`. **Authentication:** Use a Bearer token in the `Authorization` header. **When to use Responses vs Chat Completions:** Use `/responses` if your OpenAI SDK client targets the Responses API (e.g. `client.responses.create`), if you need built-in tool types such as `web_search` or `custom`, or if you want server-side reasoning output. For most existing integrations, `/chat/completions` remains the right choice. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | | `model` | string | Required | The AI model to use (e.g., `gpt-5`, `gpt-4.1-mini`) | | `input` | string or array | Required | A plain string prompt, or an array of input items in the OpenAI Responses API format | | `instructions` | string | Optional | System-style instructions prepended to the conversation | | `tools` | array | Optional | Tool definitions — supports `function`, `web_search`, and `custom` types | | `tool_choice` | string or object | Optional | `"none"`, `"auto"`, `"required"`, or a specific tool object | | `temperature` | number | Optional | Controls randomness (0.0–2.0). Default: 1.0 | | `max_output_tokens` | integer | Optional | Maximum number of output tokens to generate | | `stream` | boolean | Optional | If `true`, returns a Server-Sent Events stream. Default: `false` | | `reasoning` | object | Optional | Reasoning controls for models that support it (e.g., effort level) | | `metadata` | object | Optional | Arbitrary key-value metadata attached to the request | #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `id`, `object` (`response`), `created_at`, `model`, `output` (array of text/tool-call/reasoning items), `usage` (`input_tokens`, `output_tokens`, `total_tokens`), and `status` (`completed`) | | `400 Error` | Invalid request format or missing required parameters | | `401 Error` | Authentication failure — invalid or missing API key | | `429 Error` | Token quota exceeded for the user / plan | #### Example: Basic Response ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/responses' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "input": "Summarize what Ask Sage is in two sentences." }'from openai import OpenAI client = OpenAI( base_url="https://api.asksage.ai/server/openai/v1", api_key="YOUR_API_KEY", ) response = client.responses.create( model="gpt-5", input="Summarize what Ask Sage is in two sentences.", ) print(response.output_text)import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.asksage.ai/server/openai/v1', apiKey: 'YOUR_API_KEY', }); const response = await client.responses.create({ model: 'gpt-5', input: 'Summarize what Ask Sage is in two sentences.', }); console.log(response.output_text); ``` #### Example: Responses with Tools ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/responses' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "input": "What is the weather in Washington DC today?", "tools": [ { "type": "function", "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": {"type": "string"} }, "required": ["location"] } } ], "tool_choice": "auto" }'from openai import OpenAI client = OpenAI( base_url="https://api.asksage.ai/server/openai/v1", api_key="YOUR_API_KEY", ) response = client.responses.create( model="gpt-5", input="What is the weather in Washington DC today?", tools=[{ "type": "function", "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"], }, }], tool_choice="auto", ) print(response.output) ``` ---------------- ## Embeddings ### Create Embeddings POST https://api.asksage.ai/server/openai/v1/embeddings Generate vector embeddings using the standard OpenAI embeddings format. Works as a drop-in for `client.embeddings.create(...)` in the OpenAI Python and JavaScript SDKs. **Authentication:** Use a Bearer token in the `Authorization` header. **Supported Models:** `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`. Other model names fall back to the tenant's default embedding engine. **Input Limits:** Maximum 256 inputs per request. Input may be a single string or an array of strings. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | | `model` | string | Optional | Embedding model to use. Default: `text-embedding-3-small` | | `input` | string or array | Required | The text to embed — a single string or an array of strings (max 256 items) | #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `object` (`list`), `data` (array of `{object: "embedding", index, embedding: float[]}` items), `model`, and `usage` (`prompt_tokens`, `total_tokens`) | | `400 Error` | Invalid input format, empty input, or more than 256 inputs | | `401 Error` | Authentication failure — invalid or missing API key | | `429 Error` | Token quota exceeded for the user / plan | #### Example: Single Input ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/embeddings' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "text-embedding-3-small", "input": "Ask Sage is a federally focused AI platform." }'from openai import OpenAI client = OpenAI( base_url="https://api.asksage.ai/server/openai/v1", api_key="YOUR_API_KEY", ) response = client.embeddings.create( model="text-embedding-3-small", input="Ask Sage is a federally focused AI platform.", ) print(response.data[0].embedding[:8]) # first 8 floats print("total tokens:", response.usage.total_tokens)import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.asksage.ai/server/openai/v1', apiKey: 'YOUR_API_KEY', }); const response = await client.embeddings.create({ model: 'text-embedding-3-small', input: 'Ask Sage is a federally focused AI platform.', }); console.log(response.data[0].embedding.slice(0, 8)); console.log('total tokens:', response.usage.total_tokens); ``` #### Example: Batch Inputs ```bash curl -X POST 'https://api.asksage.ai/server/openai/v1/embeddings' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "text-embedding-3-small", "input": [ "Ask Sage is a federally focused AI platform.", "It provides secure AI tools for government agencies.", "Users can query documents and datasets with natural language." ] }'from openai import OpenAI client = OpenAI( base_url="https://api.asksage.ai/server/openai/v1", api_key="YOUR_API_KEY", ) texts = [ "Ask Sage is a federally focused AI platform.", "It provides secure AI tools for government agencies.", "Users can query documents and datasets with natural language.", ] response = client.embeddings.create( model="text-embedding-3-small", input=texts, ) for item in response.data: print(f"[{item.index}] {item.embedding[:4]}...") # first 4 floats ``` ---------------- ## List Available Models ### List Models GET https://api.asksage.ai/server/openai/v1/models Retrieve a list of all available AI models in OpenAI format. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `object: "list"` and `data` array of model objects with `id`, `object`, `created`, `owned_by` | | `401 Error` | Authentication failure | #### Example ```bash curl -X GET 'https://api.asksage.ai/server/openai/v1/models' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: application/json'import requests url = 'https://api.asksage.ai/server/openai/v1/models' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json' } response = requests.get(url, headers=headers) print(response.json())const response = await fetch('https://api.asksage.ai/server/openai/v1/models', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json' } }); const data = await response.json(); console.log(data); ``` ---------------- ## How It Works ### Same Pattern as OpenAI Ask Sage's `openai/v1/*` endpoints follow the exact same API specification as OpenAI, making integration seamless. You can use Ask Sage's API with the same request/response patterns you're familiar with from OpenAI. Simply point your requests to Ask Sage's base URL with Bearer token authentication. **Key Difference:** Instead of using OpenAI's base URL (`https://api.openai.com/v1`), use Ask Sage's base URL (`https://api.asksage.ai/server/openai/v1`). #### Example: Making Requests ```bash # Ask Sage API (OpenAI-compatible format) curl -X POST 'https://api.asksage.ai/server/openai/v1/chat/completions' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-4.1-mini", "messages": [ {"role": "user", "content": "Hello!"} ] }'import requests # Ask Sage API (OpenAI-compatible format) url = 'https://api.asksage.ai/server/openai/v1/chat/completions' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'gpt-4.1-mini', 'messages': [ {'role': 'user', 'content': 'Hello!'} ] } response = requests.post(url, headers=headers, json=data) print(response.json())// Ask Sage API (OpenAI-compatible format) const response = await fetch('https://api.asksage.ai/server/openai/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'gpt-4.1-mini', messages: [ {role: 'user', content: 'Hello!'} ] }) }); const data = await response.json(); console.log(data); ``` **Same Patterns:** Use the same request structure, parameters, and response formats you're already familiar with from OpenAI. ---------------- ## Migration Guide ### Key Benefits **Easy Migration:** Minimal code changes to switch from OpenAI to Ask Sage. **Familiar Patterns:** Use the same API patterns and structure as OpenAI. --- # Anthropic-Style Endpoints Source: /docs/v2/api-documentation/Anthropic-Compatibility-Guide.html # Anthropic Compatibility Guide Use the Anthropic Messages API format with Ask Sage — works with Claude Code out of the box ---------------- **Important Note:** Base URLs may vary depending on your environment. For assistance, please contact us at [support@asksage.ai](mailto:support@asksage.ai). **Instance-Specific Base URL:** The base URL shown reflects the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against. ---------------- ## What's New? ### Anthropic Messages API Support Ask Sage now supports the **Anthropic Messages API format**, making it easy to: **Claude Code Integration:** Connect Claude Code directly to Ask Sage with minimal configuration. **Standard Format:** Use the same Messages API format and patterns as Anthropic. **Model Flexibility:** Access Claude models via AWS Bedrock and Google Vertex AI backends. ---------------- Anthropic-Compatible Endpoints ## Messages ### Create a Message POST https://api.asksage.ai/server/anthropic/v1/messages The main endpoint for creating messages using the standard Anthropic format. Requests are routed to AWS Bedrock or Google Vertex AI based on the resolved model. **Authentication:** Use a Bearer token in the `Authorization` header, or pass your token via `x-access-tokens` or `x-api-key`. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | | `model` | string | Required | Claude model — see [naming formats](#model-naming-formats) below | | `messages` | array | Required | Array of message objects with `role` (`user`/`assistant`) and `content` | | `system` | string or array | Optional | System prompt — string or array of content blocks with optional cache control | | `max_tokens` | integer | Required | Maximum number of tokens to generate | | `temperature` | number | Optional | Controls randomness (0.0–1.0). Default: 1.0 | | `tools` | array | Optional | Array of tool definitions for function calling | | `tool_choice` | object | Optional | `{"type": "auto"}`, `{"type": "any"}`, or `{"type": "tool", "name": "..."}` | #### Model Naming Formats {#model-naming-formats} The `model` field accepts multiple naming formats: - **Simple names:** `sonnet`, `opus`, `haiku` - **Date-suffixed:** `claude-sonnet-4-5-20250929`, `claude-opus-4-8-default`, `claude-opus-4-7-default`, `claude-opus-4-6-default` - **Vertex format:** `claude-sonnet-4-5@20250929`, `claude-opus-4-8@default`, `claude-opus-4-7@default` - **AskSage format:** `google-claude-48-opus`, `google-claude-47-opus`, `google-claude-45-sonnet`, `aws-bedrock-claude-45-sonnet-gov` #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `id`, `type`, `role`, `model`, `content` (array of `text`/`tool_use` blocks), `stop_reason` (`end_turn`/`max_tokens`/`tool_use`), and `usage` (`input_tokens`, `output_tokens`) | | `400 Error` | Invalid request format or missing required parameters | | `401 Error` | Authentication failure — invalid or missing API key | | `429 Error` | Rate limit exceeded — retry after a moment | #### Example: Basic Message ```bash curl -X POST 'https://api.asksage.ai/server/anthropic/v1/messages' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 1024, "messages": [ {"role": "user", "content": "What is Ask Sage?"} ] }'import requests url = 'https://api.asksage.ai/server/anthropic/v1/messages' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'claude-sonnet-4-5-20250929', 'max_tokens': 1024, 'messages': [ {'role': 'user', 'content': 'What is Ask Sage?'} ] } response = requests.post(url, headers=headers, json=data) print(response.json())const response = await fetch('https://api.asksage.ai/server/anthropic/v1/messages', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'claude-sonnet-4-5-20250929', max_tokens: 1024, messages: [ {role: 'user', content: 'What is Ask Sage?'} ] }) }); const data = await response.json(); console.log(data); ``` #### Example: Multi-Turn Conversation with System Prompt ```bash curl -X POST 'https://api.asksage.ai/server/anthropic/v1/messages' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 1024, "system": "You are a helpful cybersecurity assistant.", "messages": [ {"role": "user", "content": "What is zero trust architecture?"}, {"role": "assistant", "content": "Zero trust is a security framework that requires all users to be authenticated and authorized before accessing resources."}, {"role": "user", "content": "How does it apply to cloud environments?"} ] }'import requests url = 'https://api.asksage.ai/server/anthropic/v1/messages' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'claude-sonnet-4-5-20250929', 'max_tokens': 1024, 'system': 'You are a helpful cybersecurity assistant.', 'messages': [ {'role': 'user', 'content': 'What is zero trust architecture?'}, {'role': 'assistant', 'content': 'Zero trust is a security framework that requires all users to be authenticated and authorized before accessing resources.'}, {'role': 'user', 'content': 'How does it apply to cloud environments?'} ] } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` #### Example: Function Calling **Tip:** Tool use enables the model to call external functions to retrieve information or perform actions. ```bash curl -X POST 'https://api.asksage.ai/server/anthropic/v1/messages' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 1024, "messages": [ {"role": "user", "content": "What'\''s the weather like in San Francisco?"} ], "tools": [ { "name": "get_weather", "description": "Get the current weather in a location", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location"] } } ] }'import requests url = 'https://api.asksage.ai/server/anthropic/v1/messages' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'claude-sonnet-4-5-20250929', 'max_tokens': 1024, 'messages': [ {'role': 'user', 'content': "What's the weather like in San Francisco?"} ], 'tools': [ { 'name': 'get_weather', 'description': 'Get the current weather in a location', 'input_schema': { 'type': 'object', 'properties': { 'location': {'type': 'string', 'description': 'The city and state, e.g. San Francisco, CA'}, 'unit': {'type': 'string', 'enum': ['celsius', 'fahrenheit']} }, 'required': ['location'] } } ] } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ---------------- ## Token Counting ### Count Input Tokens POST https://api.asksage.ai/server/anthropic/v1/messages/count_tokens Count the number of input tokens for a message payload before sending the full request. Useful for context-window management. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | string (header) | Required | Bearer token: `Bearer YOUR_API_KEY` | | `model` | string | Required | The Claude model to count tokens for | | `messages` | array | Required | Array of message objects (same format as Messages endpoint) | #### Response | Field | Type | Description | | --- | --- | --- | | `input_tokens` | integer | Number of input tokens in the request | #### Example ```bash curl -X POST 'https://api.asksage.ai/server/anthropic/v1/messages/count_tokens' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "model": "claude-sonnet-4-5-20250929", "messages": [ {"role": "user", "content": "Hello, how are you?"} ] }'import requests url = 'https://api.asksage.ai/server/anthropic/v1/messages/count_tokens' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'model': 'claude-sonnet-4-5-20250929', 'messages': [ {'role': 'user', 'content': 'Hello, how are you?'} ] } response = requests.post(url, headers=headers, json=data) print(response.json()) # {"input_tokens": 12} ``` ---------------- ## Claude Code Integration ### Connect Claude Code to Ask Sage Ask Sage's Anthropic endpoint is fully compatible with **Claude Code**. Connect your Claude Code CLI or VS Code extension to Ask Sage with minimal configuration. #### Method 1 — Settings File (Recommended) Create or edit `~/.claude/settings.json`: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.asksage.ai/server/anthropic", "ANTHROPIC_AUTH_TOKEN": "your-asksage-token-here", "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 4096, "MAX_THINKING_TOKENS": 1024 }, "permissions": { "allow": ["*"], "deny": ["Delete"] } } ``` **Note:** `CLAUDE_CODE_MAX_OUTPUT_TOKENS` must be greater than `MAX_THINKING_TOKENS`. Anthropic recommends setting these values when using AWS Bedrock Claude 4.5 Sonnet (default) due to burndown throttling. #### Method 2 — Environment Variables Export variables in your terminal before launching Claude Code: ```bash export ANTHROPIC_BASE_URL="https://api.asksage.ai/server/anthropic" export ANTHROPIC_API_KEY="your-asksage-token-here" ``` **VS Code Extension:** The VS Code extension requires Method 2 (environment variables) — there is no built-in way to set them within the extension settings. ---------------- ## Available Models ### Supported Claude Models | Model | Provider | Capability | | --- | --- | --- | | `claude-sonnet-4-5-20250929` | AWS Bedrock (Gov) | Default — balanced speed and quality | | `claude-opus-4-8-default` | Google Vertex AI | Most capable — coding, agents, enterprise workflows | | `claude-opus-4-7-default` | Google Vertex AI | Previous generation Opus — still available | | `claude-opus-4-6-default` | Google Vertex AI | Previous generation Opus — complex reasoning | | `claude-opus-4-5-20251101` | Google Vertex AI | Previous generation Opus | | `claude-sonnet-4-6-default` | Google Vertex AI | Latest Sonnet via Vertex | | `claude-haiku-4-5-20251001` | Google Vertex AI | Fastest — lightweight tasks | **Intelligent Fallback:** If the requested model is unavailable on your account, Ask Sage automatically falls back to the best available model in the same capability tier. ---------------- ## How It Works ### Request Flow Ask Sage's `anthropic/v1/*` endpoints follow the Anthropic Messages API specification, making integration seamless. 1. Your application sends a request to `https://api.asksage.ai/server/anthropic/v1/messages` 2. Ask Sage validates your authentication token 3. The model name is resolved and routed to the appropriate backend (AWS Bedrock or Google Vertex AI) 4. The response is returned in standard Anthropic Messages API format **Key Difference:** Instead of using Anthropic's base URL (`https://api.anthropic.com`), use Ask Sage's base URL (`https://api.asksage.ai/server/anthropic`). **Full Compatibility:** Use the same request structure, parameters, and response formats you're already familiar with from the Anthropic API. ---------------- ## Supported Features ### Feature Coverage **Non-Streaming Responses:** Full message responses returned in a single payload. **Tool Use / Function Calling:** Define tools and let Claude call them during conversation. **System Prompts:** Set system-level instructions with optional cache control. **Multi-Turn Conversations:** Maintain context across multiple messages. **Token Counting:** Count input tokens before sending requests. **Beta Features:** Anthropic beta features supported via the `anthropic-beta` header. --- # Gemini-Style Endpoints Source: /docs/v2/api-documentation/Gemini-Compatibility-Guide.html # Gemini Compatibility Guide Use the Google Gemini API format with Ask Sage — powered by Vertex AI ---------------- **Important Note:** Base URLs may vary depending on your environment. For assistance, please contact us at [support@asksage.ai](mailto:support@asksage.ai). **Instance-Specific Base URL:** The base URL shown reflects the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL to the instance you authenticate against. ---------------- ## What's New? ### Google Gemini API Support Ask Sage now supports the **Google Gemini API format**, making it easy to: **Easy Migration:** Switch from Google AI Studio or Vertex AI to Ask Sage with minimal code changes. **Standard Format:** Use the same Gemini API format and patterns you already know. **Regional Failover:** Automatic regional failover across multiple US regions for high availability. ---------------- Gemini-Compatible Endpoints ## Generate Content ### Generate Content POST https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent The main endpoint for generating content using Gemini models. Requests are routed to Google Vertex AI with automatic regional failover. **Authentication:** Use `YOUR_API_KEY` in the `x-access-tokens` header. #### Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `x-access-tokens` | string (header) | Required | Authentication: `YOUR_API_KEY` | | `model` | string (URL path) | Required | Gemini model — see [naming formats](#model-naming-formats) below | | `contents` | array | Required | Array of content objects with `role` (`user`/`model`) and `parts` (text/inlineData/functionCall/functionResponse) | | `systemInstruction` | object | Optional | System-level instructions — object with `role` and `parts` fields | | `generationConfig` | object | Optional | `temperature`, `topP`, `topK`, `maxOutputTokens`, `candidateCount`, `stopSequences`, `responseMimeType`, `responseSchema` | | `tools` | array | Optional | Array of tool objects containing `functionDeclarations` for function calling | | `safetySettings` | array | Optional | Safety filter configuration per category | #### Model Naming Formats {#model-naming-formats} The `model` URL path supports multiple naming formats: - **Simple names:** `flash`, `pro` - **Standard:** `gemini-2.5-pro`, `gemini-2.5-flash` - **Preview versions:** `gemini-2.5-pro-preview-05-06`, `gemini-2.5-flash-preview-04-17` - **With prefix:** `models/gemini-2.5-pro` - **Vertex format:** `publishers/google/models/gemini-2.5-pro` #### Response | Status | Description | | --- | --- | | `200 Success` | Returns `candidates` (with `content`, `finishReason`, `safetyRatings`), `usageMetadata` (`promptTokenCount`, `candidatesTokenCount`, `totalTokenCount`), and `modelVersion` | | `400 Error` | Invalid request format or parameters | | `401 Error` | Authentication failure — invalid or missing API key | | `429 Error` | Rate limit exceeded — automatic regional failover will be attempted | #### Example: Basic Text Generation ```bash curl -X POST 'https://api.asksage.ai/server/google/v1beta/models/gemini-2.5-flash:generateContent' \ -H 'x-access-tokens: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ { "role": "user", "parts": [{"text": "What is Ask Sage?"}] } ] }'import requests model = 'gemini-2.5-flash' url = f'https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent' headers = { 'x-access-tokens': 'YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'contents': [ { 'role': 'user', 'parts': [{'text': 'What is Ask Sage?'}] } ] } response = requests.post(url, headers=headers, json=data) print(response.json())const model = 'gemini-2.5-flash'; const response = await fetch( `https://api.asksage.ai/server/google/v1beta/models/${model}:generateContent`, { method: 'POST', headers: { 'x-access-tokens': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ contents: [ { role: 'user', parts: [{text: 'What is Ask Sage?'}] } ] }) } ); const data = await response.json(); console.log(data); ``` #### Example: Multi-Turn Conversation with System Instruction ```bash curl -X POST 'https://api.asksage.ai/server/google/v1beta/models/gemini-2.5-pro:generateContent' \ -H 'x-access-tokens: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "systemInstruction": { "role": "user", "parts": [{"text": "You are a helpful cybersecurity assistant."}] }, "contents": [ {"role": "user", "parts": [{"text": "What is zero trust architecture?"}]}, {"role": "model", "parts": [{"text": "Zero trust is a security framework that requires all users to be authenticated and authorized before accessing resources."}]}, {"role": "user", "parts": [{"text": "How does it apply to cloud environments?"}]} ], "generationConfig": { "temperature": 0.3, "maxOutputTokens": 2048 } }'import requests model = 'gemini-2.5-pro' url = f'https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent' headers = { 'x-access-tokens': 'YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'systemInstruction': { 'role': 'user', 'parts': [{'text': 'You are a helpful cybersecurity assistant.'}] }, 'contents': [ {'role': 'user', 'parts': [{'text': 'What is zero trust architecture?'}]}, {'role': 'model', 'parts': [{'text': 'Zero trust is a security framework that requires all users to be authenticated and authorized before accessing resources.'}]}, {'role': 'user', 'parts': [{'text': 'How does it apply to cloud environments?'}]} ], 'generationConfig': { 'temperature': 0.3, 'maxOutputTokens': 2048 } } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` #### Example: Function Calling **Tip:** Gemini uses `functionDeclarations` within the `tools` array for function calling. ```bash curl -X POST 'https://api.asksage.ai/server/google/v1beta/models/gemini-2.5-flash:generateContent' \ -H 'x-access-tokens: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ {"role": "user", "parts": [{"text": "What'\''s the weather like in San Francisco?"}]} ], "tools": [ { "functionDeclarations": [ { "name": "get_weather", "description": "Get the current weather in a location", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location"] } } ] } ] }'import requests model = 'gemini-2.5-flash' url = f'https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent' headers = { 'x-access-tokens': 'YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'contents': [ {'role': 'user', 'parts': [{'text': "What's the weather like in San Francisco?"}]} ], 'tools': [ { 'functionDeclarations': [ { 'name': 'get_weather', 'description': 'Get the current weather in a location', 'parameters': { 'type': 'object', 'properties': { 'location': {'type': 'string', 'description': 'The city and state, e.g. San Francisco, CA'}, 'unit': {'type': 'string', 'enum': ['celsius', 'fahrenheit']} }, 'required': ['location'] } } ] } ] } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` #### Example: Structured JSON Output ```bash curl -X POST 'https://api.asksage.ai/server/google/v1beta/models/gemini-2.5-flash:generateContent' \ -H 'x-access-tokens: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ {"role": "user", "parts": [{"text": "List three cloud security best practices"}]} ], "generationConfig": { "responseMimeType": "application/json", "responseSchema": { "type": "object", "properties": { "practices": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string"}, "description": {"type": "string"} } } } } } } }'import requests model = 'gemini-2.5-flash' url = f'https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent' headers = { 'x-access-tokens': 'YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'contents': [ {'role': 'user', 'parts': [{'text': 'List three cloud security best practices'}]} ], 'generationConfig': { 'responseMimeType': 'application/json', 'responseSchema': { 'type': 'object', 'properties': { 'practices': { 'type': 'array', 'items': { 'type': 'object', 'properties': { 'name': {'type': 'string'}, 'description': {'type': 'string'} } } } } } } } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ---------------- ## Available Models ### Supported Gemini Models | Model | Provider | Capability | | --- | --- | --- | | `gemini-2.5-flash` | Google Vertex AI | Default — fast and efficient for most tasks | | `gemini-2.5-pro` | Google Vertex AI | Most capable — complex reasoning and analysis | **Intelligent Fallback:** If the requested model is unavailable on your account, Ask Sage automatically falls back to the best available model in the same capability tier. **Regional Failover:** Requests automatically fail over across 7 US regions (`us-central1`, `us-east1`, `us-east4`, `us-east5`, `us-south1`, `us-west1`, `us-west4`) for high availability on rate-limit or capacity errors. ---------------- ## How It Works ### Request Flow Ask Sage's `google/v1/*` endpoints follow the Google Gemini API specification, making integration seamless. 1. Your application sends a request to `https://api.asksage.ai/server/google/v1beta/models/{model}:generateContent` 2. Ask Sage validates your authentication token 3. The model name is resolved and the request is routed to Google Vertex AI 4. If a region hits rate limits, the request automatically retries in the next available region 5. The response is returned in standard Gemini API format **Key Difference:** Instead of using Google's Vertex AI endpoint directly, use Ask Sage's base URL (`https://api.asksage.ai/server/google/v1beta`) with `x-access-tokens` header authentication. #### Role Mapping Ask Sage automatically handles role normalization for convenience: | Input Role | Mapped To | Notes | | --- | --- | --- | | `user` | `user` | No change | | `model` | `model` | No change | | `assistant` | `model` | Automatically mapped for OpenAI compatibility | | `system` | `systemInstruction` | Extracted and merged into the system instruction field | **Full Compatibility:** Use the same request structure, parameters, and response formats you're already familiar with from the Google Gemini API. ---------------- ## Supported Features ### Feature Coverage **Text Generation:** Generate text with configurable temperature, top-p, and top-k. **Function Calling:** Define function declarations and let Gemini call them. **System Instructions:** Set system-level instructions to guide model behavior. **Multi-Turn Conversations:** Maintain context across multiple user/model exchanges. **Structured Output:** Get JSON responses conforming to a specified schema. **Safety Settings:** Configure safety filters per harm category. --- # Enterprise Accounts Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-account.html # Enterprise Account Manage users, tokens, and account settings in one centralized platform In this section, we will cover the `Enterprise Account` feature of the Ask Sage platform. The `Enterprise Account` feature is designed to cater to the needs of organizations and businesses that require a more comprehensive and scalable solution deploying and managing GenAI. By providing a centralized platform for managing multiple users, the `Enterprise Account` feature allows organizations to manage their `tokens` and users effectively, ensuring a seamless experience for all users. ![Ask Sage Admin Panel Dashboard](/assets/images/asksage-platform-v2-token-statistics-overview.png) Ask Sage Platform **Enterprise Solution** Ask Sage delivers a solution that is tailored to the needs of organizations and businesses, providing a scalable and comprehensive solution for deploying and managing GenAI. Table of Contents 1. TOC ## Obtaining an Enterprise Account Follow these steps to get an `Enterprise Account` on the Ask Sage platform. Doing so will expedite the process of getting an `Enterprise Account` and ensure that your organization can have a seamless experience with the Ask Sage platform. -------------------------------------------- 1. **Minimum of 2 Users**: An `Enterprise Account` is only available for organizations and businesses that have a minimum of 2 users. Otherwise, an individual subscription is recommended instead. 2. **All Users Need to Register An Account**: All users who will be part of the `Enterprise Account` need to register an account on the Ask Sage platform and agree to the terms and conditions. This is a mandatory requirement for all users who will be part of the `Enterprise Account`. 3. **Email Ask Sage Sales Team**: Once all users have registered an account on the Ask Sage platform, organizations need to email the Ask Sage sales team at [sales@asksage.ai](mailto:sales@asksage.ai) and request an `Enterprise Account`. In the email provide the following information: - **Organization Name**: The name of your organization (e.g., ABC Corp) - **Billing Address**: The billing address of your organization - **Emails of All Users**: The email addresses of all users who will be part of the `Enterprise Account` - **Emails of Admin Users**: The email addresses of the users who will be the admin of the `Enterprise Account` - Minimum of 1 admin user required - and there is no maximum limit on the number of admin users - **Token Request**: Visit: [Pricing & Sales](/docs/v2/asksage-sales.html) for resources on purchasing tokens. If you require additional tokens, please mention the number of tokens you require (in quantities of 2M). - Minimum of 200K tokens required, per user. - **Additional Information**: Any additional information that you would like to provide to the Ask Sage sales team. 4. **Payment**: Once the Ask Sage sales team has received your email, they will get in touch with you to discuss the payment terms and conditions. Once the payment has been made, your `Enterprise Account` will be activated. -------------------------------------------- ## Viewing the Admin Panel ### Administrator Access After successfully obtaining an `Enterprise Account` on the Ask Sage platform, administrators will be able to access the `Admin Panel` on the Ask Sage platform. Any user who has been designated as an admin user for the `Enterprise Account` will be required to setup multi-factor authentication (MFA) for their account. This is a mandatory requirement for all admin users who will be managing the `Enterprise Account`. **Note:** Until the admin user has setup MFA for their account, they will not be able to access the `Admin Panel`. To access the `Admin Panel`, follow these steps: #### Login to the Ask Sage Platform Go to the Ask Sage platform and login to your account. Navigate to the Admin Panel by clicking your account icon in the bottom of the left sidebar. If you are the administrator of the account you will see `Admin Panel` within the window that displays. ![Ask Sage Settings Navigation Menu](/assets/images/asksage-platform-v2-side-bar-menu-section-f.png) Ask Sage Settings Navigation **Security Requirement:** Admins are required to setup Multi-Factor Authentication (MFA) for their account to access the `Admin Panel`. #### Access the Admin Panel Once you have selected the `Admin Panel` option, you will be redirected to the Administrator Dashboard where you can manage your `Enterprise Account`. ![Ask Sage Enterprise Admin Panel](/assets/images/asksage-platform-v2-user-management-table.png) Ask Sage Enterprise Admin Panel ## Admin Panel Layout ### Admin Panel Sections The Admin Panel is divided into two sections: #### Management - **User Management** — View users, update paid/banned status, manage tokens - **Token Distribution** — Configure token allocation policies - **Token Requests** — Review pending token requests #### Analytics - **Token Statistics** — Token usage dashboards and CSV exports - **Activity Logs** — User interaction history and audit trail ### Responsive Behavior ### Mobile & Tablet On smaller screens (below 1200px), the sidebar collapses into a slide-out drawer: 1. A **hamburger menu** icon () appears in the top-left of the content header 2. Tap the icon to open the sidebar as an overlay drawer 3. Selecting a page automatically closes the drawer We will cover the following topics related to managing Organizations, Users, Models, and Tokens in the `Admin Panel` in the subsequent sections. --- # User Management Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-user-management.html # User Management Manage users and their access to the Ask Sage platform Table of Contents 1. TOC As an Administrator of an `Enterprise Account`, you have the ability to manage users and their access to the Ask Sage platform. This section covers how Administrators can effectively manage users and their access levels. ![Ask Sage Admin Panel User Management table](/assets/images/asksage-platform-v2-user-management-table.png) User Management **Pool-Only Billing:** If your organization has enabled the **Shared Token Pool** on the [Token Distribution](/docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-distribution) page, an alert banner reading *"Pool-only billing is on. Per-user token limits are ignored — the Max Inference Tokens column is shown for reference only"* appears at the top of the User Management table. In this mode, users draw directly from the org-wide pool and per-user token columns are informational only. ## Accessing User Account Information ### Finding a User To look up a specific user in the User Management tab: 1. Click the **Filter by email...** text box 2. Type the user's email address and press **Enter** or click **Apply** 3. The user's profile row will appear, displaying their current account details ## Summary Bar ### Organization Snapshot A row of summary pills above the table gives a real-time snapshot of the organization: - **Total Users** — the number of users in the organization - **Purchased Inference Tokens** — total inference tokens purchased for the organization - **Purchased Embedding Tokens** — total embedding tokens purchased for the organization - **Assigned Inference Tokens** — inference tokens currently assigned across all users - **Assigned Embedding Tokens** — embedding tokens currently assigned across all users ## User Table Columns Reference Each row in the User Management table includes the following information: ### Column Definitions | Column | Description | | --- | --- | | ID | User's unique identifier on the tenant | | Company | Company name associated with the user's organization | | First name / Last name | User's registered name | | Email | User's registered email address | | CAC | Whether the user has a CAC/PIV card registered (Yes/No) | | MFA | Whether multi-factor authentication is enabled (Yes/No) | | Type | The user's privilege level: **SuperAdmin** — full tenant access **Admin** — manages their organization exclusively via the admin portal **User** — no elevated privileges, cannot access admin portals | | Plan | The subscription plan the user is enrolled in | | Paid | Whether the user has access to paid features (Yes/No) | | Status | The account's current state — **Active** or **Disabled** | | Last Login | Date and time the user last logged in — displays "—" if the user has never logged in | | Verified | Email verification status — only applies to tenants that require email verification | | Max Inference Tokens | The monthly inference token allocation assigned to the user. Shown for reference only when the organization's Shared Token Pool is on. | | Max Embedding Tokens | The training/embedding token allocation assigned to the user. Shown for reference only when the organization's Shared Token Pool is on. | | Total Inference Tokens | Total inference tokens consumed by the user since the account was created | | Total Embedding Tokens | Total embedding/training tokens consumed by the user since the account was created | ## Activating and Disabling User Accounts **Prerequisite:** If you are an Administrator of an `Enterprise Account` and do not have access, check that you have setup multi-factor authentication (MFA) for your account. This is a mandatory requirement for all admin users who will be managing the `Enterprise Account`. ### Understanding Paid Status - `No`: User will not have access to paid features but will still be able to login - `Yes`: User will have access to the paid features of the Ask Sage platform **Automatic Token Assignment:** When a user is activated, they are automatically assigned a default volume of tokens (for example, 200K or 500K tokens), unless the organization's Shared Token Pool is on, in which case they draw from the shared pool instead. ![Ask Sage Admin Panel User Actions menu](/assets/images/asksage-platform-v2-user-actions-menu.png) User Account Actions Menu ## User Account Actions Menu Each user row has a context menu accessible by clicking the **three vertical dots** () to the left of the user's information. Available actions include: ### Available Actions | Action | Description | | --- | --- | | View Logs | Opens the user's interaction and activity history | | Remove Paid Status | Revokes paid feature access without disabling the account | | Disable Account | Blocks login access entirely | **Need something else?** Password resets, CAC/MFA resets, role changes, and org reassignment are handled by [support@asksage.ai](mailto:support@asksage.ai). ### Disabling Users ### User Disabling Process #### Reducing Access (Non-Paid Status) To disable a user and reduce their access, click the **three vertical dots** () to the left of the user and select `Remove Paid Status`. #### Blocking Login Entirely To completely block a user from logging in to the platform, click the **three vertical dots** () to the left of the user and select `Disable Account`. The user's **Status** column will change from `Active` to `Disabled`. **Re-enabling Access:** If tokens were assigned to the user, they can be reassigned to another user by Administrators. To restore access they will need to contact their Admin. **Data Retention:** User accounts cannot be completely deleted as all data needs to be retained for 3 years due to compliance regulations. --- # Analytics Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-account-metrics.html # Analytics View detailed metrics for your Enterprise Account and gain insights into token and user usage --- Table of contents 1. TOC --- Administrators have the ability to view detailed token usage metrics for their `Enterprise Account` on the **Token Statistics** page, found under **Analytics** in the Admin Panel sidebar. This section covers how Administrators can use these metrics to gain insights into token consumption trends and plan for future token purchases. ![Token Statistics page showing the Overview tab with pool allocation, burn rate, and monthly usage charts](/assets/images/asksage-platform-v2-token-statistics-overview.png) Token Statistics — Overview ## Date Range and Summary Cards ### Date Range Use the date range dropdown (e.g., *Last 12 months*) at the top of the page to control the window used by the charts and tables below. The selected range and its current status (e.g., "in progress" for the current month) are shown alongside the dropdown. Three summary cards give a real-time snapshot for the selected range: - **Inference Tokens** — total inference tokens consumed in the selected range, with percentage change versus the prior period - **Embedding Tokens** — total embedding/training tokens consumed in the selected range, with percentage change versus the prior period - **This month so far** — live combined inference + embedding token usage for the current calendar month ## Overview Tab ### Pool Health Cards The **Overview** tab surfaces a set of cards that describe the health of the organization's token pool for the current period: - **Inference pool allocated** — the percentage of purchased inference tokens currently assigned to users, with the raw totals shown below the percentage - **[Month] usage** — total inference tokens consumed so far in the current month, with percentage change versus the previous month - **Burn rate** — the average tokens consumed per day, trailing a recent window (e.g., ~60 days) - **Projected run-out** — the projected date the unallocated pool will be exhausted at the current burn rate - **[Month] projection** — a projected total for the current month based on pace so far, compared to the last complete month - **Assigned but unused** — tokens assigned to users that have not yet been consumed this month **Run-out Warning:** When the unallocated pool is projected to run out within the current period, a warning banner appears summarizing the remaining balance, burn rate, and projected run-out date. ### Monthly Charts and Top Consumers Below the pool health cards, monthly bar charts break down **Inference Tokens** and **Embedding Tokens** usage over the selected date range, with a dashed marker projecting the current month's total. Each chart is paired with a data table listing the exact monthly figures. ## Data & Exports Tab ### Monthly Token Usage Table The **Data & Exports** tab shows a **Monthly token usage** table with one row per calendar month, listing Inference Tokens, Embedding Tokens, and the combined Total for that period — making it easy to spot seasonal trends or sudden spikes in usage across the Enterprise Account. ![Token Statistics Data & Exports tab showing monthly usage table and export options](/assets/images/asksage-platform-v2-token-statistics-data-exports.png) Token Statistics — Data & Exports ### Export Options - **Export Token Usage CSV** (Export Data section) — downloads the full historical monthly token usage table as a CSV file, covering both inference and embedding token columns by period - **Download Users CSV** (Server exports — Users) — downloads every user account with profile, role, and status fields - **Download Users with Tokens CSV** (Server exports — Users with Tokens) — downloads user accounts along with their token assignments and usage, useful for audits or sharing usage reports with stakeholders ## Activity Logs ### User Logs Administrators can view the Activity Logs for each user in the Enterprise Account from the standalone **Activity Logs** page, found under **Analytics** in the Admin Panel sidebar. The Activity Logs provide a detailed history of the user's interactions on the platform, including the number of tokens consumed, the type of interactions, the date and time of interactions, IP address, and other relevant details. To access the Activity Logs for a specific user, click the three-dot menu to the left of that user in the User Management table and select **View Logs**. Each entry includes the prompt text (truncated), the model used, Prompt Tokens, Completion Tokens, Total Tokens for that interaction, and a Training flag indicating whether the response involved a dataset ingestion. **Tip:** **Use the three-dot menu -> View Logs** for a specific user to access detailed interaction history and token consumption details. --- # Token Management Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-management.html # Token Management Manage and distribute tokens for users on the Ask Sage platform Table of Contents 1. TOC Administrators have the ability to manage tokens for users on the Ask Sage platform. This section covers how Administrators can effectively manage and distribute tokens to users in their organization. ![Ask Sage User Management Table](/assets/images/asksage-platform-v2-user-management-table.png) User Management Table **Shared Token Pool Organizations:** If your organization has **Shared Token Pool** billing turned on (see [Token Distribution](/docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-distribution)), the manual per-user editing flow described below is disabled. Every member draws directly from the org's shared pool instead of an individual monthly limit, and the Max Inference Tokens / Max Embedding Tokens columns in the User Table become reference-only. Turn the Shared Token Pool off to manage individual user limits again. **Minimum Requirements:** - All users are required to have a minimum amount of Ask Sage Tokens, set by Token Distribution Policy settings or set by default. For example, if you have 4 accounts and purchased 2M tokens, each account would be assigned 200K Ask Sage tokens each if using the default settings. - If more tokens are needed, contact us at [sales@asksage.ai](mailto:sales@asksage.ai) ## Assigning Tokens Manually (Shared Token Pool Off) ### Token Assignment Overview For organizations that have **not** enabled the Shared Token Pool, Administrators can assign tokens to individual users directly from the **User Table** in the Admin Panel. Organizations with automated allocation needs should instead use the presets and rebalancing schedules covered in [Token Distribution](/docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-distribution). ### Confirming Token Availability ### Token Availability Check Before assigning tokens to users, Administrators need to ensure that they have the necessary tokens available in their `Enterprise Account`. To confirm the availability of tokens, Administrators can review the token allocation columns in the User Table, where the per-user Max Inference Tokens and Max Embedding Tokens are visible alongside current usage. **Need More Tokens?** If more tokens are needed, contact us at [sales@asksage.ai](mailto:sales@asksage.ai) ### Step-by-Step Token Assignment ### Token Distribution Process Administrators can assign and distribute tokens as needed within their organization. Follow these steps to assign tokens to users: #### Token Assignment Steps 1. Navigate to the **User Management** tab of the Admin Panel 2. Locate the user you want to assign tokens to 3. **Double-click** the value in the **Max Inference Tokens** column to enter edit mode 4. Type the new token value and press **Enter** or click outside the cell to confirm 5. A blue **Save Changes** button will appear in the bottom left corner — click it to lock in the change 6. Repeat for **Max Embedding Tokens** ![Token Allocation — Max Inference and Max Embedding Tokens](/assets/images/asksage-platform-v2-admin-token-allocation.png) Max Inference Tokens and Max Embedding Tokens columns in edit mode #### Token Type Definitions Understanding the different token types is essential for proper token allocation: - **Max Inference Tokens:** Represents the total number of inference tokens assigned to a user - **Max Embedding Tokens:** Represents the total number of tokens assigned to a user for embedding purposes **Token Usage Explanation:** Inference tokens are used when a user interacts with the Ask Sage platform to generate responses. Embedding tokens are used when a user ingests data into the datasets. --- # Token Distribution Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-distribution.html # Token Distribution Automate and manage token allocation across your organization using presets, policies, and per-user overrides Table of Contents 1. TOC The Token Distribution panel gives administrators full control over how tokens are allocated to users within their organization — both automatically and manually. Use the **Inference** / **Training** toggle in the top-right corner to switch between managing inference and training token pools. Administrators can choose from pre-configured allocation presets, define floor and ceiling limits, configure auto-increase rules, and set per-user overrides to handle edge cases. The panel is organized into three tabs: **Policy & Distribution**, **Users**, and **History**. ## Shared Token Pool ### Shared Token Pool Toggle At the top of the panel, the **Shared Token Pool** toggle switches the organization between per-user monthly limits and a single, org-wide pool. When turned **ON**: > Everyone in your organization draws from the shared pool. Individual monthly limits don't apply — anyone can keep using tokens until the pool runs out, and once it does, everyone is paused together until it's topped up or refilled at the start of next month. A tip below the toggle reminds administrators: *"turn this off to go back to per-user limits — useful if some users need more guardrails than others."* While Shared Token Pool is on, an info banner appears at the top of the **Policy & Distribution**, **Users**, and **History** tabs: > Shared Token Pool is on. Per-user policies, allocations, and overrides are disabled because every member draws directly from the org's shared pool. Turn the pool off above to manage individual user limits again. With the pool on, allocation presets, floor/ceiling, auto-increase, and per-user overrides are all shown for reference but cannot be edited — the **Users** tab shows "Activate an allocation preset to enable per-user overrides." and the **History** tab shows no distribution history until the pool is turned off and a policy is activated. ![Ask Sage Token Distribution — Shared Token Pool toggle enabled](/assets/images/asksage-platform-v2-token-distribution-shared-pool.png) Token Distribution — Shared Token Pool On **Note:** The remainder of this page — allocation presets, floor & ceiling, auto-increase, reclamation, and per-user overrides — applies when the **Shared Token Pool** is turned **off**. ![Ask Sage Token Distribution Allocation Status](/assets/images/asksage-platform-v2-token-distribution-status.png) Token Distribution — Allocation Status and Presets ## Allocation Status At the top of the panel, the **Allocation Status** section provides a real-time snapshot of your organization's monthly token pool: ### Monthly Status Indicators - **Purchased** — total tokens purchased for your organization - **Allocated** — tokens currently assigned to users - **Used** — monthly tokens consumed by users - **Unallocated** — tokens in your pool not yet assigned to any user - **Pending Requests** — the number of user-submitted token requests currently awaiting administrator review When a preset is active, its name appears as a badge next to the allocation status (e.g., Aggressive Preset). If no preset has been activated yet, the panel shows "No active policy — select a preset below to get started." ## Allocation Presets Administrators can select from five allocation presets to define how tokens are distributed and managed across the organization. Each preset balances floor levels, ceilings, auto-increase aggressiveness, and reclamation behavior. ### Preset Comparison | Preset | Best For | Floor | Ceiling | Trigger | Cooldown | Bump | Reclamation | | --- | --- | --- | --- | --- | --- | --- | --- | | Conservative | Cost-conscious organizations | 200K / 200K | 1M | 90% | 4h | +25% current | Off | | Standard | Balanced teams | 500K / 500K | 5M | 80% | 1h | +25% / +50% near max | Off | | Aggressive | High-trust power users | 1M / 1M | Unlimited | 75% | 30min | Flat +500K | Off | | Dynamic | Large orgs with mixed usage | 500K / 500K | Unlimited | Tiered (75–99.9%) | 1h | +25% remaining | Enabled | | Custom | Specific manual requirements | Configure all parameters manually | ## Floor & Ceiling The **Floor & Ceiling** section defines the minimum and maximum token allocation boundaries for users. ### Floor & Ceiling Settings - **Floor** — the starting token allocation given to each user when added. This is the minimum a user can hold at any time. - **Ceiling** — the maximum tokens a user can accumulate. **Note:** If using the **Distribute Now** button, users' tokens will be set to the ceiling. ## Auto-Increase ### Auto-Increase Configuration When enabled, auto-increase automatically bumps a user's token allocation when they approach their limit — preventing workflow interruptions without requiring manual intervention. #### Core Settings - **Enable Auto-Increase** — toggle to activate automatic token bumping - **Trigger Mode** — choose how tokens are automatically increased. Select *Tiered (Dynamic)* for a hands-off approach that adjusts automatically, or *Flat Threshold* to set a specific usage percentage that triggers the increase. - **Trigger %** (10–99%) — the percentage of token usage at which an auto-increase fires. For example, 80% means a bump is triggered when the user has consumed 80% of their allocation. - **Cooldown (min)** — minimum time that must elapse between consecutive auto-increases for the same user - **Bump Method** — choose how additional tokens are calculated. Select *Flat Fixed Amount* to add a set number of tokens each time, or use *% of Current* / *% of Remaining* to scale the increase based on the user's current or remaining token balance. - **Bump Amount/Bump %** — the number of tokens added per bump - **Buffer Days** — days before the end of the period at which a pre-emptive bump is applied to ensure users don't run out #### Near-Max Settings - **Near-Max Threshold** — a value between 0.0 and 1.0 (e.g., 0.8 = 80%) that defines when a user is considered "near ceiling" - **Near-Max Bump** — a larger bump amount applied specifically when the user's allocation is near the ceiling, to avoid frequent small increments **Tip:** Setting a Near-Max Bump higher than your standard Bump Amount ensures users near their ceiling receive a meaningful allocation increase rather than incrementally small bumps. ![Ask Sage Token Distribution Auto-Increase and Per-User Overrides](/assets/images/asksage-platform-v2-token-distribution-auto-increase.png) Auto-Increase Settings and Per-User Overrides ## Schedule & Reclamation ### Schedule & Reclamation - **Monthly Reset to Floor (1st of month)** — when enabled, all user allocations are reset back to the configured floor value at 00:00 UTC on the 1st of each month (not local midnight), ensuring consistent token budgets across monthly periods - **Enable Reclamation** — when enabled, the system identifies users with excess allocation above their projected need and reclaims those tokens back into the pool for redistribution ## Distribution Actions Four action buttons control how the distribution policy is applied: ### Action Buttons - **Activate [Preset]** — applies the currently selected preset and saves it as the active policy - **Save Policy** - saves any changes to floor, ceiling, or auto-increase settings without immediately activating. Use this to stage configuration changes before going live. - **Preview Distribution** — shows a projected view of how tokens would be distributed under the current settings before committing any changes - **Distribute Now** — immediately distributes tokens to all users according to the current policy without waiting for the scheduled cycle ## Reclamation Preview ### Reclamation Preview The **Reclamation Preview** section allows administrators to preview which users have excess token allocation above their projected need before reclamation runs. Click **Preview Reclamation** to generate the report and review it prior to enabling reclamation. ## Per-User Overrides ### Per-User Overrides The **Per-User Overrides** table allows administrators to set individual floor and ceiling values for specific users, overriding the organization-wide policy. This is useful for power users or restricted accounts that require different allocation limits. #### Table Columns - **Email** — the user's email address - **Current** — the user's current token allocation - **Floor Override** — a custom floor value for this user (leave as *Default* to use the global floor) - **Ceiling Override** — a custom ceiling value for this user (leave as *Default* to use the global ceiling) - **Override** — when user set to Override, this user's allocation is excluded from auto-increase and reclamation - **Status** — indicates whether the override is active - **Actions** — remove the override **Tip:** Use the **Show overrides only** toggle to filter the table and display only users with active overrides, making it easier to manage customized accounts. ![Ask Sage Token Distribution Preview, Reclamation, and Per-User Overrides](/assets/images/asksage-platform-v2-token-distribution-preview.png) Distribution Preview, Reclamation Preview, and Per-User Overrides ## Auto-Rebalancing Schedule ### Auto-Rebalancing Schedule The **Auto-Rebalancing Schedule** controls how often the system automatically rebalances token allocations across your organization. Select the desired schedule frequency from the dropdown and click **Save Policy** to apply. ## Legacy Distribution Strategy ### Legacy Distribution Strategy In addition to the preset-based distribution system, the panel includes a **Legacy Distribution Strategy** section with two simple distribution modes: - **Equal Split** — divides the available token pool evenly across all users. Configure the following parameters: **Reserve Pool %** — the percentage of total tokens to hold back as a reserve (not distributed to users) - **Min Tokens Per User** — the minimum number of tokens each user must receive regardless of the split calculation - **Usage-Based** — distributes tokens proportionally based on each user's historical usage patterns **Note:** The Legacy Distribution Strategy is provided for backwards compatibility. For most organizations, the preset-based system (Conservative, Standard, Aggressive, Dynamic, or Custom) is recommended. ## Inference vs. Embedding Tokens The Token Distribution panel applies to both inference and training (embedding) token pools. Use the **Inference** / **Training** toggle in the top-right corner of the panel to switch between managing inference token distribution and embedding token distribution policies independently. --- # Token Requests Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-token-requests.html # Token Requests Review and act on user-submitted requests for additional token allocation Table of Contents 1. TOC Users on the Ask Sage platform can submit requests to their administrator when they need additional tokens. The **Token Requests** panel provides administrators with a centralized queue to review, approve, or deny these requests. ![Ask Sage Token Requests Panel](/assets/images/asksage-platform-v2-token-requests-panel.png) Token Requests Panel — Administrator View ## Request Queue ### Viewing Requests The request queue displays all token requests submitted by users in your organization. A total count is shown at the top of the panel. Administrators can filter the queue using the following tabs: - **Pending** — requests awaiting administrator review - **Approved** — requests that have been approved - **Denied** — requests that have been denied - **All** — all requests regardless of status ## Request Table Each token request appears as a row in the table with the following columns: ### Table Columns ![Ask Sage Token Requests Panel](/assets/images/asksage-platform-v2-token-requests-pending.png) Token Requests Pending - **User Email** — the email address of the user who submitted the request - **Requested Amount** — the number of additional tokens the user is requesting - **Reason** — the explanation provided by the user for why they need more tokens - **Current Tokens** — the user's token allocation at the time the request was submitted - **Status** — the current state of the request: *Pending*, *Approved*, or *Denied* - **Date** — the timestamp of when the request was submitted - **Actions** — controls to approve or deny the request ## Approving and Denying Requests ### Acting on a Request Use the **Actions** column to review and respond to each request: - **Approve** — grants the requested token amount to the user. The user's allocation is updated immediately and the request status changes to *Approved*. - **Deny** — rejects the request. The request status changes to *Denied* and the user's allocation remains unchanged. **Note:** Before approving a request, confirm that your organization has sufficient unallocated tokens available. You can verify this in the **Allocation Status** section of the [Token Distribution](./asksage-enterprise-token-distribution) panel. **User Notification:** Users are **not automatically notified** when their token request is approved or denied. Administrators should manually notify the user of the decision after taking action. --- # Theme Builder Source: /docs/v2/asksage-platform/enterprise-account/asksage-enterprise-theme-builder.html # Theme Builder Customize the look and feel of the Ask Sage platform to match your organization's brand Table of Contents 1. TOC Administrators can customize the appearance of the Ask Sage platform for their organization using the **Theme Builder**, found under **Branding** in the Admin Panel sidebar. Theme Builder pairs a configuration panel with a live preview of the actual chat interface, so changes can be reviewed before they're applied. ![Ask Sage Theme Builder showing brand configuration panel and live preview](/assets/images/asksage-platform-v2-theme-builder.png) Theme Builder — Configuration Panel and Live Preview ## Brand Metadata ### Naming and Default Mode The top of the configuration panel captures the identity of the theme: - **Brand name** — the display name for this theme (e.g., "New Brand") - **Short name (optional)** — an abbreviated name used where space is limited - **Default mode** — whether users start in **Dark** or **Light** mode - **Lock mode** — when enabled, hides the dark/light toggle for users and forces everyone into the configured default mode ## Dark Mode and Light Mode Tabs ### Configuring Each Mode Independently Color settings are configured separately for **Dark mode** and **Light mode** using two tabs. Each tab shows a counter (e.g., `0/47`) indicating how many of the available color values have been customized away from their defaults. Within each mode tab, settings are organized into collapsible categories: - **Brand** — the core brand colors: Primary, Hover, Active, Soft, and Glow. Each has a text input (defaulting to `default`) and a color swatch. - **Dark mode** / **Light mode** — mode-specific surface and background colors - **Semantic** — colors used for status and feedback (e.g., success, warning, error states) - **Accent** — supporting accent colors used throughout the interface - **Inputs** — colors for form fields and input controls **Tip:** Hover over the icon next to any color field for a description of where that color is used in the interface. ## Advanced — Component Slots ### Component-Level Overrides The collapsed **Advanced — component slots** section allows administrators to override individual sidenav, topbar, chat, button, and card surfaces beyond the standard color categories above. Most organizations won't need this level of control — it exists for brands with more specific design requirements. ## Live Preview ### Reviewing Changes The right side of the Theme Builder renders a live preview of the actual Ask Sage chat interface, updating as color values change on the left. Use the controls above the preview to: - Zoom the preview to **50%**, **75%**, or **100%** - Toggle the preview between **Dark** and **Light** to check both modes - Refresh the preview or navigate it back to its home state ## Exporting a Theme ### theme.json Below the live preview, the **THEME.JSON** panel shows the full generated configuration as JSON, including the brand metadata and every color value. Use **Copy** to copy the JSON to your clipboard, or **Download** to save it as a file. **Need help applying your theme?** Contact [support@asksage.ai](mailto:support@asksage.ai) for assistance rolling out a custom theme to your organization. ## Discarding Changes ### Reset Draft Click **Reset draft** in the top-right corner of the Theme Builder to discard all unsaved changes and return every color value to its default. --- # Integrations Source: /docs/v2/integrations/integrations.html # Ask Sage Integrations Bring Ask Sage directly into your workflows including integrations with popular platforms and tools. ### Development Integrations Ask Sage integrates with various platforms and tools to extend its capabilities directly into your workflows. Below you'll find current integrations and links to their respective documentation. **Feedback Welcome:** If you have any requests for integrations or feedback, please reach out to us at [support@asksage.ai](mailto:support@asksage.ai). --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Claude Code ### Claude Code - CLI Integration Bring Ask Sage's AI models directly into your terminal or IDE with Claude Code—Anthropic's official CLI for Claude, now integrated with Ask Sage. ![Claude Code CLI](/assets/images/integrations-v2-claude-code-hero.png) #### Command-line Assistant Full terminal integration #### Multi-file Operations Complex refactoring tasks #### Git Integration Seamless version control #### DoD PKI Support Government environments #### MCP Protocol Extended capabilities **Perfect for:** Developers get to leverage Ask Sage's AI models directly in their terminal or IDE for coding assistance, refactoring, and more using Claude Code via the Anthropic Models. [View Full Documentation](claude-code.html) --- ## Claude Cowork ### Claude Cowork - Desktop App Run Anthropic's Cowork desktop app against Ask Sage as your inference provider. Get the full Cowork agentic workspace (Cowork tab + Code tab) with all model routing handled by Ask Sage's gateway, including **Claude Opus 4.7 with the 1M-token context window**. #### 1M Context Window Opus 4.7 / 4.6 with extended context #### Auto Model Discovery Picker fills in from Ask Sage's `/v1/models` #### Telemetry Lockdown Disable all Anthropic-bound traffic #### MDM Managed Jamf, Intune, Group Policy ready #### OpenTelemetry Export Send full session activity to your collector **Perfect for:** Regulated and air-gapped deployments that want the full Claude Desktop experience while routing all inference and telemetry through Ask Sage. [View Full Documentation](claude-cowork-3p.html) --- ## Dify ### Dify - Model Provider Plugin Register Ask Sage as a native **model provider** inside Dify, the open-source LLM app platform. Once installed, every Ask Sage model (GPT, Claude, Gemini, Llama, Groq, and more) becomes selectable in Dify's model picker for chatflows, agents, workflows, and RAG datasets — routed through Ask Sage's FedRAMP-authorized API. #### 47+ Models Auto-generated from the Ask Sage catalog #### Dynamic Discovery Models fetched at runtime, cached 5 min #### Token Tracking Prompt + completion usage reported #### Governed Inference FedRAMP-authorized Ask Sage gateway **Perfect for:** Teams building chat assistants, agents, and RAG workflows in Dify who want every response routed through Ask Sage's governed model gateway. [View Full Documentation](dify.html) --- ## GitLab Duo ### GitLab Duo - Self-Hosted Model Integration Power GitLab Duo Chat and Code Suggestions with Ask Sage's FedRAMP-compliant AI models. GitLab Duo supports self-hosted model providers through its AI Gateway — Ask Sage's OpenAI, Anthropic, and Gemini-compatible passthrough surfaces plug in directly, keeping AI traffic within FedRAMP-compliant infrastructure. #### Three Provider Surfaces OpenAI, Anthropic, and Gemini-compatible endpoints #### Duo Chat Self-hosted model routing for chat #### Code Suggestions Dedicated models for completion and generation #### FedRAMP-Compliant AI traffic stays within governed infrastructure **Perfect for:** GitLab EE teams with a Duo Enterprise license who want Duo Chat, Code Suggestions, and Duo Workflow running on self-hosted, FedRAMP-authorized models instead of GitLab's cloud-connected path. [View Full Documentation](gitlab-duo.html) --- ## OpenAI Codex ### Codex CLI - Terminal Integration Use OpenAI's open-source Codex CLI with Ask Sage as your AI provider. Bring AI-powered coding assistance directly into your terminal with support for multi-agent workflows. ![Codex VSCode](/assets/images/integrations-v2-codex-hero.png) #### Terminal-based AI CLI coding assistant #### Multi-Agent Extended agent capabilities #### Multiple Models GPT-5.4, GPT-4.1-gov, and more #### Easy Configuration Simple TOML-based setup **Perfect for:** Developers who want to use OpenAI-compatible models through Ask Sage via the Codex CLI for terminal-based coding workflows. [View Full Documentation](codex.html) --- ## opencode ### opencode - IDE Integration Use the opencode VS Code extension with Ask Sage as your AI provider. opencode is a terminal-based agentic coding assistant that integrates directly into your editor — all inference routes through your organization's Ask Sage instance. #### Agentic Chat Multi-turn AI with full codebase context #### In-place Edits AI applies changes directly to your files #### Keyboard-driven Launch from VS Code with a single shortcut #### Governed Inference All configured model inference traffic routes through your Ask Sage instance **Perfect for:** Developers who want a fast, keyboard-driven AI coding agent inside VS Code, with all model traffic routed through Ask Sage's governed gateway. [View Full Documentation](opencode.html) --- ## PyCharm ### PyCharm - JetBrains IDE Plugin Bring Ask Sage's governed AI models directly into PyCharm with the AskSage plugin — an open-source IntelliJ Platform plugin that works in any JetBrains IDE. #### Chat Tool Window Multi-turn chat with model and persona selection #### Editor Context Actions Explain, Refactor, Generate Docs, Ask About File, with shortcuts #### Real-Time Web Search A per-message toggle grounds answers in live results, with sources shown #### Tabular Data Train and query CSV/TSV/XLSX/XLSB datasets in natural language **Perfect for:** Python (and any JetBrains-IDE) developers who want Ask Sage's model catalog and knowledge-base training available directly in their editor. [View Full Documentation](pycharm.html) --- ## Power Automate ### Power Automate - Microsoft 365 Integration Bring governed, accredited generative AI into your existing Power Automate flows — no code required. Because Ask Sage exposes a standard REST API, any flow can send a prompt and use the response in the next step: an email, a Teams reply, a SharePoint item, an approval, and more. #### HTTP & Custom Connector Two ways to call Ask Sage from a flow #### Document Analysis Analyze OneDrive & SharePoint files #### Teams Bot Threaded channel bot with history #### Importable Solutions Downloadable, ready-to-import zips **Perfect for:** Teams who want to add secure, governed AI to their Microsoft 365 automations — quick prototypes with the HTTP action, or reusable production flows with a custom connector. [View Full Documentation](power-automate/power-automate.html) --- ## SharePoint Chat Widget ### SharePoint Chat Widget - Microsoft 365 Integration Bring AI-powered question-and-answer capabilities directly into your organization's SharePoint pages with the Ask Sage Chat Widget. ![Ask Sage Chat Widget](/assets/images/integrations-v2-sharepoint-widget-conversation.png) #### Instant, Cited Answers AI-generated answers with source citations #### Department-Specific Per-site knowledge base configuration #### Secure by Default XSS protection and input validation built in #### Standard Deployment Installed via SharePoint App Catalog **Perfect for:** Organizations using Microsoft 365 who want to surface AI-powered self-service answers for HR, IT, onboarding, compliance, and more — directly within SharePoint. [View Full Documentation](sharepoint-widget/sharepoint-widget.html) --- --- # Claude Code Source: /docs/v2/integrations/claude-code.html # Claude Code Integration Bring Ask Sage's AI models directly into your terminal with Claude Code CLI ![Claude Code CLI](/assets/images/integrations-v2-claude-code-hero.png) ### About Claude Code Bring Ask Sage's AI models directly into your terminal or IDE with Claude Code—Anthropic's official CLI for Claude, now integrated with Ask Sage. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### Ask Sage API Key Valid user API Key from Ask Sage #### Claude Code Installed on your system #### Node.js Required for Claude Code installation ## Installation ### Installation Claude Code can be installed in two ways: #### Option 1: VSCode Extension Install the Claude Code extension directly in Visual Studio Code: 1. Open VSCode and navigate to the Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X` on Mac) 2. Search for "Claude Code for VS Code" by Anthropic 3. Click the **Install** button to add the extension to your VSCode ![Claude Code VSCode Extension Installation](/assets/images/integrations-v2-claude-code-vscode-install.png) #### Option 2: CLI Installation (via npm) ```bash npm install -g @anthropic-ai/claude-code # Verify installation claude --version ``` --- ## Configuration Methods ### Configuration Methods Claude Code can be configured to work with Ask Sage using two methods. Choose the method that best fits your workflow. #### Method 1: Using ~/.claude/settings.json (Recommended) If on Windows, this file `~/.claude/settings.json` might need to be created where you have Claude Code installed. For example: `C:\Users\username\.claude` Create or edit `~/.claude/settings.json` with the following configuration: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.asksage.ai/server/anthropic", "ANTHROPIC_AUTH_TOKEN": "your-asksage-token-here", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1 }, "permissions": { "allow": ["*"], "deny": ["Delete"] } } ``` **Required Parameters:** - `ANTHROPIC_BASE_URL`: Your Ask Sage Server Base URL with `/anthropic` path. Note this varies based on instance of Ask Sage you are using. - `ANTHROPIC_AUTH_TOKEN`: Your Ask Sage API Key - `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`: Set to `1` to disable all non-essential traffic to Anthropic services (including telemetry, error reporting, and bug reports) #### Method 2: Environment Variables (Terminal Session) Export the following environment variables in your terminal before launching Claude Code: ```bash export ANTHROPIC_BASE_URL="https://api.asksage.ai/server/anthropic" export ANTHROPIC_AUTH_TOKEN="your-asksage-token-here" export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ``` Then launch Claude Code from the same terminal session. **Important:** Method 2 only works in the terminal where the exports were set, and the exports will be cleared once the terminal is closed. Method 1 persists as long as the file is not deleted. --- ## Privacy & Data Usage Controls ### Privacy & Data Usage Controls Claude Code can send operational telemetry to Anthropic services. You have full control over this data sharing through environment variables. **Ask Sage Default Behavior:** When using Ask Sage's API endpoint (similar to Bedrock or Vertex providers), non-essential traffic to Anthropic is disabled by default. Ask Sage follows a "fire and forget" approach—your data is never used for model training and is not retained after generating responses. #### Disable All Non-Essential Traffic To ensure no operational data is sent to Anthropic services (including telemetry, error reporting, and bug reports), set the following environment variable: ```bash export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ``` #### Configuration Examples **Method 1: Add to ~/.claude/settings.json (Recommended)** ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.asksage.ai/server/anthropic", "ANTHROPIC_AUTH_TOKEN": "your-asksage-token-here", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1 }, "permissions": { "allow": ["*"], "deny": ["Delete"] } } ``` **Method 2: Export in Terminal Session** ```bash export ANTHROPIC_BASE_URL="https://api.asksage.ai/server/anthropic" export ANTHROPIC_AUTH_TOKEN="your-asksage-token-here" export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ``` **What Data is Affected?** Setting this environment variable disables the following Anthropic services: - **Statsig Metrics:** Operational telemetry including latency, reliability, and usage patterns (no code or file paths) - **Sentry Error Reporting:** Operational error logs for debugging Claude Code itself - **Bug Reports:** Prevents the `/bug` command from sending conversation history to Anthropic All data sent to these services is encrypted in transit (TLS) and at rest (AES-256). However, disabling these services ensures no operational data leaves your environment. #### Individual Service Controls (Advanced) For finer control, you can disable specific services individually: ```bash # Disable telemetry metrics only export DISABLE_TELEMETRY=1 # Disable error reporting only export DISABLE_ERROR_REPORTING=1 # Disable bug report command only export DISABLE_BUG_COMMAND=1 ``` **Ask Sage Privacy:** Regardless of these Claude Code settings, Ask Sage maintains strict data privacy. All queries use a "fire and forget" approach—your data is processed for immediate responses only and is never retained, logged, or used for model training. For more details, see our [FAQ on Security & Data Privacy](../../v1/faq/faq.html#security--data-privacy). --- ## DoD/DoW Network Configuration ### DoD/DoW Network Configuration **Government Users:** For users working on DoD or DoW networks, additional certificate configuration is required. #### Prerequisites You'll need a DoD root certificate in PEM format. If you haven't already created this file, see the [DoD Certificate Setup](dod-certs.html#dod-certificate-configuration) guide for instructions. #### Configuration for VSCode Extension Add the following to your VSCode `settings.json`: ```json { "claudeCode.environmentVariables": [ { "name": "NODE_EXTRA_CA_CERTS", "value": "C:\\Path\\TO\\AskSage_DoD_Root.pem"}, { "name": "ANTHROPIC_BASE_URL", "value": "https://api.genai.army.mil/server/anthropic/"}, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "ASK-SAGE-API-KEY"}, { "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": 1} ] } ``` **Important Notes:** - Replace `C:\\Path\\TO\\AskSage_DoD_Root.pem` with your actual certificate path - Use double backslashes (`\\`) in Windows paths for JSON - Replace `ASK-SAGE-API-KEY` with your actual Ask Sage API Key. - For Army GenAI environment, use `https://api.genai.army.mil/server/anthropic/` - You can reuse the same PEM file across other Ask Sage integrations #### Example Configuration File For usage on DoD/DoW networks, add the certificate to your `~/.claude/settings.json`: ```json { "env": { "NODE_EXTRA_CA_CERTS": "/path/to/AskSage_DoD_Root.pem", "ANTHROPIC_BASE_URL": "https://api.genai.army.mil/server/anthropic", "ANTHROPIC_AUTH_TOKEN": "your-asksage-token-here", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1 }, "permissions": { "allow": ["*"], "deny": ["Delete"] } } ``` **Linux/Mac users:** Use forward slashes in paths: `/path/to/AskSage_DoD_Root.pem` --- ## Troubleshooting ### Troubleshooting **Issue: "Token is invalid" error** **Solutions:** - Verify your API Key is correct - Remove any extra spaces from the token string **Issue: Connection errors** **Solutions:** - Verify the `ANTHROPIC_BASE_URL` is correct and accessible - Verify your Ask Sage API Key is correct - Ensure there are no firewall rules blocking the connection **Issue: Certificate errors in DoD/DoW environment** **Solutions:** - Verify certificate path is correct in your configuration - Ensure certificate is in PEM format (not DER) - Check you have the complete certificate chain - Windows users: Use double backslashes (`\\`) in JSON configuration --- ## Additional Resources ### Documentation & Resources - [Claude Code Official Documentation](https://code.claude.com/docs) - [Claude Code Settings Reference](https://code.claude.com/docs/en/settings) - [Claude Code Data Usage & Privacy](https://code.claude.com/docs/en/data-usage) - Learn about telemetry and privacy controls - [DoD Certificate Setup](dod-certs.html) - For DoD/DoW network configuration **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # Claude Cowork Source: /docs/v2/integrations/claude-cowork-3p.html # Claude Cowork Integration Bring Ask Sage's AI models into the Claude Desktop app with Anthropic's Cowork ![Claude Cowork](/assets/images/integrations-v2-claude-cowork-hero.png) ### About Claude Cowork on 3P Run Anthropic's Cowork desktop app against Ask Sage as your inference provider — full Cowork agentic workspace, with all model routing handled by Ask Sage's gateway. **Cowork on third-party (3P)** is a deployment mode of the Claude Desktop app (Cowork and Code tabs) that routes *all* model inference through a provider you configure instead of Anthropic's first-party API. Conversation history is stored locally on the user's device, and the agent runs against the LLM gateway of your choice — including **Ask Sage**. You get the same agentic Cowork experience (file creation, multi-step research, sub-agent coordination, the Code tab) with inference and billing handled by Ask Sage. This page walks you through pointing Cowork at Ask Sage as a Gateway provider, picking the model (including **Claude Opus 4.8 with the 1M-token context window**), and locking down all telemetry to Anthropic so the only outbound traffic is to your Ask Sage endpoint. **Reference:** Anthropic's official Cowork on 3P documentation lives at [claude.com/docs/cowork/3p/overview](https://claude.com/docs/cowork/3p/overview). This page focuses on the Ask Sage–specific setup. Field semantics and the canonical configuration reference are at [claude.com/docs/cowork/3p/configuration](https://claude.com/docs/cowork/3p/configuration). --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### Ask Sage API Key Valid user API Key from Ask Sage #### Claude Desktop The Claude desktop app installed on macOS or Windows #### 3P Mode Available Your Claude Desktop build must support Cowork on 3P (see [installation](https://claude.com/docs/cowork/3p/installation)) --- ## Quick Start ### Quick Start The fastest path to a working setup uses Claude Desktop's built-in configuration window — no hand-editing of plist or registry files required. 1. Open Claude Desktop and go to **Developer → Configure third-party inference**. The Developer menu is hidden by default. Enable it from **Help → Troubleshooting → Enable Developer Mode**, then it will appear in the menu bar. 2. Choose **Gateway** as the inference provider. 3. Set the gateway base URL to `https://api.asksage.ai/server/anthropic` (no trailing slash) and paste your Ask Sage API key. Set the auth scheme to **bearer**. 4. (Recommended) Apply the [telemetry-disable settings](#disabling-all-telemetry-to-anthropic) below before saving. 5. Click **Apply Locally**, then fully quit and re-open Claude Desktop. The model picker will auto-discover available models from `https://api.asksage.ai/server/anthropic/v1/models`. **Why Gateway?** Ask Sage exposes an Anthropic-compatible Messages API (`POST /v1/messages`) plus a model-list endpoint (`GET /v1/models`) — exactly what Cowork on 3P's Gateway provider expects. No need for a separate LiteLLM/Portkey proxy in front of Ask Sage; you can point Cowork directly at us. --- ## Configuration ### Where the configuration lives Cowork on 3P is configured entirely through OS-native managed preferences. You can manage them via MDM (recommended for fleets) or by hand in a per-user config file (good for evaluation on your own machine). ```text macOS (MDM): /Library/Managed Preferences//com.anthropic.claudefordesktop.plist macOS (per-user): ~/Library/Application Support/Claude-3p/claude_desktop_config.json (under "enterpriseConfig") Windows (MDM): HKLM\SOFTWARE\Policies\Claude (machine) or HKCU\SOFTWARE\Policies\Claude (user) Windows (per-user): %APPDATA%\Claude-3p\claude_desktop_config.json (under "enterpriseConfig") ``` **Important behaviours:** - When an MDM source is present, it *wins*. Local values are ignored. - Configuration is read **once at launch** — fully quit and reopen the app after any change. - All values are stored as **strings**, even booleans (`"true"`/`"false"`) and arrays (JSON-encoded into a single string). The most common mistake is writing `inferenceModels` or `coworkEgressAllowedHosts` as a native plist/registry array — that won't work. They must be a single string containing JSON. ### Required keys (Ask Sage / Gateway provider) ### Connection | Setting | Value | Why | | --- | --- | --- | | `inferenceProvider` | `gateway` | Selects the Gateway backend — what Ask Sage is, in Cowork's terms. | | `inferenceGatewayBaseUrl` | `https://api.asksage.ai/server/anthropic` | Ask Sage's Anthropic-compatible endpoint. Must be HTTPS. Use the equivalent for your Ask Sage instance (e.g. `https://api.dev.asksage.ai/server/anthropic` for dev). | | `inferenceGatewayApiKey` | *your Ask Sage user API key* | Authenticates the request to Ask Sage. Generate this in your Ask Sage account. | | `inferenceGatewayAuthScheme` | `bearer` | **Required.** Ask Sage keys do not start with `sk-`, so Cowork's `auto` scheme would default to `Authorization: Bearer` — which happens to be correct. Setting `bearer` explicitly avoids any ambiguity. | | `deploymentOrganizationUuid` | *a UUID you generate* | Identifies your fleet to Anthropic for telemetry attribution. Set this once per organization. If telemetry is disabled (recommended below) this is cosmetic, but generate one anyway so support cases can be tied back to your deployment. | | `disableDeploymentModeChooser` | `true` | Skips the sign-in mode chooser at first launch and boots directly into 3P mode. Stops users from accidentally signing into a personal Anthropic account. | ### Models — picker and 1M context window ### Models Cowork on 3P automatically discovers available Ask Sage models by calling `GET /server/anthropic/v1/models` against your gateway base URL. **You do not need to configure `inferenceModels` just to populate the picker** — it fills in automatically. You only need to set `inferenceModels` when you want to: - Restrict the picker to a curated subset of the available models - Pick which model is the default (the first entry wins) - Surface a **1M-token context window** variant of a model that supports it (Claude Opus 4.8, 4.7, and 4.6 on Ask Sage) #### Enabling Opus 4.8 with 1M context Add an `inferenceModels` entry with `supports1m: true` to surface the 1M context variant in the picker. Order this first if you want it as the default. ```json [ { "name": "claude-opus-4-8", "supports1m": true }, { "name": "claude-opus-4-7", "supports1m": true }, { "name": "claude-opus-4-6", "supports1m": true }, { "name": "claude-sonnet-4-6" }, { "name": "claude-sonnet-4-5" }, { "name": "claude-haiku-4-5" } ] ``` **About `supports1m`:** This is a *capability assertion you make about your deployment* — Cowork does not probe Ask Sage to verify it. Only set `supports1m: true` on models you've confirmed support 1M context. On Ask Sage today, that's **Claude Opus 4.8**, **Claude Opus 4.7**, and **Claude Opus 4.6** (all forward the `context-1m-2025-08-07` Anthropic beta header). Setting it on a model that doesn't support 1M will fail mid-session once the conversation grows past the model's actual limit. **Plist/registry encoding:** The `inferenceModels` value in your MDM/registry profile must be a single **string** containing the JSON above — not a native plist ``. In a `.mobileconfig`, that means `[...]` with the entire JSON inside. --- ## Disabling all telemetry to Anthropic ### Disabling all telemetry to Anthropic By default, Cowork on 3P sends a small amount of operational telemetry to Anthropic-operated hosts (crash reports, product analytics, favicon fetches, auto-update checks). For Ask Sage deployments — particularly in regulated or air-gapped environments — you'll typically want to disable all of it, so that the *only* outbound traffic from the device is to your Ask Sage endpoint. Set **all four** of the following keys to `true`. With these set, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. | Setting | Value | What it blocks | | --- | --- | --- | | `disableEssentialTelemetry` | `true` | Crash reports, error stack traces, performance timings (Sentry, Datadog). | | `disableNonessentialTelemetry` | `true` | Product-usage analytics: feature adoption, session counts, UI interactions. | | `disableNonessentialServices` | `true` | Favicon fetches and the third-party iframe used for artifact previews. UI degrades cosmetically (generic icons, static previews) but functionality is unaffected. | | `disableAutoUpdates` | `true` | Update checks and downloads from Anthropic. **Your IT team becomes responsible for distributing new builds.** | **Trade-off — manual support model:** Disabling `disableEssentialTelemetry` opts you into a manual support model. Anthropic will have *zero* remote visibility into failures on your fleet, so to get help with an issue your team will need to collect application logs from affected machines and send them to Anthropic directly. We recommend leaving `disableEssentialTelemetry: false` during initial rollout, then turning it on after the deployment is stable. #### Optional: send your own telemetry to your collector Independently of what's sent to Anthropic, you can export full session activity (prompts, tool calls, token counts, errors) to your own OpenTelemetry collector. This is the recommended way to retain an audit trail in environments that disable Anthropic-bound telemetry. | Setting | Value | Description | | --- | --- | --- | | `otlpEndpoint` | *e.g.* `https://otel.your-org.com` | Base URL of your OTLP collector. The endpoint host is automatically added to the sandbox network allowlist. | | `otlpProtocol` | `http/protobuf` (default), `http/json`, or `grpc` | Wire format used by your collector. | | `otlpHeaders` | *e.g.* `x-api-key=...,x-org=asksage` | Comma-separated `key=value` pairs sent on every OTLP request (standard `OTEL_EXPORTER_OTLP_HEADERS` format). | --- ## Recommended security profile (Ask Sage) ### Locked-down profile for Ask Sage This profile is a starting point for regulated or sensitive deployments. The only outbound traffic from a configured device goes to **Ask Sage** (model inference) and **your OTLP collector** (audit/telemetry). Anthropic-bound traffic is fully disabled. ```json { "inferenceProvider": "gateway", "inferenceGatewayBaseUrl": "https://api.asksage.ai/server/anthropic", "inferenceGatewayApiKey": "your-asksage-api-key-here", "inferenceGatewayAuthScheme": "bearer", "deploymentOrganizationUuid": "00000000-0000-0000-0000-000000000000", "disableDeploymentModeChooser": "true", "inferenceModels": "[{\"name\":\"claude-opus-4-8\",\"supports1m\":true},{\"name\":\"claude-opus-4-7\",\"supports1m\":true},{\"name\":\"claude-opus-4-6\",\"supports1m\":true},{\"name\":\"claude-sonnet-4-6\"},{\"name\":\"claude-sonnet-4-5\"},{\"name\":\"claude-haiku-4-5\"}]", "disableEssentialTelemetry": "true", "disableNonessentialTelemetry": "true", "disableNonessentialServices": "true", "disableAutoUpdates": "true", "isLocalDevMcpEnabled": "false", "isDesktopExtensionEnabled": "false", "isDesktopExtensionDirectoryEnabled": "false", "disabledBuiltinTools": "[\"WebSearch\",\"WebFetch\"]", "coworkEgressAllowedHosts": "[]", "allowedWorkspaceFolders": "[\"~/Documents/AskSage\"]", "otlpEndpoint": "https://otel.your-org.com" } ``` **Note:** The shape above shows what the keys look like under `enterpriseConfig` in `claude_desktop_config.json`. For MDM delivery, encode the same keys in `.mobileconfig` (macOS) or as `HKLM\SOFTWARE\Policies\Claude` registry values (Windows). All values must be strings, including booleans and JSON arrays. The in-app configuration window (**Developer → Configure third-party inference**) can export the right format for you. *The Developer menu is hidden by default — enable it from **Help → Troubleshooting → Enable Developer Mode**.* **Required egress for this profile:** - `downloads.claude.ai` — VM workspace bundle and Claude CLI binary, fetched at session start. **Without this, Cowork sessions cannot start.** - `api.asksage.ai` (or your Ask Sage instance host) — model inference - Host of `otlpEndpoint` — your OTLP collector (only if you set it) Allowlist these on your perimeter firewall on HTTPS port 443. Everything else can be denied. --- ## Verification ### Verifying the setup After saving the configuration and restarting Claude Desktop, run the following checks. #### 1. Confirm the model list endpoint is reachable ```bash curl -s https://api.asksage.ai/server/anthropic/v1/models \ -H "x-api-key: your-asksage-api-key-here" \ | jq ``` You should see a JSON response with a `data` array containing `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-5`, etc. If you get a 404, you're hitting an Ask Sage instance that hasn't been updated with the model-list endpoint yet — let support know. #### 2. Confirm Cowork picks up your models Open Claude Desktop and click the model picker in the Cowork tab. You should see the models from the `/v1/models` response. If you set `inferenceModels` with `supports1m: true` on Opus 4.8, you'll see a separate *Opus 4.8 (1M context)* entry. #### 3. Confirm no traffic is leaving to Anthropic hosts Run a packet capture or check your firewall logs for connections to `*.sentry.io`, `browser-intake-us5-datadoghq.com`, `a-cdn.anthropic.com`, `a-api.anthropic.com`, `api.anthropic.com`, or `www.claudeusercontent.com`. With the locked-down profile applied, the only Anthropic-domain traffic should be the one-time `downloads.claude.ai` fetch at session start. --- ## Windows (MSIX) — End-to-End Setup ### Windows MSIX Setup Guide Complete end-to-end setup guide for Windows 10/11 using Ask Sage as the inference gateway. **All commands use Command Prompt (`cmd.exe`).** **Critical — Windows MSIX path redirect:** Claude Desktop on Windows ships as an MSIX package, which sandboxes all filesystem writes into `%LOCALAPPDATA%\Packages\Claude_\LocalCache\`. Anthropic's public docs point at `%APPDATA%\Claude-3p\` — **that path does not work on MSIX builds.** This guide uses the real sandboxed paths throughout. See [Why Windows is harder than Mac](#why-windows-is-harder-than-mac) at the bottom. ### Step 1 — Install Claude Desktop ### Install & find your publisher ID Download the installer from [claude.com/download](https://claude.com/download). It's a `.msix` package — double-click to install. **Verify installation and capture your publisher ID:** ```cmd dir "C:\Program Files\WindowsApps" | findstr /i claude ``` Expected output (example): `Claude_1.3883.0.0_x64__pzs8sxrjxfjjc`. The last segment (`pzs8sxrjxfjjc`) is your **publisher ID**. Substitute it wherever you see `pzs8sxrjxfjjc` below — yours may differ. ### Step 2 — Initialize sandboxed folders ### First launch ```cmd REM Launch once to create sandboxed filesystem (don't sign in) start shell:AppsFolder\Claude_pzs8sxrjxfjjc!Claude REM Wait 15-20 seconds, then kill all Claude processes taskkill /F /IM claude.exe /T ``` MSIX apps leave multiple child processes running — closing the window isn't enough. Multiple "SUCCESS" lines from `taskkill` is normal. ### Step 3 — Generate a deployment UUID ### UUID generation `cmd.exe` has no built-in UUID generator. Use any of these: ```cmd REM Option A — Git for Windows: "C:\Program Files\Git\usr\bin\uuidgen.exe" REM Option B — PowerShell one-liner: powershell -Command "[guid]::NewGuid().ToString()" REM Option C — visit uuidgenerator.net and copy the output ``` **Don't skip this.** Without a real UUID, your deployment gets pooled with every other unconfigured install worldwide under the shared placeholder `00000000-0000-4000-8000-000000000001`, and Anthropic can't identify your org on support tickets. ### Step 4 — Create the config file ### Config file at the correct MSIX path ```cmd mkdir "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p" 2>nul notepad "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\claude_desktop_config.json" ``` When Notepad asks to create a new file, click **Yes**. Paste the JSON below, replacing the two placeholders: ```json { "deploymentMode": "3p", "enterpriseConfig": { "inferenceProvider": "gateway", "inferenceGatewayBaseUrl": "https://api.asksage.ai/server/anthropic", "inferenceGatewayApiKey": "YOUR_ASKSAGE_TOKEN_HERE", "inferenceGatewayAuthScheme": "bearer", "deploymentOrganizationUuid": "REPLACE-WITH-GENERATED-UUID", "disableDeploymentModeChooser": true, "disableEssentialTelemetry": true, "disableNonessentialTelemetry": true, "disableNonessentialServices": true }, "_cfprefsMigrated": true, "preferences": { "coworkScheduledTasksEnabled": true, "ccdScheduledTasksEnabled": false, "coworkWebSearchEnabled": true } } ``` Replace `YOUR_ASKSAGE_TOKEN_HERE` with your Ask Sage API key and `REPLACE-WITH-GENERATED-UUID` with the UUID from Step 3. Save with **Ctrl+S**. **Two Notepad gotchas:** 1. If Notepad opens a *Save As* dialog, set **Save as type** to **All Files** — otherwise it appends `.txt` and creates `claude_desktop_config.json.txt`, which the app ignores. 2. Encoding should be **UTF-8** (default on Windows 11), not "UTF-8 with BOM." **Config notes:** - **Models auto-discover.** `inferenceModels` is intentionally omitted — the Cowork Gateway spec auto-discovers via the gateway's `GET /v1/models` endpoint, which Ask Sage implements. To pin the picker to a specific subset or enable 1M context variants, add an `inferenceModels` key inside `enterpriseConfig` — see the [Models section above](#models--picker-and-1m-context-window). - **`disableDeploymentModeChooser: true`** boots directly into 3P mode. Remove this key if you want the option to fall back to Anthropic sign-in. - **All three telemetry keys disabled** (`disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices` all `true`). Appropriate for gov/regulated environments. Tradeoff: Anthropic has no crash data on their side — your team ships logs manually on support tickets. ### Step 5 — Validate the file ### Confirm file name and contents ```cmd REM Confirm file has no .txt extension dir "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p" REM If you see .json.txt, fix it: ren "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\claude_desktop_config.json.txt" "claude_desktop_config.json" REM View contents type "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\claude_desktop_config.json" ``` ### Step 6 — Launch and verify ### Launch Claude Desktop fresh ```cmd REM Kill any zombie processes first taskkill /F /IM claude.exe /T REM Launch fresh start shell:AppsFolder\Claude_pzs8sxrjxfjjc!Claude ``` **Visual check:** Claude should open directly into a chat interface with a model picker — *not* a claude.ai sign-in screen. The picker should show the models Ask Sage auto-discovered. **Log check:** The active 3P log is at: `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\logs\main.log` (This is different from the standard-mode log at `...\Claude\logs\main.log`.) ```cmd REM Search log for config / gateway issues findstr /i "enterprise gateway inferenceProvider Failed" "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\logs\main.log" REM Search for errors and warnings findstr /i "[error] [warn]" "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\logs\main.log" ``` #### What a healthy 3P session looks like in the log - `[Lifecycle] Session local_: initializing → running` - `[LocalAgentModeSessionManager] mcpServerStatus returned N servers` - `[CycleHealth] Healthy cycle:` with `cycle_health: 'healthy'` - `model: 'claude-sonnet-4-5-20250929'` (or whichever model you selected) #### Bad signs and fixes | Log shows | Means | Fix | | --- | --- | --- | | `Failed to parse enterprise config "inferenceGatewayBaseUrl": invalid_string` | URL validation rejected | Remove trailing slash from the base URL | | Empty or missing model picker | Gateway `GET /v1/models` discovery failed | Verify Ask Sage token, or pin models explicitly with `inferenceModels` | | `claude.ai/login` and `User logged out during IPC wait` | Config not read — app is in standard mode | Verify config is at the sandboxed path, JSON is valid, all processes killed before launch | | `Not main instance, returning early from app ready` | Zombie processes intercepted launch | `taskkill /F /IM claude.exe /T` + relaunch | | `No active account/org for marketplace operations` | Config not detected | Wrong config path, invalid JSON, or zombie processes | ### Step 7 — Test inference ### Test actual inference Type "hi" in the chat and send. You should get a response within a few seconds. If it hangs, verify the endpoint from cmd: ```cmd curl -N -X POST "https://api.asksage.ai/server/anthropic/v1/messages" ^ -H "Authorization: Bearer YOUR_ASKSAGE_TOKEN" ^ -H "Content-Type: application/json" ^ -d "{\"model\":\"claude-sonnet-4-5-20250929\",\"max_tokens\":64,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}" ``` - **SSE frames look correct but Claude Desktop errors with `$.input_tokens`** → historical Windows MSIX SSE parsing bug, resolved by auto-update. Check your version with `dir "C:\Program Files\WindowsApps" | findstr /i claude` — should be 1.3883+. - **Single JSON blob instead of SSE** → streaming isn't active for your account. Contact Ask Sage platform team. - **HTTP 401/403** → token or endpoint issue. Re-verify your API key and base URL. ### Windows path cheat sheet ### Path cheat sheet | What | Path | | --- | --- | | 3P config file | `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude-3p\claude_desktop_config.json` | | 3P log file (active) | `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude-3p\logs\main.log` | | 3P session data | `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude-3p\local-agent-mode-sessions\` | | Standard-mode log (fallback) | `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude\logs\main.log` | | App install location | `C:\Program Files\WindowsApps\Claude__` | | Documented-but-wrong config path | `%APPDATA%\Claude-3p\claude_desktop_config.json` (silently ignored on MSIX) | ### Windows quick command reference ### Quick commands (cmd.exe) | Action | Command | | --- | --- | | Launch Claude | `start shell:AppsFolder\Claude_pzs8sxrjxfjjc!Claude` | | Kill all processes | `taskkill /F /IM claude.exe /T` | | Check if running | `tasklist | findstr /i claude` | | Open config in Notepad | `notepad "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\claude_desktop_config.json"` | | Open config folder | `explorer "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p"` | | Open log in Notepad | `notepad "%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude-3p\logs\main.log"` | | View log (paged) | `type "%LOCALAPPDATA%\...\Claude-3p\logs\main.log" | more` | | Check version | `dir "C:\Program Files\WindowsApps" | findstr /i claude` | --- ## Why Windows is harder than Mac ### Why Windows is harder than Mac Anthropic's Cowork on 3P docs are written assuming a non-sandboxed install. On macOS, `~/Library/Application Support/Claude-3p/` is the real filesystem path and the docs work as written. On Windows, the `.msix` installer packages the app as a Microsoft Store-style MSIX bundle, which sandboxes all filesystem writes into `%LOCALAPPDATA%\Packages\Claude_\LocalCache\`. Everything the docs say about `%APPDATA%\Claude-3p\` **silently redirects** through this container — meaning config written to the documented path is never read, and logs written during a 3P session never appear in the documented log location. The redirected paths are: - **Config:** `%APPDATA%\Claude-3p\` → `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude-3p\` - **Logs:** `%APPDATA%\Claude\logs\` → `...\LocalCache\Roaming\Claude-3p\logs\` (in 3P mode) or `...\Roaming\Claude\logs\` (in standard mode) Use the sandboxed paths and everything else in the Anthropic docs applies as written. --- ## Troubleshooting ### Common issues #### Model picker is empty Means Cowork couldn't reach `GET /server/anthropic/v1/models` on your Ask Sage instance. Check: - `inferenceGatewayBaseUrl` is correct (no trailing slash) and uses HTTPS - `inferenceGatewayAuthScheme` is set to `x-api-key` — without this, Cowork's auto-detect sends the key as a Bearer token and the model-list call returns 401 - Your Ask Sage instance has the `/v1/models` endpoint deployed (introduced via Server PR #540 — check with the curl from [Verification](#verification) above) #### Opus 4.8 (1M) variant doesn't appear The `name` field in `inferenceModels` must **exactly match** the ID returned by `/v1/models`. If discovery returns `claude-opus-4-8` but you set `supports1m` on an alias like `opus-48`, the variant won't appear. #### Configuration changes aren't taking effect Cowork on 3P reads configuration **once at launch**. After any change, fully quit the app (not just close the window) and reopen it. On macOS that's ⌘+Q; on Windows, right-click the tray icon and choose Quit. #### "Array key is invalid" You wrote `inferenceModels` or `coworkEgressAllowedHosts` as a native plist `` or registry multi-string. Both must be a single **string** containing JSON. Wrap the JSON in `...` (macOS) or store as a `REG_SZ` single string (Windows). --- ## Reference ### Reference links - [Anthropic — Cowork on 3P overview](https://claude.com/docs/cowork/3p/overview) - [Anthropic — Cowork on 3P configuration reference](https://claude.com/docs/cowork/3p/configuration) (every supported key) - [Anthropic — Cowork on 3P telemetry & egress](https://claude.com/docs/cowork/3p/telemetry) - [Anthropic — Cowork on 3P installation & setup](https://claude.com/docs/cowork/3p/installation) - [Anthropic — Cowork monitoring (OpenTelemetry schema)](https://claude.com/docs/cowork/monitoring) - [Ask Sage — Anthropic API compatibility guide](../api-documentation/Anthropic-Compatibility-Guide.html) - [Ask Sage — Claude Code integration](claude-code.html) (related: terminal CLI vs. desktop app) --- # Codex Source: /docs/v2/integrations/codex.html # Codex Integration Bring Ask Sage's AI models directly into your terminal with Codex CLI ![Codex VSCode](/assets/images/integrations-v2-codex-hero.png) ### About Codex Bring Ask Sage's AI models directly into your terminal or IDE with OpenAI's official CLI Codex, now integrated with Ask Sage. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### Ask Sage API Key Valid user API Key from Ask Sage #### Node.js Required for Codex CLI installation #### Codex Access Install the Codex CLI or VSCode extension in the next section ## Installation ### Installation Codex can be installed in two ways: #### Option 1: VSCode Extension Install the Codex extension directly in Visual Studio Code: 1. Open VSCode and navigate to the Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X` on Mac) 2. Search for "Codex-OpenAI's coding agent" by OpenAI 3. Click the **Install** button to add the extension to your VSCode ![Codex VSCode Extension Installation](/assets/images/integrations-v2-codex-vscode-install.png) #### Option 2: CLI Installation (via npm) ```bash npm i -g @openai/codex ``` --- ## Configuration Methods ### Configuration Methods Configure Ask Sage as the model provider in `~/.codex/config.toml`. If the `config.toml` file doesn't exist, create it. Choose one of the two options below. The example configs below disable Codex update checks to reduce outbound requests. If your environment allows update checks, you can set `check_for_update_on_startup = true`. #### Option 1: Hard-Coded API Key Hard code your Ask Sage API key directly into the config file: ```toml # Core Model Selection model = "gpt-5.4" model_provider = "asksage" # Disable update checks to avoid unnecessary outbound requests. check_for_update_on_startup = true # Disable Web Search (Sends Queries Externally) # "cached" (default) serves results from the web search cache. # "live" fetches the most recent data from the web (same as --search). # "disabled" turns off the web search tool. web_search = "disabled" # Approval & Sandbox approval_policy = "on-request" allow_login_shell = true sandbox_mode = "read-only" model_reasoning_effort = "medium" # Model Provider — Ask Sage Passthrough [model_providers.asksage] name = "AskSage Passthrough" base_url = "https://api.asksage.ai/server/openai/v1" wire_api = "responses" http_headers = { "x-access-tokens" = "your-api-key" } # Features [features] multi_agent = true runtime_metrics = false apps = false apps_mcp_gateway = false responses_websockets = false responses_websockets_v2 = false # Sandbox Settings — No Network from Sandbox [sandbox_workspace_write] writable_roots = [] network_access = false exclude_tmpdir_env_var = false exclude_slash_tmp = false # Network Permissions — Locked to Ask Sage API Only [permissions.network] enabled = true mode = "limited" allowed_domains = ["api.asksage.ai"] denied_domains = ["statsig.com", "statsigapi.net", "featuregates.org", "api.openai.com"] allow_local_binding = false dangerously_allow_non_loopback_proxy = false dangerously_allow_non_loopback_admin = false dangerously_allow_all_unix_sockets = false # Shell Environment Policy [shell_environment_policy] inherit = "all" ignore_default_excludes = false exclude = [] set = {} include_only = [] experimental_use_profile = false # History — Disabled for Classified Environments [history] persistence = "none" # TUI [tui] notifications = false animations = true show_tooltips = true # Analytics — Disabled [analytics] enabled = false # Feedback — Disabled [feedback] enabled = false # OpenTelemetry — Disabled [otel] log_user_prompt = false environment = "production" exporter = "none" trace_exporter = "none" metrics_exporter = "none" # Notices — Suppress All [notice] hide_full_access_warning = true hide_world_writable_warning = true hide_rate_limit_model_nudge = true # MCP Servers [mcp_servers] # Profiles [profiles] # Projects [projects] # Tools [tools] # Windows [windows] sandbox = "unelevated" ``` **Required Parameters:** - `model`: The model to use (e.g., `gpt-5.4` for `Commercial`, `gpt-5.4-gov` for `Government` tenants) - `base_url`: Your Ask Sage Server Base URL with `/server/openai/v1` path. Note this varies based on the instance of Ask Sage you are using. Please verify this Base URL when you Create your API Key, the corresponding Base URL will be underneath. - `http_headers`: Contains your Ask Sage API key via the `x-access-tokens` header #### Option 2: Environment Variable (Recommended) Use an environment variable for your API key instead of hard-coding it. You will need to run the export command each time you open a new terminal before running `codex`: ```bash export ASKSAGE_API_KEY="your-API-Key" ``` Then use this `~/.codex/config.toml`: ```toml # Core Model Selection model = "gpt-5.4" model_provider = "asksage" # Disable update checks to avoid unnecessary outbound requests. check_for_update_on_startup = true # Disable Web Search (Sends Queries Externally) # "cached" (default) serves results from the web search cache. # "live" fetches the most recent data from the web (same as --search). # "disabled" turns off the web search tool. web_search = "disabled" # Approval & Sandbox approval_policy = "on-request" allow_login_shell = true sandbox_mode = "read-only" model_reasoning_effort = "medium" # Model Provider — Ask Sage Passthrough [model_providers.asksage] name = "AskSage Passthrough" base_url = "https://api.asksage.ai/server/openai/v1" wire_api = "responses" env_key = "ASKSAGE_API_KEY" # Features [features] multi_agent = true runtime_metrics = false apps = false apps_mcp_gateway = false responses_websockets = false responses_websockets_v2 = false # Sandbox Settings — No Network from Sandbox [sandbox_workspace_write] writable_roots = [] network_access = false exclude_tmpdir_env_var = false exclude_slash_tmp = false # Network Permissions — Locked to Ask Sage API Only [permissions.network] enabled = true mode = "limited" allowed_domains = ["api.asksage.ai"] denied_domains = ["statsig.com", "statsigapi.net", "featuregates.org", "api.openai.com"] allow_local_binding = false dangerously_allow_non_loopback_proxy = false dangerously_allow_non_loopback_admin = false dangerously_allow_all_unix_sockets = false # Shell Environment Policy [shell_environment_policy] inherit = "all" ignore_default_excludes = false exclude = [] set = {} include_only = [] experimental_use_profile = false # History — Disabled for Classified Environments [history] persistence = "none" # TUI [tui] notifications = false animations = true show_tooltips = true # Analytics — Disabled [analytics] enabled = false # Feedback — Disabled [feedback] enabled = false # OpenTelemetry — Disabled [otel] log_user_prompt = false environment = "production" exporter = "none" trace_exporter = "none" metrics_exporter = "none" # Notices — Suppress All [notice] hide_full_access_warning = true hide_world_writable_warning = true hide_rate_limit_model_nudge = true # MCP Servers [mcp_servers] # Profiles [profiles] # Projects [projects] # Tools [tools] # Windows [windows] sandbox = "unelevated" ``` **Important:** With Option 2, the environment variable is only available in the terminal session where the export was run. Once the terminal is closed, the key will be lost and you will need to export it again. --- ## DoD/DoW Network Configuration (In Development) ### DoD/DoW Network Configuration **Government Users:** For users working on DoD or DoW networks, additional certificate configuration is required. This section is in Development, if you encounter issues setting up your Certs please reach out to us for troubleshooting. #### Prerequisites You'll need a DoD root certificate in PEM format. If you haven't already created this file, see the [DoD Certificate Setup](dod-certs.html#dod-certificate-configuration) guide for instructions. #### Configuration for VSCode Extension Add the following to your VSCode `config.toml`: ```toml # Core Model Selection model = "gpt-5.4-gov" model_provider = "asksage" # Disable update checks to avoid unnecessary outbound requests. check_for_update_on_startup = true # Disable Web Search (Sends Queries Externally) # "cached" (default) serves results from the web search cache. # "live" fetches the most recent data from the web (same as --search). # "disabled" turns off the web search tool. web_search = "disabled" # Approval & Sandbox approval_policy = "on-request" allow_login_shell = true sandbox_mode = "read-only" model_reasoning_effort = "medium" # Model Provider — Ask Sage Passthrough (Azure Government OpenAI) [model_providers.asksage] name = "AskSage Passthrough" base_url = "https://api.genai.army.mil/server/openai/v1" wire_api = "responses" http_headers = { "x-access-tokens" = "your-api-key" } [model_providers.asksage.tls] ca-certificate = "C:\\ProgramData\\ssl\\certs\\DoD_CAs.pem" # Features [features] multi_agent = true runtime_metrics = false apps = false apps_mcp_gateway = false responses_websockets = false responses_websockets_v2 = false # Sandbox Settings — No Network from Sandbox [sandbox_workspace_write] writable_roots = [] network_access = false exclude_tmpdir_env_var = false exclude_slash_tmp = false # Network Permissions — Locked to Ask Sage API Only [permissions.network] enabled = true mode = "limited" allowed_domains = ["api.genai.army.mil"] denied_domains = ["statsig.com", "statsigapi.net", "featuregates.org", "api.openai.com"] allow_local_binding = false dangerously_allow_non_loopback_proxy = false dangerously_allow_non_loopback_admin = false dangerously_allow_all_unix_sockets = false # Shell Environment Policy [shell_environment_policy] inherit = "all" ignore_default_excludes = false exclude = [] set = {} include_only = [] experimental_use_profile = false # History — Disabled for Classified Environments [history] persistence = "none" # TUI [tui] notifications = false animations = true show_tooltips = true # Analytics — Disabled [analytics] enabled = false # Feedback — Disabled [feedback] enabled = false # OpenTelemetry — Disabled [otel] log_user_prompt = false environment = "production" exporter = "none" trace_exporter = "none" metrics_exporter = "none" # Notices — Suppress All [notice] hide_full_access_warning = true hide_world_writable_warning = true hide_rate_limit_model_nudge = true # MCP Servers [mcp_servers] # Profiles [profiles] # Projects [projects] # Tools [tools] # Windows [windows] sandbox = "unelevated" ``` **Important Notes:** - Replace `C:\\ProgramData\\ssl\\certs\\DoD_CAs.pem` with your actual certificate path - Use double backslashes (`\\`) in Windows paths for TOML - Replace `your-api-key` with your actual Ask Sage API Key - For Army GenAI environment, update the `base_url` to your tenant's endpoint - You can reuse the same PEM file across other Ask Sage integrations **Linux/Mac users:** Use forward slashes in paths: `/path/to/AskSage_DoD_Root.pem` #### Option 2: Environment Variable Use an environment variable for your API key instead of hard-coding it. You will need to run the export command each time you open a new terminal before running `codex`: ```bash export ASKSAGE_API_KEY="your-API-Key" ``` Then use this `~/.codex/config.toml`: ```toml # Core Model Selection model = "gpt-5.4-gov" model_provider = "asksage" # Disable update checks to avoid unnecessary outbound requests. check_for_update_on_startup = true # Disable Web Search (Sends Queries Externally) # "cached" (default) serves results from the web search cache. # "live" fetches the most recent data from the web (same as --search). # "disabled" turns off the web search tool. web_search = "disabled" # Approval & Sandbox approval_policy = "on-request" allow_login_shell = true sandbox_mode = "read-only" model_reasoning_effort = "medium" # Model Provider — Ask Sage Passthrough (Azure Government OpenAI) [model_providers.asksage] name = "AskSage Passthrough" base_url = "https://api.genai.army.mil/server/openai/v1" wire_api = "responses" env_key = "ASKSAGE_API_KEY" [model_providers.asksage.tls] ca-certificate = "C:\\ProgramData\\ssl\\certs\\DoD_CAs.pem" # Features [features] multi_agent = true runtime_metrics = false apps = false apps_mcp_gateway = false responses_websockets = false responses_websockets_v2 = false # Sandbox Settings — No Network from Sandbox [sandbox_workspace_write] writable_roots = [] network_access = false exclude_tmpdir_env_var = false exclude_slash_tmp = false # Network Permissions — Locked to Ask Sage API Only [permissions.network] enabled = true mode = "limited" allowed_domains = ["api.genai.army.mil"] denied_domains = ["statsig.com", "statsigapi.net", "featuregates.org", "api.openai.com"] allow_local_binding = false dangerously_allow_non_loopback_proxy = false dangerously_allow_non_loopback_admin = false dangerously_allow_all_unix_sockets = false # Shell Environment Policy [shell_environment_policy] inherit = "all" ignore_default_excludes = false exclude = [] set = {} include_only = [] experimental_use_profile = false # History — Disabled for Classified Environments [history] persistence = "none" # TUI [tui] notifications = false animations = true show_tooltips = true # Analytics — Disabled [analytics] enabled = false # Feedback — Disabled [feedback] enabled = false # OpenTelemetry — Disabled [otel] log_user_prompt = false environment = "production" exporter = "none" trace_exporter = "none" metrics_exporter = "none" # Notices — Suppress All [notice] hide_full_access_warning = true hide_world_writable_warning = true hide_rate_limit_model_nudge = true # MCP Servers [mcp_servers] # Profiles [profiles] # Projects [projects] # Tools [tools] # Windows [windows] sandbox = "unelevated" ``` --- ## Recommended Models ### Recommended Models #### Commercial Tenants We recommend the most recent OpenAI model: `gpt-5.4` #### Government Tenants `gpt-5.4-gov` for tool usage **Model Metadata Note:** If you see the message *"Model metadata for not found. Defaulting to fallback metadata; this can degrade performance and cause issues."* in the terminal, Codex will usually continue to work, but some behavior may be degraded. If you notice tool issues or poor performance, switch to one of the recommended models above or contact support. --- ## Troubleshooting ### Troubleshooting **Issue: "stream disconnected before completion: stream closed before response.completed"** This is a generic error message indicating something is not configured correctly. **Solutions:** - Verify your API key is correct and not missing - Ensure you are using a model your account has access to - Double-check the `base_url` in your `config.toml` - If using Option 2, confirm you exported `ASKSAGE_API_KEY` in the same terminal session **Issue: Authentication errors** **Solutions:** - Verify your Ask Sage API Key is valid - Remove any extra spaces from the API key string - Confirm the `x-access-tokens` header (Option 1) or `env_key` (Option 2) is correctly configured **Issue: Connection errors** **Solutions:** - Verify the `base_url` is correct and accessible - Ensure there are no firewall rules blocking the connection - Check your network connectivity **Need Help?** If you can't resolve the issue, reach out to [support@asksage.ai](mailto:support@asksage.ai). --- ## Additional Resources ### Documentation & Resources - [Codex CLI GitHub Repository](https://github.com/openai/codex) - [Ask Sage OpenAI Compatibility Guide](../api-documentation/OpenAI-Compatibility-Guide.html) - [Codex Configuration Reference](https://developers.openai.com/codex/config-reference) **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # Dify Source: /docs/v2/integrations/dify.html # Ask Sage Model Provider for Dify Use Ask Sage as a model provider inside Dify — 47+ governed AI models through one FedRAMP-authorized API The **Ask Sage Model Provider Plugin** registers Ask Sage as a native model provider in [Dify](https://dify.ai/), the open-source LLM app platform. Once installed, every Ask Sage model (GPT, Claude, Gemini, Llama, Groq, and more) becomes selectable in Dify's model picker for chatflows, agents, workflows, and datasets — using the same Ask Sage API key you already use for other integrations. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the commercial instance at [chat.asksage.ai](https://chat.asksage.ai/), with an API base URL of `https://api.asksage.ai`. The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the **API Base URL** in the plugin credentials to the instance you authenticate against. --- ## At a Glance ### What this integration does Dify is an open-source platform for building LLM applications — chat assistants, agents, workflows, and RAG pipelines. The Ask Sage plugin plugs Ask Sage in as a **model provider**, so the entire Ask Sage model catalog appears in Dify's model selector with the same security boundary, logging, and policy controls you already get from Ask Sage. No model-by-model wiring and no separate per-model credentials. #### 47+ Predefined Models Auto-generated from the Ask Sage catalog #### Dynamic Model Discovery Fetched at runtime with 5-minute caching #### Custom Model Support Add any model your tenant provides #### Token Usage Tracking Prompt + completion tokens reported to Dify #### FedRAMP-Authorized API Governed inference through Ask Sage #### Streaming UI Support Works with Dify's streaming chat surface **Perfect for:** Teams who build chat assistants, agents, and RAG workflows in Dify and want every response routed through Ask Sage's governed, accredited model gateway instead of calling model vendors directly. --- ## Requirements ### Before you begin | Component | Version | | --- | --- | | **Dify** | 1.0+ with Plugin Daemon | | **Dify Plugin Daemon** | 0.5.5+ (see [Known Issues](#known-issues--daemon-053)) | | **Dify Plugin SDK** (`dify_plugin`) | 0.5.x (must match the daemon) | | **Python** | 3.12 (only for remote-debugging installs) | | **Ask Sage Account** | With API key access | **Match the SDK to the daemon.** The `dify_plugin` SDK version must match your Plugin Daemon version. If your daemon is 0.5.x, install `dify_plugin>=0.5.0,<0.6.0`. A mismatch (for example SDK 0.7.x against a 0.5.x daemon) causes **silent connection failures** — the plugin appears installed but never connects. --- ## Step 1 — Create an Ask Sage Account & API Key ### Get access This plugin authenticates against the Ask Sage commercial tenant. If you already have an Ask Sage account and API key, skip ahead to [Getting Your API Key](#getting-your-api-key). 1. Register Go to [chat.asksage.com/register](https://chat.asksage.com/register) and fill in all required fields (first name, last name, company, email, phone, country). 2. Verify your email Submit the form and enter the verification code emailed to you. If the code does not arrive, email [support@asksage.com](mailto:support@asksage.com) to force-validate your account. 3. Sign in Log in at [chat.asksage.com](https://chat.asksage.com/) with your email and password. New accounts include a free 30-day trial with 200,000 inference tokens and 200,000 training tokens. ### Getting Your API Key 1. Open Account settings Sign in at [chat.asksage.com](https://chat.asksage.com/), click the **Settings** cog (bottom left), and select the **Account** tab. 2. Generate a key Scroll to **Manage your API Keys** and generate a new key. Save it securely — you will paste it into the plugin in [Step 4](#step-4--configure-credentials). **MFA:** For multi-factor authentication, we recommend Microsoft Authenticator or Google Authenticator. Configure it on the same Account settings page. --- ## Step 2 — Verify Your Plugin Daemon Version **Check this before installing anything.** Dify 1.13.3 ships with `dify-plugin-daemon:0.5.3-local` by default, which has a bug that breaks `.difypkg` installation. You must upgrade the daemon to **0.5.5+** before installing any local plugin package. (Installing directly from the Dify Marketplace — Option A below — is signed and not affected, but upgrading the daemon is still recommended.) In your `docker-compose.yaml` (for example `C:\dify\docker\docker-compose.yaml`), find the `plugin_daemon` service and pin a fixed image: docker-compose.yaml — plugin_daemon ```yaml plugin_daemon: # Daemon 0.5.3 has a struct-tag bug that rejects plugin_unique_identifier # on the /decode/from_identifier endpoint. Fixed in 0.5.5 (PR #593). image: langgenius/dify-plugin-daemon:0.5.5-local ``` Then restart the daemon: PowerShell ```bash cd C:\dify\docker docker compose up -d plugin_daemon ``` --- ## Step 3 — Install the Plugin Choose the installation method that fits your environment. **Option A (Marketplace)** is the simplest for most users; **Option B (.difypkg)** suits air-gapped or restricted networks; **Option C (Remote debugging)** is for plugin development. ### Option A — Install from the Dify Marketplace (recommended) 1. Open the Marketplace In Dify, go to **Plugins** (top right) and open the **Marketplace** tab. 2. Find Ask Sage Search for **AskSage** (or open the listing at [marketplace.dify.ai/plugin/jlay2026/asksage](https://marketplace.dify.ai/plugin/jlay2026/asksage)) and click **Install**. The package is signed — no host configuration required. 3. Configure credentials Continue to [Step 4](#step-4--configure-credentials) to enter your API key and email. ### Option B — Install from a `.difypkg` Package Use this for air-gapped instances, test builds, or versions not published to the Marketplace. Requires daemon **0.5.5+** (see [Step 2](#step-2--verify-your-plugin-daemon-version)); some instances also require signature verification to be disabled (`FORCE_VERIFYING_SIGNATURE=false`) for unsigned local packages. 1. Download the package Download the latest `asksage-.difypkg` from the project's [Releases page](https://github.com/JLay2026/asksage-dify-plugin/releases). 2. Upload it In Dify, go to **Plugins** → **Install Plugin** and upload the `.difypkg` file. 3. Configure credentials Continue to [Step 4](#step-4--configure-credentials). ### Option C — Remote Debugging (development) For contributors working on the plugin itself. Run the plugin as a local Python process that connects to your Dify instance. Clone & set up the environment ```bash git clone https://github.com/JLay2026/asksage-dify-plugin.git cd asksage-dify-plugin # Create a Python 3.12 virtual environment py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 # Windows # source .venv/bin/activate # Linux/Mac pip install -r requirements.txt ``` Copy `.env.example` to `.env` and fill in your debug key. Find the key in the Dify UI under **Plugins** → the **bug** icon → **Debug Key**. .env ```bash INSTALL_METHOD=remote REMOTE_INSTALL_HOST=localhost REMOTE_INSTALL_PORT=5003 REMOTE_INSTALL_KEY=your-debug-key-from-dify ``` Run the plugin: Run ```bash python -m main ``` --- ## Step 4 — Configure Credentials ### Connect the plugin to Ask Sage After installing, go to **Settings → Model Providers**, find **AskSage**, click it, and enter: | Field | Description | | --- | --- | | **API Key** | Your Ask Sage static API key from **Settings → Account → Manage your API Keys** in the Ask Sage app. | | **Email** | The email address associated with your Ask Sage account. | | **API Base URL** | Default: `https://api.asksage.ai`. Change only if you use a custom or instance-specific Ask Sage deployment (see the callout at the top of this page). | **Validation:** Click **Save**. The plugin validates your credentials by calling Ask Sage's `/server/get-models` endpoint. If the save succeeds, the model list is populated and Ask Sage models are now available in the Dify model picker. **Credentials do not carry over between installs.** API key and base URL are not preserved when you uninstall/reinstall or upgrade via `.difypkg`. Re-enter them after any reinstall. --- ## Refreshing the Model List ### Picking up new Ask Sage models The plugin discovers models dynamically at runtime (cached for 5 minutes), so newly enabled models on your tenant generally appear automatically. To regenerate the bundled predefined-model YAMLs — for example after Ask Sage adds models to your tenant — run the generator script (remote-debugging / source installs): Regenerate model YAMLs ```bash python generate_models.py ``` This calls `/server/get-models`, writes one YAML per model, and updates `_position.yaml`. Image-generation models are filtered out automatically. Restart the plugin (debug mode) or reinstall the `.difypkg` to pick up the changes. --- ## Updating the Plugin How you update depends on how you installed. ### Packaged install (.difypkg) You must repackage and reinstall. The daemon rejects reinstalls at the same version, so bump the `version` in `manifest.yaml` first. 1. Pull the latest code & bump the versionEdit `version:` in `manifest.yaml` (e.g. `0.1.1 → 0.2.0`). 2. RepackageRun `dify plugin package .\asksage` from the *parent* directory (not inside the plugin folder). An "Access is denied" error usually means you are in a directory you cannot write to. 3. Uninstall the old versionIn the Dify console: **Plugins** → find **AskSage** → uninstall. 4. Upload the new package & re-enter credentialsInstall the new `.difypkg`, then re-enter your API key and base URL (they do not carry over). ### Debug mode Updates are simpler: pull the latest code, then stop the running process (`Ctrl+C`) and relaunch with `python -m main`. Dify picks up updated model YAMLs and code on reconnect — no version bump or repackaging required. **Tip:** Use debug mode during active development; switch to a Marketplace or `.difypkg` install for production and team distribution. --- ## Known Issues — Daemon 0.5.3 Dify 1.13.3's default `docker-compose.yaml` pins `langgenius/dify-plugin-daemon:0.5.3-local`, which has a bug in the `DecodePluginFromIdentifier` handler. The Go struct uses a `json:` tag instead of a `form:` tag, so Gin cannot bind the `plugin_unique_identifier` query parameter. The result is a 400 error on `/decode/from_identifier` immediately after a successful `.difypkg` upload: Error ```bash 400: Key: 'PluginUniqueIdentifier' Error: Field validation for 'PluginUniqueIdentifier' failed on the 'required' tag ``` **Fix:** Upgrade to daemon **0.5.5+** (see [Step 2](#step-2--verify-your-plugin-daemon-version)). **References:** - [dify-plugin-daemon PR #593](https://github.com/langgenius/dify-plugin-daemon/pull/593) — daemon-side fix (included in 0.5.5) - [dify PR #34720](https://github.com/langgenius/dify/pull/34720) — API-side backward-compatible fix - [dify issue #34274](https://github.com/langgenius/dify/issues/34274) — original bug report --- ## Known Limitations - **No native streaming** — Ask Sage's `/server/query` returns complete responses. The plugin simulates streaming by yielding the full response as a single chunk, so Dify's streaming UI still works. - **No stop sequences** — Ask Sage does not support stop-sequence parameters. - **Token estimation** — Pre-invocation estimates use a 4-characters-per-token heuristic since Ask Sage does not expose a tokenizer endpoint. Actual usage reported back from responses is accurate. - **No function / tool calling** — Tool-calling support varies by underlying model and is not yet exposed through this plugin. --- ## Resources & Support - **Marketplace listing:** [marketplace.dify.ai/plugin/jlay2026/asksage](https://marketplace.dify.ai/plugin/jlay2026/asksage) - **Source & releases:** [github.com/JLay2026/asksage-dify-plugin](https://github.com/JLay2026/asksage-dify-plugin) - **Dify documentation:** [docs.dify.ai](https://docs.dify.ai/) - **Ask Sage support:** [support@asksage.com](mailto:support@asksage.com) **Feedback Welcome:** Have a request or feedback on this integration? Reach out at [support@asksage.ai](mailto:support@asksage.ai). --- # DoD Certificate Setup Source: /docs/v2/integrations/dod-certs.html # DoD Certificate Setup Prepare a DoD PKI root certificate for secure Ask Sage connections on DoD/DoW networks ### About This Guide Government users on DoD or DoW networks need a DoD PKI root certificate to establish trusted TLS connections to Ask Sage. This guide covers downloading and converting that certificate. Once you have the resulting `.pem` file, apply it in your specific tool's configuration—see the [Claude Code](claude-code.html) and [Codex](codex.html) integration guides for tool-specific setup steps. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before configuring DoD/DoW certificates, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### API Key [Generate your key](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) #### OpenSSL Used to convert the certificate bundle to PEM format --- ## DoD Certificate Configuration ### DoD Certificate Configuration **Government Users:** For secure government environments requiring DoD PKI certificates, follow this process. The resulting `.pem` file can be reused across any Ask Sage integration that supports a custom CA certificate. 1. Download DoD Certificates Navigate to [DoD Cyber Exchange PKI/PKE](https://www.cyber.mil/pki-pke/tools-configuration-files/) Download **"PKI CA Certificate Bundles: PKCS#7 for DoD PKI Only"** (latest version) Extract the downloaded ZIP file (e.g., `unclass-certificates_pkcs7_DoD.zip`) Locate the `.der.p7b` file (e.g., `Certificates_PKCS7_v5_14_DoD.der.p7b`) Save to a permanent location on your system 2. Convert Certificate Format Open a terminal with OpenSSL (Git Bash on Windows works well): ```bash # Navigate to your certificate directory cd /path/to/certificates # Convert DER to PEM format openssl pkcs7 \ -in Certificates_PKCS7_v5_14_DoD.der.p7b \ -inform DER \ -print_certs \ -out Certificates_PKCS7_v5_14_DoD.der.pem ``` This creates the `.pem` file you'll reference in your integration's configuration. 3. Reference the Certificate in Your Tool Point your integration's CA certificate/root certificate setting at the `.pem` file you just created. The exact setting name varies by tool—see the [Claude Code](claude-code.html#dod-dow-network-configuration) and [Codex](codex.html) integration guides for the specific configuration keys and file locations. **Army GenAI Environment:** The same certificate applies when connecting to the Army GenAI endpoint (`https://api.genai.army.mil/server/`) instead of the commercial endpoint—only the base URL changes. **Path Format:** - **Windows:** Use forward slashes or escaped backslashes `C:/Users/username/certs/cert.pem` or `C:\\Users\\username\\certs\\cert.pem` - **Mac/Linux:** Standard Unix paths `/Users/username/certs/cert.pem` --- ## Troubleshooting ### Troubleshooting **Issue: Certificate Errors** SSL/TLS certificate validation failures **Solutions:** - Verify `.pem` file path is absolute and correct - Use forward slashes in paths (even on Windows) - Ensure certificate conversion completed successfully - Download the latest DoD certificate bundle - Check file permissions (must be readable) --- ## Additional Resources ### Documentation & Resources - [DoD Cyber Exchange PKI/PKE](https://www.cyber.mil/pki-pke/tools-configuration-files/) - Download the latest DoD certificate bundle - [Ask Sage API Documentation](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) - [Claude Code Integration](claude-code.html) - Apply your certificate for terminal-based access - [Codex Integration](codex.html) - Apply your certificate for terminal-based access **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # GitLab Duo Source: /docs/v2/integrations/gitlab-duo.html # GitLab Duo Integration Power GitLab Duo Chat and Code Suggestions with Ask Sage's FedRAMP-compliant AI models ### About This Integration GitLab Duo supports self-hosted model providers through its AI Gateway. This guide walks you through connecting Ask Sage's OpenAI-, Anthropic-, and Gemini-compatible passthrough surfaces to GitLab Duo Chat, Code Suggestions, and Duo Workflow — keeping your AI traffic within FedRAMP-compliant infrastructure. --- --- **Instance-Specific Base URL:** The endpoints shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### Ask Sage API Key From your tenant under **Account > API Keys** #### GitLab EE With a Duo Enterprise license applied #### AI Gateway Running and reachable, e.g. `http://aigw.local:5052/-/health` ## Provider Surfaces ### Provider Surfaces Ask Sage exposes three provider-compatible surfaces. Each maps to a GitLab **model family**, an **endpoint**, and a **model-identifier prefix** — you need the matching row when you add a model in GitLab. | Provider | GitLab model family | Endpoint (base URL) | Identifier prefix | | --- | --- | --- | --- | | OpenAI | `GPT` | `https://api.asksage.ai/server/openai/v1` | `custom_openai/` | | Anthropic | `Claude` | `https://api.asksage.ai/server/anthropic` | `anthropic/` | | Gemini | `Gemini` | `https://api.asksage.ai/server/google/v1beta` | `gemini/` | **Anthropic Endpoint Note:** Enter `https://api.asksage.ai/server/anthropic` *without* a trailing `/v1`. GitLab's AI Gateway appends `/v1/messages` automatically. Including `/v1` in the endpoint produces a double path (`/v1/v1/messages`) and causes 404 errors. ## Step 1: Discover Available Model IDs ### Discover Available Model IDs Ask Sage's available models depend on your subscription tier. Retrieve the list before configuring GitLab to confirm the model IDs your account can access: ```bash curl -s https://api.asksage.ai/server/openai/v1/models \ -H "Authorization: Bearer $ASK_SAGE_API_KEY" \ | python -m json.tool | grep '"id"' ``` When you enter model IDs in GitLab, prefix each with the matching provider identifier prefix. For example, `anthropic/claude-sonnet-4-6` for a Claude model, or `custom_openai/gpt5` for a GPT model. **Common Models** (verify availability against your account): - `anthropic/claude-sonnet-4-6` — Anthropic Claude Sonnet 4.6 - `custom_openai/gpt5` — GPT-5 - `gemini/gemini-2.5-flash` — Google Gemini 2.5 Flash ## Step 2: Verify Your API Key ### Verify Your API Key with the Passthrough APIs Before configuring GitLab, confirm your API key and model IDs work by calling Ask Sage's passthrough surfaces directly. Use the surface that matches the provider you're configuring. #### OpenAI-style passthrough Use this when the GitLab model family is `GPT` and the identifier prefix is `custom_openai/`. ```bash curl -X POST https://api.asksage.ai/server/openai/v1/chat/completions \ -H "Authorization: Bearer $ASK_SAGE_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "gpt5.5", "stream": true, "messages": [{"role": "user", "content": "Hello"}] }' ``` #### Anthropic-style passthrough Use this when the GitLab model family is `Claude` and the identifier prefix is `anthropic/`. Auth may be supplied as `Authorization: Bearer`, `x-access-tokens`, or `x-api-key`. ```bash curl -X POST https://api.asksage.ai/server/anthropic/v1/messages \ -H "Authorization: Bearer $ASK_SAGE_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 1024, "stream": true, "messages": [{"role": "user", "content": "Hello"}] }' ``` #### Gemini-style passthrough Use this when the GitLab model family is `Gemini` and the identifier prefix is `gemini/`. Authentication uses the `x-access-tokens` header. Model identifiers accept multiple formats: `gemini-2.5-flash`, `models/gemini-2.5-pro`, or `publishers/google/models/gemini-2.5-pro`. ```bash curl -X POST \ 'https://api.asksage.ai/server/google/v1beta/models/gemini-2.5-flash:streamGenerateContent' \ -H "x-access-tokens: $ASK_SAGE_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "contents": [{"role": "user", "parts": [{"text": "Hello"}]}] }' ``` --- ## Step 3: Add Self-Hosted Models in GitLab ### Add Self-Hosted Models in GitLab Add one model entry per Duo feature you want to configure. 1. In the upper-right corner, select **Admin**. 2. In the left sidebar, select **GitLab Duo**. 3. Under **GitLab Duo Model Selection**, select **Configure models for GitLab Duo**. 4. Select the **Self-hosted models** tab, then select **Add self-hosted model**. 5. Fill in the fields and select **Save**. See the recommended settings below. **API Key Field:** Enter your Ask Sage API key from **Account > API Keys** in your Ask Sage tenant. GitLab stores this value encrypted and the AI Gateway sends it as a `Bearer` token to the endpoint you configured. **Test Connection Timeout:** The **Test Connection** button uses a 3-second timeout. Ask Sage may not respond within 3 seconds for slower models or cold starts. If the test fails but Duo Chat works normally, the timeout is a false alarm — not a real connectivity problem. #### Duo Chat (recommended: a lightweight model) | Field | Value | | --- | --- | | Name | `Ask Sage — Duo Chat` | | Model family | `GPT` | | Endpoint | `https://api.asksage.ai/server/openai/v1` | | Model identifier | `custom_openai/gpt5-mini` | | API key | Your Ask Sage API key | #### Code Suggestions — Completion (recommended: a capable recent model) | Field | Value | | --- | --- | | Name | `Ask Sage — Code Completion` | | Model family | `Claude` | | Endpoint | `https://api.asksage.ai/server/anthropic` | | Model identifier | `anthropic/claude-opus-4-8` | | API key | Your Ask Sage API key | #### Code Suggestions — Generation (recommended: a frontier model) | Field | Value | | --- | --- | | Name | `Ask Sage — Code Generation` | | Model family | `GPT` | | Endpoint | `https://api.asksage.ai/server/openai/v1` | | Model identifier | `custom_openai/gpt5.5` | | API key | Your Ask Sage API key | ## Step 4: Assign Models to Duo Features ### Assign Models to Duo Features Navigate to **Admin > GitLab Duo > Configure models for GitLab Duo** and assign each model you created to its corresponding feature. | Duo Feature | Recommended model entry | | --- | --- | | Duo Chat | Ask Sage — Duo Chat | | Code generation | Ask Sage — Code Generation | | Code completion | Ask Sage — Code Completion | | Duo Workflow (agentic) | Ask Sage — Duo Chat (or a dedicated model) | **Unassigned Features:** Features you do not assign default to the AI Gateway's cloud-connected path if licensed. For a fully self-hosted setup, assign a model to every feature you intend to use. ## Step 5: Set the Request Timeout ### Set the Request Timeout GitLab's default 30-second timeout may be too short for slower models or long prompts. Navigate to **Admin > GitLab Duo > Change configuration > Request timeout** and set a value appropriate for your use case: | Use case | Recommended timeout | | --- | --- | | Fast models (GPT-4.1, Gemini Flash) | 60 seconds | | Standard use | **120 seconds** | | Large prompts or slow models | 360 seconds | ## Step 6: Verify ### Verify the Configuration #### Health Check Navigate to **Admin > GitLab Duo > Run health check**. This tests AI Gateway connectivity and confirms each configured model endpoint responds. #### Rake Task ```bash docker exec gitlab gitlab-rake "gitlab:duo:verify_self_hosted_setup[root]" ``` #### Live Chat Test Open any GitLab project and open the Duo Chat panel in the sidebar. Send a message — a response should stream within a few seconds. If nothing appears, check the logs: ```bash # AI Gateway — outbound requests to Ask Sage docker logs gitlab-aigw 2>&1 | grep -i "asksage\|error" | tail -20 # Workhorse — WebSocket / gRPC errors docker exec gitlab bash -c "tail -50 /var/log/gitlab/gitlab-workhorse/current" ``` --- ## Troubleshooting ### Troubleshooting **Issue: Duo Chat produces no response — DAP service URL** On GitLab 19.2 and later, Workhorse reads the DAP service URL from `ApplicationSetting`, not `Ai::Setting`. If the value is only set on `Ai::Setting`, Workhorse reads `nil` and the WebSocket returns HTTP 500 with `invalid target address "": missing address`. **Diagnose:** ```bash docker exec gitlab gitlab-rails runner " puts 'AppSetting: ' + ApplicationSetting.current.duo_agent_platform_service_url.inspect fs = Ai::FeatureSetting.find_by(feature: :duo_agent_platform_agentic_chat) puts 'Workhorse sees: ' + Gitlab::DuoWorkflow::Client.url_for(feature_setting: fs, user: User.find_by(username: 'root')).inspect " ``` Both values must print `"gitlab-aigw:50052"` — no URL scheme prefix. If either prints `nil`, set it: ```bash docker exec gitlab gitlab-rails runner "ApplicationSetting.current.update!(duo_agent_platform_service_url: 'gitlab-aigw:50052', self_hosted_duo_agent_platform_service_secure: false)" ``` **Issue: Chat fails with a TLS certificate error (online cloud license)** When the GitLab license is a subscription-based online cloud license, GitLab instructs Workhorse to open a billing tracking stream to `duo-workflow-svc.runway.gitlab.net:443`. In an isolated Docker environment, the TLS certificate cannot be verified, so Workhorse aborts the WebSocket before any message reaches the AI Gateway. The Workhorse log contains: `failed to open self-hosted tracking stream ... x509: certificate signed by unknown authority`. **Diagnose:** ```bash docker exec gitlab gitlab-rails runner ' puts "online_cloud_license? = #{License.current&.online_cloud_license?}" puts "should_bill? = #{Ai::SelfHostedDapBilling.should_bill?(Ai::FeatureSetting.find_by(feature: :duo_agent_platform_agentic_chat))}" ' ``` If both print `true`, patch `should_bill?` to return `false` — this removes the cloud tracking stream from the Workhorse config. The patch survives `gitlab-ctl restart` but is lost on container recreation. ```bash docker exec gitlab bash -c "sed -i 's/def self\.should_bill?(feature_setting)/def self.should_bill?(feature_setting)\n return false # local-dev: cloud tracking stream disabled/' /opt/gitlab/embedded/service/gitlab-rails/ee/lib/ai/self_hosted_dap_billing.rb" docker exec gitlab gitlab-ctl restart puma ``` Verify the patch applied: ```bash docker exec gitlab bash -c "grep -A2 'def self.should_bill' /opt/gitlab/embedded/service/gitlab-rails/ee/lib/ai/self_hosted_dap_billing.rb" ``` Expected output: the line immediately after `def self.should_bill?` reads `return false`. **Issue: gRPC service not running on port 50052** The AI Gateway container image does not include `ss` or `netstat`. Check the startup log instead: ```bash docker logs gitlab-aigw 2>&1 | grep -E "gRPC server on port 50052|Started server" ``` If the line is absent, the gRPC service did not start — often a JWKS-fetch race when the gateway started before GitLab was ready. Restart the gateway: `docker restart gitlab-aigw` **Issue: 429 / rate limit errors in AI Gateway logs** Ask Sage applies rate limits per API key. If you see 429s: - Check your Ask Sage account tier limits - Reduce concurrent Duo Chat sessions - Switch to a model with higher rate limits on your plan **Issue: Model identifier not found / 404** **Solutions:** - Verify the model ID exactly matches what `/v1/models` returns — model IDs are case-sensitive - Confirm the identifier prefix matches the provider surface (`custom_openai/`, `anthropic/`, or `gemini/`) - For Anthropic: enter the endpoint without `/v1` — the AI Gateway appends it automatically - Confirm the model is available on your Ask Sage subscription tier --- ## Additional Resources ### Documentation & Resources directly from GitLab - [GitLab: Configure Duo features to use self-hosted models](https://docs.gitlab.com/administration/gitlab_duo_self_hosted/configure_duo_features/) - [GitLab: Supported LLM serving platforms](https://docs.gitlab.com/administration/gitlab_duo_self_hosted/supported_llm_serving_platforms/) - [GitLab: Duo self-hosted overview](https://docs.gitlab.com/administration/gitlab_duo_self_hosted/) **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # OpenClaw Source: /docs/v2/integrations/openclaw.html # OpenClaw Integration Use Ask Sage as a custom model provider for the OpenClaw AI agent platform ### About OpenClaw [OpenClaw](https://docs.openclaw.ai) is an open-source AI agent platform that orchestrates autonomous agents with tool access, memory, and multi-channel delivery. OpenClaw supports custom model providers via Anthropic, OpenAI, and Google API formats — making it fully compatible with Ask Sage's API passthrough. By configuring Ask Sage as a provider, your OpenClaw agents gain access to **50+ models across all major providers** through a single API key — no per-model billing, no separate accounts. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### Ask Sage API Key Generate from your [Account Settings](https://chat.asksage.ai/account) #### Ask Sage Subscription Plan with API access (5M Ultimate recommended) #### OpenClaw Installed [Install OpenClaw](https://docs.openclaw.ai) on your system ## Recommended Plan ### Recommended Plan for OpenClaw **5M Ultimate Plan ($200/mo) — Recommended for Agent Workloads** AI agents consume significantly more tokens than interactive chat. Autonomous tool loops, multi-step reasoning, large context windows, and background tasks add up fast. The **5M Ultimate plan** provides 5 million tokens per month — enough headroom for sustained agent workflows without running into limits mid-task. **Why Ask Sage is Ideal for AI Agents:** Ask Sage uses **token-based pricing** — there's no per-model billing and no separate API keys for each provider. One API key gives your OpenClaw agents access to **50+ models** across Anthropic, OpenAI, and Google. Switch between Claude, GPT, and Gemini freely without managing multiple accounts or worrying about per-model charges. --- ## Configuration ### Configuration Ask Sage is registered with OpenClaw as a custom model provider. Ask Sage supports three API formats — Anthropic Messages, OpenAI Responses, and Google Generative AI — so you can pick the format that matches the model family you want to use, or register all three. **Recommended: Use the `openclaw` CLI (OpenClaw 2026.5+)** Starting in OpenClaw **2026.5**, the canonical way to register and switch models is the `openclaw onboard` + `openclaw models` CLI. Direct edits to `openclaw.json` still work but are now guarded by safety checks (clobber-protect, size-drop, protected-paths) — the CLI bypasses all of those because it uses the same atomic write path the gateway trusts. The JSON snippets below are still shown for reference and for environments that pre-bake their config (e.g. containers, IaC), but for day-to-day use the CLI is faster and won't trip safety guards. #### Quickstart — Register Ask Sage with One Command The fastest path is the non-interactive `openclaw onboard` flow. This single command registers Ask Sage as a custom Anthropic-compatible provider and sets a default model: ```bash export ASKSAGE_API_KEY="YOUR_ASK_SAGE_API_KEY" openclaw onboard \ --flow quickstart \ --auth-choice custom-api-key \ --custom-provider-id asksage-anthropic \ --custom-base-url "https://api.asksage.ai/server/anthropic" \ --custom-compatibility anthropic \ --custom-model-id google-claude-48-opus \ --custom-text-input \ --custom-image-input \ --custom-api-key "$ASKSAGE_API_KEY" \ --accept-risk \ --non-interactive # Set Opus 4.8 as the default model openclaw models set asksage-anthropic/google-claude-48-opus # Add a fallback chain (recommended) openclaw models fallbacks add asksage-anthropic/google-claude-46-sonnet # Verify openclaw models list ``` Repeat the `openclaw onboard` step with `--custom-provider-id asksage-openai` + `--custom-base-url "https://api.asksage.ai/server/openai/v1"` + `--custom-compatibility openai` to add GPT models, and once more with `asksage-google` + `https://api.asksage.ai/server/google/v1beta` for Gemini. Each call is additive — it does not overwrite previously-registered providers. #### Useful follow-up commands ```bash # See every model OpenClaw can route to (default, fallbacks, configured) openclaw models list # Switch the default model later openclaw models set asksage-anthropic/google-claude-46-sonnet # Manage fallback order openclaw models fallbacks list openclaw models fallbacks add asksage-google/google-gemini-2.5-pro openclaw models fallbacks remove asksage-openai/gpt-4.1 openclaw models fallbacks clear # Re-discover a provider's catalog after Ask Sage adds new models openclaw models auth login --provider asksage-anthropic # Show effective config + auth state openclaw models status ``` #### Reference: Equivalent JSON Configuration If you prefer to bake the configuration into `openclaw.json` directly — for example, in a container image, a Helm chart, or an Infrastructure-as-Code template — the same setup looks like this. Edit the file at `~/.openclaw/openclaw.json` (or use `openclaw config file` to print the active path). **Safety guards on direct JSON edits (2026.5+)** If the gateway is running while you edit, it may reject the change with one of: `clobbered` (file changed under the gateway), `size-drop` (new file is >20% smaller than the last good snapshot), or `protected-paths` (an API key, model id, or other locked field changed without going through the proper command). Stop the gateway first (`openclaw gateway stop`) for hand edits, or use `openclaw config set --batch-file ops.json` for scripted changes — it goes through the same trusted writer that the gateway accepts. #### Anthropic-Style Provider (Claude Models) Use the Anthropic Messages API format for Claude models: ```json { "models": { "providers": { "asksage-anthropic": { "baseUrl": "https://api.asksage.ai/server/anthropic", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "anthropic-messages", "models": [ { "id": "google-claude-48-opus", "name": "Claude Opus 4.8 (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 128000 }, { "id": "google-claude-47-opus", "name": "Claude Opus 4.7 (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 128000 }, { "id": "google-claude-46-sonnet", "name": "Google Claude 4.6 Sonnet (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 800000, "maxTokens": 32768 } ] } } }, "agents": { "defaults": { "model": { "primary": "asksage-anthropic/google-claude-48-opus" } } } } ``` #### OpenAI-Style Provider (GPT Models) Use the OpenAI Responses API format for GPT models: ```json { "models": { "providers": { "asksage-openai": { "baseUrl": "https://api.asksage.ai/server/openai/v1", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "openai-responses", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 (Ask Sage)", "reasoning": false, "input": ["text", "image"], "contextWindow": 1047576, "maxTokens": 32768 } ] } } } } ``` #### Google-Style Provider (Gemini Models) Use the Google Generative AI format for Gemini models: ```json { "models": { "providers": { "asksage-google": { "baseUrl": "https://api.asksage.ai/server/google/v1beta", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "google-generative-ai", "models": [ { "id": "google-gemini-2.5-pro", "name": "Gemini 2.5 Pro (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65536 } ] } } } } ``` --- ## Full Multi-Provider Configuration ### Full Multi-Provider Configuration You can configure all three providers simultaneously, giving your OpenClaw agents access to Claude, GPT, and Gemini models through a single Ask Sage API key: ```json { "models": { "providers": { "asksage-anthropic": { "baseUrl": "https://api.asksage.ai/server/anthropic", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "anthropic-messages", "models": [ { "id": "google-claude-48-opus", "name": "Claude Opus 4.8 (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 128000 }, { "id": "google-claude-47-opus", "name": "Claude Opus 4.7 (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 128000 }, { "id": "google-claude-46-sonnet", "name": "Google Claude 4.6 Sonnet (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 800000, "maxTokens": 32768 } ] }, "asksage-openai": { "baseUrl": "https://api.asksage.ai/server/openai/v1", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "openai-responses", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 (Ask Sage)", "reasoning": false, "input": ["text", "image"], "contextWindow": 1047576, "maxTokens": 32768 }, { "id": "o3-mini", "name": "O3 Mini (Ask Sage)", "reasoning": true, "input": ["text"], "contextWindow": 800000, "maxTokens": 100000 } ] }, "asksage-google": { "baseUrl": "https://api.asksage.ai/server/google/v1beta", "apiKey": "YOUR_ASK_SAGE_API_KEY", "auth": "api-key", "api": "google-generative-ai", "models": [ { "id": "google-gemini-2.5-pro", "name": "Gemini 2.5 Pro (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65536 }, { "id": "google-gemini-2.5-flash", "name": "Gemini 2.5 Flash (Ask Sage)", "reasoning": true, "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65536 } ] } } }, "agents": { "defaults": { "model": { "primary": "asksage-anthropic/google-claude-48-opus" } } } } ``` **Switching Models:** Change the `agents.defaults.model.primary` value to switch your default agent model. For example, set it to `asksage-openai/gpt-4.1` or `asksage-google/google-gemini-2.5-pro` to use a different provider as your default. --- ## Available Models ### Available Models Below are key models available through Ask Sage, organized by provider API format. Use the **Model ID** value in your `openclaw.json` configuration. #### Anthropic Models (anthropic-messages) | Model ID | Name | Context Window | Max Tokens | Reasoning | | --- | --- | --- | --- | --- | | `google-claude-48-opus` | Claude 4.8 Opus (via GCP) | 1M | 128,000 | | | `google-claude-47-opus` | Claude 4.7 Opus (via GCP) | 1M | 128,000 | | | `google-claude-46-opus` | Claude 4.6 Opus (via GCP) | 800K | 32,768 | | | `google-claude-46-sonnet` | Claude 4.6 Sonnet (via GCP) | 800K | 32,768 | | | `google-claude-45-opus` | Claude 4.5 Opus (via GCP) | 135K | 32,768 | | | `google-claude-45-sonnet` | Claude 4.5 Sonnet (via GCP) | 135K | 32,768 | | | `google-claude-45-haiku` | Claude 4.5 Haiku (via GCP) | 135K | 32,768 | | | `google-claude-4-opus` | Claude 4 Opus (via GCP) | 167K | 32,768 | | | `google-claude-4-sonnet` | Claude 4 Sonnet (via GCP) | 135K | 32,768 | | #### OpenAI Models (openai-responses) | Model ID | Name | Context Window | Max Tokens | Reasoning | | --- | --- | --- | --- | --- | | `gpt-o4-mini` | GPT o4 Mini | 120K | 100,000 | | | `gpt-o3` | GPT o3 | 120K | 100,000 | | | `gpt-o3-mini` | GPT o3 Mini | 120K | 65,536 | | | `gpt-o1` | GPT o1 | 100K | 32,768 | | | `gpt-5.4` | GPT 5.4 | 170K | 32,768 | | | `gpt-5.4-nano` | GPT 5.4 Nano | 170K | 32,768 | | | `gpt-5.2` | GPT 5.2 | 170K | 32,768 | | | `gpt-5.1` | GPT 5.1 | 170K | 32,768 | | | `gpt-5` | GPT 5 | 170K | 32,768 | | | `gpt-5-mini` | GPT 5 Mini | 170K | 32,768 | | | `gpt-5-nano` | GPT 5 Nano | 170K | 32,768 | | | `gpt-4.1` | GPT 4.1 | 1,047K | 32,768 | | | `gpt-4.1-mini` | GPT 4.1 Mini | 1,047K | 32,768 | | | `gpt-4.1-nano` | GPT 4.1 Nano | 1,047K | 32,768 | | #### Google Models (google-generative-ai) | Model ID | Name | Context Window | Max Tokens | Reasoning | | --- | --- | --- | --- | --- | | `google-gemini-2.5-pro` | Gemini 2.5 Pro | 924K | 65,536 | | | `google-gemini-2.5-flash` | Gemini 2.5 Flash | 924K | 65,536 | | | `google-gemini-2.5-flash-image` | Gemini 2.5 Flash (Image) | 32K | 65,536 | | | `google-imagen-4` | Imagen 4 (Image Generation) | — | — | | | `google-veo-3-fast` | Veo 3 Fast (Video Generation) | — | — | | --- ## Government & DoD Models ### Government & DoD Models **FedRAMP High & DoD IL5/IL6 Authorized:** Ask Sage provides access to government-authorized models that meet FedRAMP High and DoD IL5/IL6 compliance requirements. These models use dedicated government endpoints and are suitable for CUI and classified workloads. #### Government Model IDs | Model ID | Description | Provider | | --- | --- | --- | | `gpt-4.1-gov` | GPT 4.1 (Azure Government) | OpenAI | | `gpt-o3-mini-gov` | O3 Mini (Azure Government) | OpenAI | | `aws-bedrock-claude-45-sonnet-gov` | Claude Sonnet 4.5 (AWS GovCloud) | Anthropic | | `aws-bedrock-claude-37-sonnet-gov` | Claude Sonnet 3.7 (AWS GovCloud) | Anthropic | | `aws-bedrock-claude-35-haiku-gov` | Claude Haiku 3.5 (AWS GovCloud) | Anthropic | **Important:** Government models require a government tenant Ask Sage account and use tenant-specific base URLs. The base URL will be displayed when you generate your API key — always use the one issued to your tenant rather than the commercial endpoint shown elsewhere in this guide. Contact your organization's Ask Sage administrator for access. --- ## Verification ### Verification After registering your providers (via CLI or JSON), verify everything is wired up correctly: #### List Configured Models The fastest check — shows the active default, fallback chain, and any aliases: ```bash openclaw models list ``` You should see rows like `asksage-anthropic/google-claude-48-opus text+image 1024k no yes default,configured`. The `default` tag confirms the primary model and `fallback#N` tags confirm the failover order. #### Check Auth + Provider Health ```bash # Show auth profiles for all providers openclaw models auth list # Full status summary (gateway, runtime, model, usage) openclaw models status ``` Your Ask Sage providers should appear with `auth: yes` and a populated `last seen` timestamp. #### Test a Conversation Start an interactive session to confirm the model responds correctly: ```bash # Start OpenClaw and send a test message openclaw start ``` If the agent responds, your Ask Sage integration is working correctly. --- ## Troubleshooting ### Troubleshooting **Issue: "Invalid API key" or authentication errors** **Solutions:** - Verify your API key is correct — copy it again from your [Account Settings](https://chat.asksage.ai/account) - Check that the `apiKey` field in `openclaw.json` has no extra spaces or line breaks - Ensure your Ask Sage subscription is active and includes API access **Issue: "Model not found" errors** **Solutions:** - Verify the `id` in your model definition matches a valid Ask Sage model ID - Check that you're using the correct API format for the model (e.g., Claude models use `anthropic-messages`, not `openai-responses`) - Government models require a government tenant — commercial API keys cannot access `-gov` models **Issue: Request timeouts** **Solutions:** - Check your network connectivity to `api.asksage.ai` - Verify no firewall rules are blocking outbound HTTPS connections - Reasoning models (e.g., `google-claude-46-sonnet` with extended thinking) may take longer — increase timeout values in OpenClaw's configuration if needed **Issue: Provider not appearing in `openclaw status`** **Solutions:** - Validate your `openclaw.json` is valid JSON (use `jq . openclaw.json` to check), or just use `openclaw config validate` - Ensure the provider is under `models.providers`, not at the root level - Most changes hot-reload automatically. If they don't, restart the gateway: `openclaw gateway restart` **Issue: `openclaw config set` rejects with `size-drop`, `clobbered`, or `protected-paths` (2026.5+)** **Why:** OpenClaw 2026.5 added safety guards around the model-provider section because the gateway auto-discovers and enriches model metadata at runtime. Replacing a whole provider block with a smaller hand-written one will look like a drop. Editing the file directly while the gateway is running will look like a clobber. Renaming a model id, swapping an API key, or rewriting an api compatibility string in-place trips protected-paths. **Solutions:** - Use the `openclaw models` CLI for default/fallback/alias changes — it never trips guards - Use `openclaw onboard --auth-choice custom-api-key` to add or re-auth a provider — bypasses protected-paths - For larger refactors, stop the gateway first (`openclaw gateway stop`), edit, then restart - Rejected payloads are saved to `~/.openclaw/openclaw.json.rejected.` and the previous good copy to `openclaw.json.last-good` — diff them to see what the guard caught **Need Help?** If you can't resolve the issue, reach out to [support@asksage.ai](mailto:support@asksage.ai). --- ## Additional Resources ### Documentation & Resources - [OpenClaw Documentation](https://docs.openclaw.ai) - [Ask Sage Platform](https://chat.asksage.ai/) - [Ask Sage OpenAI API Compatibility Guide](../api-documentation/OpenAI-Compatibility-Guide.html) - [Codex Integration](codex.html) — Another tool compatible with Ask Sage - [Claude Code Integration](claude-code.html) — Another tool compatible with Ask Sage **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # opencode Source: /docs/v2/integrations/opencode.html # opencode Integration Bring Ask Sage AI directly into VS Code with the opencode extension and CLI Use [opencode for VS Code](https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode) with Ask Sage as your AI provider — all inference stays within your organization's approved instance. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Prerequisites Before you begin, ensure you have the following: #### Ask Sage Account [Sign up or log in](https://chat.asksage.ai/) #### API Key [Generate your key](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) #### opencode CLI Install from [opencode.ai](https://opencode.ai) #### VS Code Extension Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode) --- ## Installation ### Step 1: Install the opencode CLI ### Install opencode CLI opencode is a terminal-based AI coding agent. Install it via npm or your preferred package manager: ```bash curl -fsSL https://opencode.ai/install | bash ``` ```bash npm install -g opencode-ai ``` Verify the installation: ```bash opencode --version ``` ### Step 2: Install the VS Code Extension ### Install VS Code Extension 1. Open Extensions Open the Extensions panel in VS Code (`Ctrl+Shift+X` / `Cmd+Shift+X`) 2. Search opencode Search for **"opencode"** by SST 3. Install Click **Install** on the **opencode** extension by SST **Direct Install:** You can also install via the [VS Code Marketplace page](https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode) or run `code --install-extension sst-dev.opencode` from your terminal. --- ## Configuration ### Ask Sage GPT-5.5 Configuration opencode reads its configuration from `opencode.json`. Create or update this file in your project root (or globally at `~/.config/opencode/opencode.json`) with the following: **Configuration File Locations:** - **Project-level:** `opencode.json` in your project root - **Global:** `~/.config/opencode/opencode.json` (Mac/Linux) or `%APPDATA%\opencode\opencode.json` (Windows) Project-level config takes precedence and is recommended when working within a specific Ask Sage tenant. #### opencode.json — Ask Sage GPT-5.5 Example ```json { "$schema": "https://opencode.ai/config.json", "disabled_providers": ["opencode"], "share": "disabled", "model": "asksage/gpt-5.5", "provider": { "asksage": { "npm": "@ai-sdk/openai", "name": "Ask Sage", "options": { "baseURL": "https://api.asksage.ai/server/openai/v1", "apiKey": "YOUR_API_KEY" }, "models": { "gpt-5.5": { "name": "GPT-5.5", "limit": { "context": 128000, "output": 16384 } } } } } } ``` **Important:** Replace `YOUR_API_KEY` with your actual Ask Sage API key. The `model` field at the top sets the default model — it must use the format `asksage/` where the model key matches one of the entries under `models`. **Base URL:** Use the base URL that matches your Ask Sage instance: - **Production:** `https://api.asksage.ai/server/openai/v1` - **Army GenAI:** `https://api.genai.army.mil/server/openai/v1` ### Claude Model Configuration ### Ask Sage Claude 4.8 Configuration Claude models use Anthropic's native API format. Add a second provider block to your `opencode.json` using `@ai-sdk/anthropic` pointed at Ask Sage's Anthropic-compatible endpoint: #### opencode.json — Ask Sage Claude 4.8 Opus Example ```json { "$schema": "https://opencode.ai/config.json", "disabled_providers": ["opencode"], "share": "disabled", "model": "asksage-claude/google-claude-48-opus", "provider": { "asksage-claude": { "npm": "@ai-sdk/anthropic", "name": "Ask Sage (Claude)", "options": { "baseURL": "https://api.asksage.ai/server/anthropic/v1", "apiKey": "YOUR_API_KEY" }, "models": { "google-claude-48-opus": { "name": "Claude 4.8 Opus", "limit": { "context": 200000, "output": 32000 } } } } } } ``` **Anthropic Base URL:** Use the Anthropic-compatible base URL for your Ask Sage instance: - **Production:** `https://api.asksage.ai/server/anthropic/v1` - **Army GenAI:** `https://api.genai.army.mil/server/anthropic/v1` **Combining Providers:** You can include both the GPT and Claude provider blocks in the same `opencode.json` and switch between them by changing the top-level `model` field — e.g. `asksage/gpt-5.5` or `asksage-claude/google-claude-48-opus`. Reload the VS Code window after any config change. **Important:** Replace `YOUR_API_KEY` with your actual Ask Sage API key. --- ### Using Environment Variables for the API Key ### Secure API Key Storage To avoid storing your API key in plaintext inside `opencode.json`, use opencode's environment variable substitution syntax: ```json { "$schema": "https://opencode.ai/config.json", "disabled_providers": ["opencode"], "share": "disabled", "model": "asksage/gpt-5.5", "provider": { "asksage": { "npm": "@ai-sdk/openai", "name": "Ask Sage", "options": { "baseURL": "https://api.asksage.ai/server/openai/v1", "apiKey": "{env:ASKSAGE_API_KEY}" }, "models": { "gpt-5.5": { "name": "GPT-5.5", "limit": { "context": 128000, "output": 16384 } } } } } } ``` Then export the key in your shell profile or session before launching opencode: ```bash export ASKSAGE_API_KEY="your-api-key-here" ``` --- ## Privacy & Non-Essential Traffic ### Disabling Non-Essential Traffic By default, opencode can make outbound connections beyond model inference — for update checks, session sharing, and local network discovery. In regulated environments, add the following fields to `opencode.json` to restrict traffic to Ask Sage only: ```json { "$schema": "https://opencode.ai/config.json", "disabled_providers": ["opencode"], "share": "disabled", "model": "asksage-claude/google-claude-48-opus", "autoupdate": false, "server": { "mdns": false }, "provider": { ... } } ``` #### disabled_providers: ["opencode"] Disables the built-in opencode provider so no requests route outside Ask Sage #### autoupdate: false Disables update checks to opencode.ai and GitHub on startup #### share: "disabled" Prevents conversation uploads via the `/share` command #### server.mdns: false Disables mDNS broadcast for local network service discovery **Note:** These settings do not affect model inference — all AI requests still route through your configured Ask Sage provider. Install, package, schema, and extension surfaces (npm, VS Code Marketplace, opencode.ai) are outside the scope of these flags and should be managed via your organization's network controls. --- ## Launching opencode in VS Code ### Keyboard Shortcuts Once installed, the VS Code extension provides keyboard shortcuts to launch opencode directly inside your editor: #### Open / Focus `Ctrl+Esc` (Windows/Linux) `Cmd+Esc` (Mac) #### New Session `Ctrl+Shift+Esc` (Windows/Linux) `Cmd+Shift+Esc` (Mac) #### Insert File Reference `Alt+Ctrl+K` (Windows/Linux) `Cmd+Option+K` (Mac) **Context Awareness:** The extension automatically passes your current selection or active tab to opencode when you open a new session, so you can immediately ask questions about the code you're looking at. --- ## Activation & Testing ### Verify Your Setup 1. Save Configuration Save your `opencode.json` file to your project root or global config directory 2. Restart the Extension After saving `opencode.json`, reload VS Code (**Developer: Reload Window** from the Command Palette) so the extension picks up the new config 3. Open opencode Press `Ctrl+Esc` (Windows/Linux) or `Cmd+Esc` (Mac) to launch opencode in a split terminal 4. Verify the Model The header should display your configured Ask Sage model (e.g., **Ask Sage / GPT-5**) 5. Send a Test Prompt Type a question and press `Enter` to confirm responses are flowing through Ask Sage #### Quick Test Prompt ```text What model are you running on? ``` If you receive a coherent response, your Ask Sage provider is configured correctly. --- ## Features & Capabilities ### Features & Capabilities #### Agentic Chat Multi-turn AI conversations with full codebase context #### In-place Edits AI applies code changes directly to your files #### Git-Aware Snapshot and restore state across sessions #### Multiple Models Switch between all Ask Sage models in one config #### Governed Inference All configured model inference traffic routes through your Ask Sage instance --- ## Troubleshooting ### Troubleshooting **Issue: Authentication Error / Invalid API Key** opencode returns a 401 or authentication failure **Solutions:** - ✅ Verify your Ask Sage API key is correct (no extra spaces or newlines) - ✅ If using `{env:ASKSAGE_API_KEY}`, confirm the variable is exported in the shell where VS Code was launched - ✅ Confirm the key has not expired — regenerate from your Ask Sage account settings if needed **Issue: Model Not Found** opencode reports the model is unavailable **Solutions:** - ✅ Confirm the model key in `opencode.json` exactly matches the key used by your Ask Sage instance (check via the Ask Sage `/get-models` endpoint) - ✅ Ensure the `"model"` top-level field uses the format `asksage/` - ✅ Verify the model is enabled on your tenant **Issue: Connection / Base URL Error** Requests fail to reach the Ask Sage API **Solutions:** - ✅ Double-check the `baseURL` matches your organization's Ask Sage instance - ✅ Ensure the trailing slash is present: `https://api.asksage.ai/server/` - ✅ Check firewall or proxy settings — opencode must be able to reach the API endpoint - ✅ If on a government network, confirm you are connected to the required VPN **Issue: Extension Doesn't Launch opencode** Keyboard shortcut opens a terminal but opencode doesn't start **Solutions:** - ✅ Confirm `opencode` is in your system `PATH` (run `opencode --version` in a terminal) - ✅ Restart VS Code after installing the CLI so the updated PATH is picked up - ✅ On Windows, ensure the npm global bin directory is in your PATH --- ## Additional Resources ### Documentation & Support #### Documentation - [opencode Official Documentation](https://opencode.ai/docs) - [opencode Configuration Reference](https://opencode.ai/docs/config) - [opencode Provider Configuration](https://opencode.ai/docs/providers) - [opencode VS Code Extension](https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode) - [Ask Sage API Documentation](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) #### Support - **Email:** [support@asksage.ai](mailto:support@asksage.ai) - **Documentation:** [https://docs.asksage.ai](https://docs.asksage.ai) **Need Help?** If you encounter issues not covered here, reach out to [support@asksage.ai](mailto:support@asksage.ai) with: - Your OS and VS Code version - opencode CLI version (`opencode --version`) - Relevant error messages from the opencode terminal output - Your `opencode.json` (with API key redacted) --- # Power Automate Source: /docs/v2/integrations/power-automate/power-automate.html # Ask Sage for Power Automate Bring governed, accredited generative AI into your existing Power Automate flows — no code required. Because Ask Sage exposes a standard REST API, any Power Automate flow can send a prompt and use the response in the next step: an email, a Teams reply, a SharePoint item, an approval, a Dataverse record, and so on. [Browse the examples](#examples) **Instance-Specific Base URL:** The examples here call the public Ask Sage API at `https://api.asksage.ai/server/`. The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you log into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your flows to the instance you authenticate against. ## Two ways to connect There are two ways to call Ask Sage from a flow. Both require a Power Automate plan that includes **premium connectors** (the HTTP action is premium). #### HTTP action Built-in, nothing to manage. Best for testing, prototypes, and one-off flows. #### Custom connector Wraps the API as a first-class action, reusable across flows. Best for production and teams. ## Prerequisites **Ask Sage:** - An Ask Sage account on a plan with **API access**. - An **API key** — Ask Sage UI → **Settings → API Keys**. Treat it like a password. **Power Automate:** - A Microsoft account with access to [make.powerautomate.com](https://make.powerautomate.com). - A plan that includes **premium connectors** — both the HTTP action and the custom connector are premium features. (Older guides that said the HTTP method works on a free license are incorrect.) - To import a solution: a **System Administrator** or **System Customizer** role in the target environment. Per-example extras: **Teams bot** needs a Teams team + channel; **OneDrive** / **SharePoint** analysis need a OneDrive for Business / SharePoint Online library with files to analyze. ## Authentication Send your Ask Sage **API key** directly in a custom header named **`x-access-tokens`** — it is *not* `Authorization: Bearer`, and you don't need to exchange it for a token first: ```http POST https://api.asksage.ai/server/query Content-Type: application/json x-access-tokens: YOUR_ASK_SAGE_API_KEY { "message": "What is Ask Sage?" } ``` A successful response returns the model's answer in the **`message`** field — read it in a flow with `body('')?['message']`. **Keep your key out of the flow:** never paste the key into a shared flow (it shows in run history). Store it in **Azure Key Vault** or a **Power Platform environment variable**, reference it, and turn on **Secure Inputs** on the action. Rotate keys periodically. ## Importing a solution The fastest path is to import a pre-built solution (each example ships one), then connect and run: 1. Power Automate → select your **environment** → **Solutions → Import solution** → pick the `.zip` → **Import**. 2. Create a **connection** with your Ask Sage API key (and, where applicable, a OneDrive / SharePoint / Teams connection). 3. Open the imported flow, bind it to your connection (or set the `x-access-tokens` header in the HTTP flow), replace any placeholders (file IDs, site URL, model), and **Test → Run**. **Heads-up on the model:** the document-analysis solutions ship with `model` set to `google-claude-46-sonnet`. If that model isn't enabled in your tenant, change it to one that is — list available models with `POST /server/get-models`. ## Examples Five working examples, each with a downloadable step-by-step guide (PDF) and an import-ready solution (.zip). ### 1 · HTTP quickstart The simplest call: a manually-triggered flow that takes a question, sends it to Ask Sage with the built-in **HTTP** action, and shows the answer. **Best for:** testing and prototypes. [Guide (PDF)](/assets/downloads/power-automate/guides/http-quickstart-guide.pdf) [Solution (.zip)](/assets/downloads/power-automate/AskSageAPIConnection101_1_0_0_2.zip) ### 2 · Custom connector A reusable *Ask Sage* connector action — your flows just add a step and fill in a message, with no raw HTTP wiring. **Best for:** production and teams. Ships in the same solution as the HTTP quickstart. [Guide (PDF)](/assets/downloads/power-automate/guides/custom-connector-guide.pdf) [Solution (.zip)](/assets/downloads/power-automate/AskSageAPIConnection101_1_0_0_2.zip) ### 3 · Teams bot A Microsoft Teams channel bot powered by Ask Sage, with threaded conversation history and bot-loop prevention. **Best for:** self-service Q&A inside a Teams channel. [Guide (PDF)](/assets/downloads/power-automate/guides/teams-bot-guide.pdf) [Solution (.zip)](/assets/downloads/power-automate/AdvancedTeamsBot_1_0_0_1.zip) ### 4 · OneDrive document analysis Analyze a PDF stored in OneDrive by sending it to the `query_with_file` endpoint, then read back the AI analysis. **Best for:** summarizing or extracting insight from documents. [Guide (PDF)](/assets/downloads/power-automate/guides/onedrive-doc-analysis-guide.pdf) [Solution (.zip)](/assets/downloads/power-automate/OneDriveIntegration_1_0_0_2.zip) ### 5 · SharePoint document analysis The SharePoint counterpart to example 4: analyze a document from a SharePoint library with `query_with_file`, then optionally write the analysis back into SharePoint. **Best for:** document libraries on a team site. [Guide (PDF)](/assets/downloads/power-automate/guides/sharepoint-doc-analysis-guide.pdf) [Solution (.zip)](/assets/downloads/power-automate/SharePointIntegration_1_0_0_1.zip) **Feedback Welcome:** Questions, or an integration you'd like to see? Reach out at [support@asksage.ai](mailto:support@asksage.ai). --- # PyCharm Source: /docs/v2/integrations/pycharm.html # Ask Sage Plugin for PyCharm Bring Ask Sage's governed AI models directly into PyCharm — chat, editor context actions, and knowledge-base training, with support for any JetBrains IDE The **AskSage plugin** is an open-source IntelliJ Platform plugin, published by BigBear.ai LLC, that integrates the [Ask Sage](https://asksage.ai) API directly into PyCharm. It works in any JetBrains IDE built on the IntelliJ Platform (IntelliJ IDEA, WebStorm, PhpStorm, GoLand, and more) — this page uses PyCharm as the running example since it's the most common entry point for Ask Sage users writing Python. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/), with an API base URL of `https://api.asksage.ai`. The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the **Base URL** in the plugin's settings to the instance you authenticate against. **Not yet on the JetBrains Marketplace:** This plugin is pending legal/trademark sign-off before its first Marketplace submission. Until that's complete, install it from the prebuilt ZIP or by building from source (below) — the steps to install from the Marketplace will be added to this page once it's published. --- ## At a Glance ### What this integration does The AskSage plugin adds a dedicated tool window and editor context actions to PyCharm (and any JetBrains IDE), so you can chat with any Ask Sage-hosted model with optional real-time web search and query datasets in natural language — all without leaving the IDE, and all governed by your organization's Ask Sage instance. #### Chat Tool Window Multi-turn chat, markdown rendering, persona selection #### Editor Context Actions Explain, Refactor, Generate Docs, Ask About File, Send Selection — with keyboard shortcuts #### Real-Time Web Search A per-message Web Search toggle grounds answers in live results, with sources listed under the answer #### File-Attached Queries Attach a file directly to a chat query instead of inlining its text #### Secure by Default API key stored in IntelliJ PasswordSafe; 24-hour token exchange **Perfect for:** Python (and any JetBrains-IDE) developers who want Ask Sage's governed model catalog, real-time web search, and knowledge-base datasets available directly in their editor, without switching to a browser tab. --- ## Requirements ### Before you begin | Component | Version | | --- | --- | | **JetBrains IDE** | 2025.2+ (PyCharm, IntelliJ IDEA, or any IntelliJ Platform IDE) | | **JDK** | 21 (only needed to build from source) | | **Ask Sage Account** | With API key access | --- ## Step 1 — Create an Ask Sage Account & API Key ### Get access If you already have an Ask Sage account and API key, skip to [Step 2](#step-2--get-the-plugin-zip). 1. Register Go to [chat.asksage.ai/register](https://chat.asksage.ai/register) and fill in the required fields. 2. Verify your email Enter the verification code emailed to you. If it doesn't arrive, email [support@asksage.aim](mailto:support@asksage.ai). 3. Generate an API key Sign in at [chat.asksage.ai](https://chat.asksage.ai/), open **Settings → Account**, and generate a key under **Manage your API Keys**. Save it securely — you'll enter it into the plugin in [Step 4](#step-4--configure-credentials). --- ## Step 2 — Get the Plugin ZIP ### Option A — Download the prebuilt ZIP The fastest path until this plugin reaches the JetBrains Marketplace: [AskSage-1.0.6.zip](/assets/downloads/pycharm/AskSage-1.0.6.zip) ### Option B — Build the plugin ZIP from source Clone the repository and build the distributable plugin ZIP with Gradle: Clone and build ```bash git clone https://github.com/jlayman-BBAI/pycharm-asksage-plugin.git cd pycharm-asksage-plugin ./gradlew buildPlugin ``` The built plugin ZIP is written to `build/distributions/`. **Optional — try it in a sandboxed IDE first:** Run `./gradlew runIde` to launch a throwaway IDE instance with the plugin pre-installed, without touching your main PyCharm installation. --- ## Step 3 — Install in PyCharm ### Install from disk 1. Open Plugin settings In PyCharm, go to **Settings/Preferences → Plugins**. 2. Install from disk Click the gear icon (⚙) next to the plugins search bar and choose **Install Plugin from Disk…**, then select the ZIP from Step 2. 3. Restart the IDE PyCharm will prompt you to restart to activate the plugin. --- ## Step 4 — Configure Credentials ### Connect the plugin to Ask Sage Go to **Settings → Tools → AskSage** and enter: | Field | Description | | --- | --- | | **Email** | The email address associated with your Ask Sage account. | | **API Key** | Your Ask Sage API key, exchanged for a 24-hour access token. Stored in IntelliJ PasswordSafe, not in plain-text config. | | **Base URL** | Default: `https://api.asksage.ai`. Change only if your organization uses a different Ask Sage instance (see the callout at the top of this page). | **Test before you trust it:** Click **Test Connection** to validate your credentials, then **Test Model Discovery** to confirm the model list loads. A successful test saves your credentials and live-refreshes the plugin's dropdowns — no IDE restart needed. --- ## Using the Plugin ### Chat tab Open the **AskSage** tool window (right sidebar). Pick a model and optionally a persona under **Tools**, then start chatting. Check **Web Search** to ground a response in real-time web results — when it fires, a **Sources** list with the actual URLs used appears under the answer, so you can see it happened rather than just trusting the model's word for it. Responses render as markdown, with clickable follow-up-question suggestions. Use the attach-file button next to the input to send an actual file alongside your question (via `/server/query_with_file`) instead of pasting its contents as text — useful for PDFs, spreadsheets, and other non-code files. ### Editor context actions Right-click in the editor for: | Action | Shortcut | | --- | --- | | Explain Code | `Ctrl+Shift+Alt+E` | | Refactor | `Ctrl+Shift+Alt+R` | | Generate Docs | `Ctrl+Shift+Alt+D` | | Ask About File | `Ctrl+Shift+Alt+A` | | Send Selection to AskSage | Unassigned — add one in **Settings > Keymap** if desired | | Add to Knowledge Base | `Ctrl+Shift+Alt+K` | **Ask About File** uploads the actual file via `/server/query_with_file`, so it works for any file Ask Sage can process, not just what fits cleanly as inlined text. ### Usage tab Shows monthly token usage for the current Ask Sage application. --- ## API Coverage | Endpoint | Used for | | --- | --- | | `/user/get-token-with-api-key` | Authentication | | `/server/get-models` | Model selector | | `/server/get-personas` | Persona selector | | `/server/get-datasets` | Dataset lists (knowledge base and tabular) | | `/server/get-dataset-info` | Resolving a dataset name to its numeric ID for tabular queries | | `/server/query` | Chat (standard + single-chunk simulated streaming) | | `/server/query_with_file` | Chat attach-file button; Ask About File action | | `/server/query-tabular` | Auto-detected when the Chat dataset selector picks a tabular dataset | | `/server/follow-up-questions` | Clickable follow-up suggestions | | `/server/count-monthly-tokens` | Usage tab | --- ## Known Limitations - **No native streaming** — Ask Sage's `/server/query` returns complete responses. The plugin simulates streaming by displaying the full response as a single chunk once it arrives, the same approach used by the [Ask Sage Dify plugin](dify#known-limitations). - **Not yet on the JetBrains Marketplace** — see the callout near the top of this page. Download the ZIP or build from source in the meantime. --- ## Troubleshooting | Symptom | Fix | | --- | --- | | "Authentication expired" notification | Your 24-hour access token lapsed. Re-open **Settings > Tools > AskSage** and click **Test Connection** to re-authenticate. | | Model dropdown is empty | Click **Test Model Discovery** in settings. If it still fails, confirm the **Base URL** matches your organization's Ask Sage instance. | | Tabular query fails with a dataset error | The selected dataset must have been created via **Add to Knowledge Base** on a `.csv`/`.tsv`/`.xlsx`/`.xlsb` file (tabular ingestion), not a plain-text knowledge-base entry. | | Web Search is checked but no Sources appear | Not every model supports tool-based web search on Ask Sage's platform. Try a different model, or ask a question whose answer clearly requires current information to confirm. | --- ## Resources & Support - **Source & releases:** [github.com/jlayman-BBAI/pycharm-asksage-plugin](https://github.com/jlayman-BBAI/pycharm-asksage-plugin) - **Changelog:** [CHANGELOG.md](https://github.com/jlayman-BBAI/pycharm-asksage-plugin/blob/main/CHANGELOG.md) - **Ask Sage support:** [support@asksage.ai](mailto:support@asksage.ai) **Feedback Welcome:** Have a request or feedback on this integration? Reach out at [support@asksage.ai](mailto:support@asksage.ai). --- # SharePoint Chat Widget Source: /docs/v2/integrations/sharepoint-widget/sharepoint-widget.html # Ask Sage Chat Widget for SharePoint Bring AI-powered question-and-answer capabilities directly into your organization's SharePoint pages. ![Ask Sage Chat Widget full view showing a conversation](/assets/images/integrations-v2-sharepoint-widget-full-view.png) AI-powered chat embedded directly in SharePoint — connected to your organization's knowledge bases via the Ask Sage platform. --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ### Overview The **Ask Sage Chat Widget** brings AI-powered question-and-answer capabilities directly into your organization's SharePoint pages. Employees can simply click a chat button on any SharePoint page and ask questions in plain English. The widget connects to your organization's **Ask Sage account** via API and retrieves answers from datasets (knowledge bases) that have been uploaded to the Ask Sage platform. It cites its sources and presents responses in a clean, familiar chat interface. **Important:** The widget does **not** read or index SharePoint content directly. All knowledge bases are managed within your Ask Sage account. Documents must be uploaded to Ask Sage as datasets before the widget can answer questions about them. SharePoint serves as the user-facing environment where the chat experience is delivered. --- ## How It Works ### How It Works A floating chat button appears in the bottom-right corner of any SharePoint page where the widget is installed. Users click to open the chat, select a knowledge base, and type a question. The AI searches the selected datasets, returns a clear answer with numbered citations, and supports follow-up questions with conversation memory (up to 10 messages). ![Ask Sage chatbot widget showing Connected status](/assets/images/integrations-v2-sharepoint-admin-chatbot-connected.png) **Powered by RAG (Retrieval-Augmented Generation):** The AI **only answers from datasets in your Ask Sage account** -- it does not search the open internet or make up information. SharePoint is the delivery surface; Ask Sage is the data and AI engine. The two are connected through the Ask Sage API. --- ## Common Use Cases ### Use Cases #### HR Self-Service "How many vacation days do I get after 3 years?" "Does our dental plan cover orthodontics?" #### IT Help Desk Deflection "How do I reset my password?" "What are the steps to connect to the VPN?" #### Onboarding & Training "Who do I contact for building access?" "How do I submit an expense report?" #### Compliance & Regulatory "What are our data retention requirements?" "What are the reporting requirements for security incidents?" #### Department Knowledge Bases Finance, Legal, Engineering, Sales -- each department gets tailored datasets on their own SharePoint site. --- ## What You Need to Get Started ### Prerequisites #### Ask Sage Account An active Ask Sage subscription with an API key. [Learn more at asksage.ai](https://asksage.ai) #### SharePoint Online A modern SharePoint Online environment (Microsoft 365). On-premises is not supported. #### App Catalog Access Permission to upload apps to your tenant's SharePoint App Catalog. #### Knowledge Base Content Documents uploaded to your Ask Sage account as datasets. **No Special Infrastructure:** No special hardware, servers, or databases are required. The widget runs inside SharePoint as the user interface, while all data storage and AI processing are handled by the Ask Sage cloud platform via API. --- ## Get Started ### Admin Setup Guide Deploy, configure, and manage the widget on your SharePoint sites. Covers installation, API setup, dataset configuration, and access control. [Read the guide](admin-setup-guide.html) ### User Guide Learn how to open the chat, select datasets, ask questions, and interpret responses with source citations. [Read the guide](user-guide.html) ### Download WebPart Download the latest Ask Sage Chat widget package for SharePoint. Upload this file to your App Catalog to install. [Download .sppkg](/downloads/asksage-chatbot.sppkg) --- ## Support & Resources ### Resources - [Ask Sage Platform](https://asksage.ai) - [Ask Sage Support](https://asksage.ai/support) - [SharePoint Framework Documentation](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) **Have Questions?** Reach out to us at [support@asksage.ai](mailto:support@asksage.ai) --- # Admin Setup Guide Source: /docs/v2/integrations/sharepoint-widget/admin-setup-guide.html # SharePoint Admin Setup Guide Deploy and configure the Ask Sage Chat Widget on your SharePoint sites ### About This Guide This guide walks SharePoint site administrators and owners through the complete process of deploying and configuring the Ask Sage chatbot widget on their SharePoint sites. **Estimated Time:** 15-20 minutes to complete the full setup. **Agency Security Note:** Depending on your organization's security requirements, you may need to request and obtain approval on a **per-page basis** before deploying the widget to a specific SharePoint page. Check with your agency's security team or SharePoint governance office to confirm any approval workflows that apply before proceeding. --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## Prerequisites ### Before You Begin Ensure you have the following before starting: #### SharePoint Admin Access Permissions to access the SharePoint App Catalog #### The Package File `asksage-chatbot.sppkg` file provided to you #### Ask Sage API Key Obtained from your Ask Sage representative #### Network Access Your SharePoint environment can reach `https://api.asksage.ai` --- ## Step 1: Upload to App Catalog ### Upload to App Catalog #### 1.1 Navigate to App Catalog 1. Go to your SharePoint Admin Center 2. Navigate to **More features** > **Apps** > **Open** 3. Click **App Catalog**. If you don't have one, you'll need to [create an App Catalog](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) first. ![SharePoint Admin Center showing the path to App Catalog](/assets/images/integrations-v2-sharepoint-admin-app-catalog.png) #### 1.2 Upload the Package 1. In the App Catalog, go to **Apps for SharePoint** 2. Click **Upload** or drag and drop the `asksage-chatbot.sppkg` file 3. A dialog will appear asking you to deploy the solution ![Apps for SharePoint library with Upload button](/assets/images/integrations-v2-sharepoint-admin-upload-sppkg.png) #### 1.3 Deploy the Solution 1. Check the box: **"Make this solution available to all sites in the organization"**. This allows the web part to be used on any site. You can control access later using the built-in whitelist feature. 2. Click **Deploy** and wait for deployment to complete (usually 1-2 minutes) **Done:** The Ask Sage chatbot is now available to add to any SharePoint page in your organization. --- ## Step 2: Add Web Part to a Page ### Add the Web Part 1. Go to the SharePoint site and page where you want to add the chatbot 2. Click **Edit** in the top-right corner of the page 3. Click **See all web parts** and search for **"Ask Sage"** or **"AskSageChat"** 4. Click on the **Ask Sage Chat** web part to add it to the page. It will appear as a blue icon in the bottom right corner with "Initialize Chat" displayed. ![SharePoint page in edit mode showing the web part search](/assets/images/integrations-v2-sharepoint-admin-add-webpart.png) **Tip:** You can place the web part anywhere on the page. It will always render as a floating button in the bottom right corner regardless of placement. --- ## Step 3: Configure API Connection ### API Connection #### 3.1 Open the Property Pane Click the **Properties** button on the right side after selecting the web part. The property pane will open on the right side of the screen. ![Web part with property pane open](/assets/images/integrations-v2-sharepoint-admin-property-pane.png) #### 3.2 Configure API Settings | Setting | What to Enter | Required | | --- | --- | --- | | **API Key** | Your organization's Ask Sage API key | Yes | | **API Base URL** | Default: `https://api.asksage.ai/server`. Change only if using a proxy. | No | 1. Enter your **API Key** in the provided field 2. (Optional) Change the **API Base URL** if using a custom proxy or different endpoint 3. Click the **"Refresh Datasets"** button to load your available knowledge bases ![API Configuration section with API Key field and Refresh Datasets button](/assets/images/integrations-v2-sharepoint-admin-api-config.png) **Troubleshooting:** If the datasets don't load, verify your API key is correct and your network allows connections to `api.asksage.ai`. --- ## Step 4: Configure Dataset Access ### Dataset Configuration Datasets are the knowledge bases that the chatbot can search. You can control which datasets users can access and which are selected by default. #### 4.1 Filter Available Datasets (Optional) **Purpose:** Limit which datasets users can choose from in the chatbot interface. 1. In the **"Dataset Configuration"** section, find **"STEP 1: Filter which datasets users can select"** 2. Choose one of the following: - **Leave empty** -- Users can see and select from all datasets - **Select specific datasets** -- Use the dropdown to choose which datasets should be available 3. Use **"Select All"** to add all datasets or **"Clear All"** to remove all selections ![Dataset Configuration section showing filtered datasets selection](/assets/images/integrations-v2-sharepoint-admin-dataset-filtering.png) **Example:** A Sales team site might only show sales-related datasets. A public-facing page might restrict access to general FAQ datasets only. #### 4.2 Set Default Datasets **Purpose:** Pre-select which datasets are active when users first open the chatbot. 1. Find **"STEP 2: Set default pre-selected datasets"** in the same section 2. Use the dropdown to select dataset(s). You can only select from datasets in the filtered list (if you configured one). 3. Use **"Copy from Filtered Datasets"** to quickly set all filtered datasets as defaults, or **"Clear All"** to remove defaults. ![Default datasets configuration](/assets/images/integrations-v2-sharepoint-admin-default-datasets.png) **Example Configuration:** - **Filtered Datasets:** `sales-docs, product-catalog, pricing-guide` - **Default Datasets:** `sales-docs, product-catalog` - **Result:** Users see three datasets but two are already selected when they open the chat --- ## Step 5: Configure Access Control (Optional) ### Site Collection Whitelist The Site Collection Whitelist restricts which SharePoint sites can use this web part instance. #### Understanding the Whitelist - **Empty whitelist** = Web part works on all sites (default) - **Populated whitelist** = Web part only works on matching sites - Supports wildcard patterns (`*`) for flexible matching #### Add Site Restrictions Expand the **"Access Control"** section in the property pane and enter URL patterns in the **"Site Collection Whitelist"** field (one per line): ```text # Allow all sites on your tenant *.contoso.com # Allow only HR and IT sites https://contoso.sharepoint.com/sites/HR/* https://contoso.sharepoint.com/sites/IT/* # Allow a specific page https://contoso.sharepoint.com/sites/Intranet/SitePages/Home.aspx ``` ![Access Control section with Site Collection Whitelist](/assets/images/integrations-v2-sharepoint-admin-access-control.png) #### Pattern Matching Rules | Pattern | Matches | | --- | --- | | `https://contoso.sharepoint.com/sites/HR` | Only this exact site | | `*.sharepoint.com/sites/IT` | Any subdomain with this path | | `https://contoso.sharepoint.com/*` | Any path under this domain | | `*/sites/Sales/*` | Any domain with `/sites/Sales/` in the path | Lines starting with `#` are treated as comments. **Important:** This is a client-side governance feature, not a security boundary. For true access control, use SharePoint page permissions or implement server-side validation. See [Security Considerations](#security-considerations). --- ## Step 6: Publish and Test ### Publish and Test #### 6.1 Save and Publish 1. Review all your settings in the property pane, then close it (settings are saved automatically) 2. Click **"Republish"** or **"Publish"** in the top-right corner to make the chatbot live #### 6.2 Test the Chatbot View the published page and verify the following: - The chatbot widget appears and shows **"Connected"** status (no "Connecting..." message) - Click to open the chat interface - Verify the correct datasets are pre-selected - Send a test question and receive a response - Try selecting different datasets (if multiple are available) - Verify the chat history persists during your session ![Ask Sage Chat Widget full view showing a conversation](/assets/images/integrations-v2-sharepoint-widget-full-view.png) --- ## Troubleshooting ### Common Issues **"Connecting..." Badge Won't Disappear** **Solutions:** - Verify the API key in the property pane is correct - Check that your firewall/proxy allows access to `api.asksage.ai` - Open browser Developer Tools (F12) and check the Console tab for errors - Contact Ask Sage support if the issue persists **Datasets Not Loading** **Solutions:** - Ensure you've entered the API key in the property pane - Click "Refresh Datasets" after entering the key - Verify your Ask Sage account has datasets configured - Check browser console for error messages **"Access to this web part is restricted on this site"** **Solutions:** - Edit the page and open the web part property pane - Go to "Access Control" section - Add the current site URL to the whitelist, or clear the whitelist entirely - Republish the page **"Rate limit exceeded" Message** **Solutions:** - Wait 60 seconds for the rate limit to reset - The message will automatically clear when the rate limit resets - This is a normal protection mechanism to prevent abuse **Chatbot Displays But Doesn't Respond** **Solutions:** - Ensure at least one dataset is selected in the chat interface - Try selecting different datasets - Verify the datasets contain content in your Ask Sage admin panel - Check browser console for error messages --- ## Security Considerations ### Security Considerations #### API Key Protection **Current Limitation:** The API key is stored in the SharePoint property pane and is visible to anyone who can edit the page. **Mitigation Steps:** - Restrict page editing permissions to trusted administrators only - Monitor API usage regularly through your Ask Sage dashboard - Rotate API keys periodically (quarterly recommended) - Set up usage alerts in your Ask Sage account #### Rate Limiting The current client-side rate limiting (30 requests per minute) can be bypassed by technical users. For stronger enforcement, implement server-side rate limiting in your API proxy. #### Site Collection Whitelist This is a **client-side governance feature**, NOT a security control. For true access control: - Use SharePoint page permissions - Implement Azure AD group-based authorization - Add server-side validation in your API proxy - Use tenant-level IP restrictions #### Data Security - **User Messages:** Stored temporarily in browser memory only. Cleared when user closes the chat. Maximum 10 messages retained. - **API Communication:** All communication uses HTTPS encryption. - **HTML Content:** All AI responses are sanitized to prevent XSS attacks using DOMPurify. --- ## Monitoring Recommendations ### Ongoing Monitoring #### Weekly Review API usage in Ask Sage dashboard #### Monthly Audit which sites have the web part deployed #### Quarterly Rotate API keys and review dataset access configurations **Set Up Alerts For:** - Unusual spikes in API usage - Multiple failed authentication attempts - Rate limit violations --- ## Setup Checklist ### Completion Checklist - Package deployed to App Catalog - Solution made available to all sites - Web part added to target page - API key configured and datasets refreshed - Dataset filtering configured (if needed) - Default datasets set (if desired) - Site collection whitelist configured (if needed) - Page published and tested - Test question sent and response received - API usage monitoring set up - API key documented in secure location - Quarterly API key rotation scheduled --- ## Additional Resources ### Resources - [SharePoint Chat Widget Overview](sharepoint-widget.html) - [User Guide](user-guide.html) -- Share with end users - [Ask Sage Platform](https://asksage.ai) - [Ask Sage Support](https://asksage.ai/support) - [SharePoint Framework Documentation](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) **Have Questions?** Contact your Ask Sage representative or reach out at [support@asksage.ai](mailto:support@asksage.ai) --- # User Guide Source: /docs/v2/integrations/sharepoint-widget/user-guide.html # Ask Sage Chat Widget - User Guide Learn how to use the AI-powered chatbot to find answers quickly on your SharePoint site. ### Welcome to Ask Sage Ask Sage is an AI-powered chatbot that helps you find information from your organization's knowledge bases quickly and easily. Instead of searching through multiple documents and folders, you can simply ask questions in natural language and get accurate, cited answers. **How It Works:** Ask Sage answers questions using **datasets from the Ask Sage platform**, not directly from the SharePoint page where the chatbot appears. SharePoint is where you access the chatbot; the Ask Sage platform is where your organization's knowledge bases are stored and managed. --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## What Ask Sage Can and Cannot Do ### Capabilities #### Answer Questions Based on datasets from the Ask Sage platform #### Provide Citations Every answer includes references to source documents #### Follow-Up Questions Handle contextual follow-ups in the same conversation #### Multi-Dataset Search Search across multiple knowledge bases at once **Ask Sage Cannot:** - Search the current SharePoint page, site, or document libraries - Answer questions outside of configured Ask Sage datasets - Make up information or guess -- it only uses your organization's documents - Remember conversations after you close the chat - Execute actions or make changes to documents --- ## Getting Started ### Opening the Chat 1. Find the Chat Button Look for the **Ask Sage button** in the **bottom-right corner** of your SharePoint page. 2. Click to Open Click the button to expand the chat interface. You'll see available datasets at the top, the chat area in the middle, and the message input box at the bottom. 3. Check Connection Status If there is no "Connecting..." message, you're ready to go. If you see "Connecting..." wait a moment -- if it persists, contact your administrator. ![Chat interface opened and ready to use](/assets/images/integrations-v2-sharepoint-user-open-chat.png) --- ## Using the Chatbot ### Asking Questions 1. Select Your Datasets Make sure the relevant knowledge bases are selected (checked/highlighted) at the top of the chat. Some may already be pre-selected by your administrator. 2. Type Your Question Enter your question in the message box at the bottom. Use natural language -- ask questions the way you naturally speak. 3. Send and Wait Click **Send** or press **Enter**. Your answer will appear above your question. ![Ask Sage Chat Widget showing a conversation](/assets/images/integrations-v2-sharepoint-widget-full-view.png) #### Example Questions #### Good Questions "What is our company's remote work policy?" "How do I submit a travel expense report?" #### Less Effective Questions "Tell me everything" (too broad), "What's the weather?" (not in knowledge bases) ### Follow-Up Questions You can ask follow-up questions based on previous answers in the same conversation. The chatbot remembers the context of your conversation (up to 10 messages). **Example Conversation:** 1. **You:** "What is our vacation policy?" 2. **Ask Sage:** *Provides the vacation policy details with citations...* 3. **You:** "How many days do new employees get?" 4. **Ask Sage:** *Answers based on the same context...* 5. **You:** "How do I request time off?" 6. **Ask Sage:** *Provides the request process...* ![Ask Sage Chat Widget showing a conversation](/assets/images/integrations-v2-sharepoint-widget-full-view.png) --- ## Working with Datasets ### Understanding Datasets Datasets are the knowledge bases that Ask Sage searches to answer your questions. Think of them as different collections of documents: #### HR Policies Employee handbook, benefits, procedures #### IT Documentation Technical guides, software manuals #### Sales Materials Product information, pricing #### Company Procedures SOPs, workflows, guidelines #### Selecting Datasets Available datasets are displayed at the **top of the chat interface** as selectable buttons or checkboxes. - **Checked/Highlighted datasets** = Will be searched - **Unchecked/Grayed datasets** = Will NOT be searched - Click a dataset to **toggle** its selection on/off - You can select **multiple datasets** at once to search across different knowledge bases simultaneously ![Dataset selector showing available knowledge bases](/assets/images/integrations-v2-sharepoint-user-datasets-options.png) **Tip:** Only select datasets related to your question for more focused results. For example, if asking about HR benefits, select only HR-related datasets. **Note:** If you try to ask a question without selecting any datasets, the chatbot will remind you to select at least one first. You can change datasets at any time -- new questions will search the newly selected datasets. ![Chatbot prompt reminding user to select a dataset before asking a question](/assets/images/integrations-v2-sharepoint-no-source-data.png) --- ## Understanding Responses ### Response Structure Each AI response includes several parts: 1. Main Answer A direct response to your question in clear, formatted text. 2. Source Citations Numbered references like **[1]**, **[2]**, **[3]** indicating which source document the information came from. 3. References Section An expandable **"N References"** button at the bottom of the response. Click to see the full source text for each citation, including document names and relevant excerpts. ![AI response with answer and source citations](/assets/images/integrations-v2-sharepoint-user-references.png) **Example Citation:** *"The vacation policy allows 15 days per year **[1]**. New employees accrue vacation time starting from their first day **[2]**."* This means "15 days per year" comes from source [1] and "accrue vacation time" comes from source [2]. Click "Show more" on a reference to see the full excerpt. #### "No Source Data" Responses If Ask Sage cannot find relevant information in the selected datasets, you'll see a message saying no source data was found. This commonly happens when you ask a question that is unrelated to any of the connected knowledge bases. When this happens: - Try rephrasing your question - Select different or additional datasets - Check if you're asking about information outside the available knowledge bases - Contact your administrator if you believe the information should be available ![Chatbot response when no source data is found](/assets/images/integrations-v2-sharepoint-no-source-data.png) --- ## Tips for Best Results ### Tips for Best Results #### Be Specific Instead of "Tell me about policies," try "What is the policy for remote work equipment?" #### Select Relevant Datasets Only select datasets related to your question for more focused results. #### One Question at a Time Break complex questions into simpler parts for better answers. #### Use Follow-Ups Build on previous answers for better context and deeper details. #### Verify With Sources Always check the source references to verify information and see the full context. #### Rephrase If Needed If you don't get a good answer, try different keywords or break it into simpler parts. --- ## Frequently Asked Questions ### FAQ Is my conversation private? **Yes.** Your conversation history is stored temporarily in your browser's memory while the chat is open. When you close the chat, the conversation is completely cleared. Conversations are not saved to SharePoint or any permanent storage. How many messages can I send? You can send up to **30 messages per minute**. If you exceed this limit, you'll see a rate limit message. Wait 60 seconds and you can continue. How long does the conversation history last? The chatbot remembers up to **10 messages** (5 back-and-forth exchanges) in your current conversation. Older messages beyond this limit won't be considered for follow-up questions. Why can't I see certain datasets? Your administrator controls which datasets are available to you based on your role and the SharePoint site you're on. Can Ask Sage make changes to documents? **No.** Ask Sage is **read-only**. It can search and retrieve information but cannot modify, create, or delete documents. What if the answer is wrong? Check the source references to see the original content and verify the information. If you believe an answer is incorrect, report the issue to your administrator. Accuracy depends on the quality and currency of the source documents. Can I use Ask Sage on mobile devices? **Yes.** Ask Sage works on mobile devices through your SharePoint site's mobile interface. Does Ask Sage support other languages? Ask Sage can respond in multiple languages if your source documents are in those languages. The interface itself is in English. --- ## Troubleshooting ### Common Issues **Chat Won't Open** **Solutions:** - Refresh the page (F5 or Ctrl+R) - Clear your browser cache - Try a different browser (Edge, Chrome, Firefox) - Contact your IT administrator **"Connecting..." Message Won't Go Away** **Solutions:** - Wait 30 seconds -- it may still be connecting - Refresh the page - Check your internet connection - Contact your administrator if the issue persists **No Datasets Available** **Solutions:** - Refresh the page - Contact your administrator to verify dataset access - Check if other users have the same issue **"No Source Data" for Every Question** **Solutions:** - Try selecting different datasets - Ask questions you know should have answers in your knowledge base - Contact your administrator if the datasets should contain relevant information **"Rate Limit Exceeded" Message** **Solutions:** - Wait 60 seconds for the rate limit to reset - The message will automatically clear **Responses Are Cut Off or Incomplete** **Solutions:** - Ask the question again - Refresh the page and retry - Report to your administrator if it happens consistently **Still Need Help?** 1. **Refresh the page** -- solves many temporary issues 2. **Check with colleagues** -- see if others experience the same problem 3. **Contact your administrator** -- provide details about what you were trying to do, what happened, and any error messages --- ## Privacy & Security ### Privacy & Security #### HTTPS Encryption All communication is encrypted in transit #### No Permanent Storage Conversations are not saved after you close the chat #### Private Sessions Your questions are not shared with other users #### Access Controlled Only authorized SharePoint users can use the chatbot --- # VS Code Copilot (BYOK) Source: /docs/v2/integrations/vscode-copilot-byok.html # VS Code GitHub Copilot Integration Use Ask Sage models directly in VS Code Copilot Chat via Bring Your Own Key (BYOK) Bring Ask Sage's models into Visual Studio Code through GitHub Copilot Chat's Bring Your Own Key (BYOK) language-model support. This integration uses VS Code's **Custom Endpoint** provider and works with the same Ask Sage API key you already use for other integrations. --- --- **Instance-Specific Base URL:** The endpoints and configuration shown reflect the instance at [chat.asksage.ai](https://chat.asksage.ai/). The `api.` prefix and path suffix stay the same across deployments — only the instance segment in the middle changes based on which Ask Sage instance you are logging into. Always use the instance approved by your organization and applicable regulatory requirements, and match the base URL in your configuration to the instance you authenticate against. --- ## At a Glance ### What this integration does VS Code 1.122 added a **Custom Endpoint** BYOK provider that speaks OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. This page shows how to point that provider at Ask Sage so GPT, Claude, and Gemini-style models become first-class options in the Copilot Chat model picker — with the same security boundary, logging, and policy controls you already get from Ask Sage. API key only — no Entra ID, no extra sign-in Works in Commercial, Gov, and managed networks Chat Completions, Responses, and Anthropic Messages in one provider group Per-model reasoning effort, tool calling, and vision toggles --- ## Prerequisites ### Before you begin - **Visual Studio Code 1.122 or later** — the Custom Endpoint provider was added in this release - **GitHub Copilot Chat** enabled in VS Code - An **Ask Sage API key** (from your account settings) - Network access to the Ask Sage endpoint from your workstation - For DoD or other managed networks, your organization-provided root certificate may need to be configured for VS Code or your OS certificate store ### Copilot Business / Enterprise users If you are on a Copilot Business or Enterprise plan, your organization administrator must first enable the **Bring Your Own Language Model Key in VS Code** policy in GitHub Copilot policy settings. Without that policy, the Custom Endpoint flow will not appear. --- ## Step 1 — Add Ask Sage as a Custom Endpoint Provider 1. Open the **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`) 2. Run **Chat: Manage Language Models** 3. Select **Add Models...** 4. Choose **Custom Endpoint** 5. Enter `Ask Sage` as the group name 6. Paste your Ask Sage API key — VS Code stores it in OS secret storage, not in the JSON file 7. Choose the default API type for the group (you can mix shapes later): **Chat Completions** — for `/openai/v1/chat/completions` models 8. **Responses** — for `/openai/v1/responses` models 9. **Messages** — for `/anthropic/v1/messages` models ![Select Custom Endpoint from Add Models](../../assets/images/vscode-copilot/vscode-add-models-custom-endpoint.png) ![Create the Ask Sage group](../../assets/images/vscode-copilot/vscode-create-asksage-group.png) ![Paste the Ask Sage API key](../../assets/images/vscode-copilot/vscode-asksage-api-key.png) ![Choose the Ask Sage API type](../../assets/images/vscode-copilot/vscode-asksage-api-type.png) After you choose the API type, VS Code opens `chatLanguageModels.json` with a starter Ask Sage provider group and an empty model entry. The next step is filling that in. **Do not paste a raw API key into `chatLanguageModels.json`.** Secret fields are resolved through VS Code secret storage. After you enter the key in the UI, VS Code writes an `${input:chat.lm.secret...}` reference into the file. That reference is what should live in the JSON. --- ## Step 2 — Configure Models VS Code stores BYOK model groups as a top-level JSON array. Each entry is one provider group. Fill in the `models` array with one or more Ask Sage models. Pick the configuration shape that matches the endpoint you are calling. **Looking for the complete model list?** The four *Option* snippets below are minimal starters. See [Available Models by Environment](#available-models-by-environment) and [Drop-in Configurations by Environment](#drop-in-configurations-by-environment) further down for full per-tenant catalogs (Commercial / Gov / DoD) and copy-paste configurations. ![VS Code starter chatLanguageModels.json](../../assets/images/vscode-copilot/vscode-chat-language-models-json-starter.png) ### Option A — OpenAI Chat Completions chatLanguageModels.json — Chat Completions ```json [ { "name": "Ask Sage", "vendor": "customendpoint", "apiKey": "${input:chat.lm.secret.example}", "apiType": "chat-completions", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 (Ask Sage)", "url": "https://api.asksage.ai/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 } ] } ] ``` ### Option B — OpenAI Responses (with reasoning) chatLanguageModels.json — Responses ```json [ { "name": "Ask Sage", "vendor": "customendpoint", "apiKey": "${input:chat.lm.secret.example}", "apiType": "responses", "models": [ { "id": "gpt-5.5", "name": "GPT 5.5 (Ask Sage)", "url": "https://api.asksage.ai/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": true, "thinking": true, "supportsReasoningEffort": ["low", "medium", "high"], "reasoningEffortFormat": "responses", "maxInputTokens": 272000, "maxOutputTokens": 128000 } ], "settings": { "gpt-5.5": { "reasoningEffort": "high" } } } ] ``` ### Option C — Anthropic Messages chatLanguageModels.json — Anthropic Messages ```json [ { "name": "Ask Sage", "vendor": "customendpoint", "apiKey": "${input:chat.lm.secret.example}", "apiType": "messages", "models": [ { "id": "claude-opus-4-7", "name": "Claude Opus 4.7 (Ask Sage)", "url": "https://api.asksage.ai/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "thinking": true, "supportsReasoningEffort": ["low", "medium", "high", "xhigh", "max"], "maxInputTokens": 200000, "maxOutputTokens": 64000 } ], "settings": { "claude-opus-4-7": { "reasoningEffort": "medium" } } } ] ``` ### Option D — Combined (Chat Completions + Responses + Messages) You can place all three API shapes in a single Ask Sage provider group. Set `apiType` on each individual model to override the group default. chatLanguageModels.json — Combined (live-tested) ```json [ { "name": "Ask Sage", "vendor": "customendpoint", "apiKey": "${input:chat.lm.secret.example}", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 (Ask Sage)", "url": "https://api.asksage.ai/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 }, { "id": "gpt-5.5", "name": "GPT 5.5 (Ask Sage)", "url": "https://api.asksage.ai/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": true, "thinking": true, "supportsReasoningEffort": ["low", "medium", "high"], "reasoningEffortFormat": "responses", "maxInputTokens": 272000, "maxOutputTokens": 128000 }, { "id": "claude-opus-4-7", "name": "Claude Opus 4.7 (Ask Sage)", "url": "https://api.asksage.ai/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "thinking": true, "supportsReasoningEffort": ["low", "medium", "high", "xhigh", "max"], "maxInputTokens": 200000, "maxOutputTokens": 64000 } ], "settings": { "gpt-5.5": { "reasoningEffort": "high" }, "claude-opus-4-7": { "reasoningEffort": "medium" } } } ] ``` --- ## Step 3 — Verify the Configuration 1. Save `chatLanguageModels.json` 2. Open the Command Palette and run **Chat: Manage Language Models** again 3. Your configured Ask Sage models should appear in the Language Models pane 4. Open Copilot Chat, click the model picker, and pick one of the Ask Sage models 5. Send a simple prompt such as `hello world!`. A response confirms VS Code is reaching Ask Sage through the configured BYOK endpoint. ![Configured Ask Sage models in Manage Language Models](../../assets/images/vscode-copilot/vscode-asksage-configured-models.png) ![Ask Sage model responding in Copilot Chat](../../assets/images/vscode-copilot/vscode-asksage-chat-response.png) --- ## Available Models by Environment The Ask Sage models exposed through the OpenAI- and Anthropic-compatible endpoints depend on which Ask Sage environment your API key is provisioned in. The catalog below mirrors the canonical per-environment allow-lists from the Ask Sage Client (`src/config.js`) enriched with model metadata from the [Ask Sage CoreUI](https://ask-sage.ghe.com/Ask-Sage/CoreUI) shared model catalog (`src/Data/models.ts`). Image, video, and embedding models are intentionally omitted — the VS Code Copilot Chat picker only consumes chat / reasoning / Anthropic Messages shapes. You can always confirm what your specific account is entitled to by calling: ```bash curl https://api.asksage.ai/server/openai/v1/models \ -H "Authorization: Bearer $ASKSAGE_API_KEY" curl https://api.asksage.ai/server/anthropic/v1/models \ -H "Authorization: Bearer $ASKSAGE_API_KEY" ``` **Heads up:** the live `/openai/v1/models` and `/anthropic/v1/models` endpoints currently return a static catalog that does not yet enforce per-environment filtering or expose the full set of supported IDs (including internal aliases). Treat the tables below as the source of truth for now; a Server-side fix is tracked in the Ask Sage Server repo to bring those endpoints in line. ### Commercial (SaaS) Tenants Default profile for accounts on `api.asksage.ai` not tagged as Gov or DoD. ### Commercial — 47 chat / reasoning models | API Shape | Public ID | Display Name | Provider / Hosting | Input Ctx | Output Ctx | Tools | Vision | Reasoning | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Anthropic Messages | `claude-haiku-4-5` alias: `claude-haiku-4-5-com` | Anthropic Claude Haiku 4.5 | Direct | 200,000 | 32,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4` alias: `google-claude-4-opus` | Google Anthropic Claude 4.1 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-5` alias: `google-claude-45-opus` | Google Anthropic Claude 4.5 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-6` alias: `google-claude-46-opus` | Google Anthropic Claude 4.6 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-7` alias: `claude-opus-4-7-com` | Anthropic Claude Opus 4.7 | Direct | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-8` alias: `google-claude-48-opus` | Google Anthropic Claude 4.8 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4` alias: `google-claude-4-sonnet` | Google Anthropic Claude 4 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-5-vertex` alias: `google-claude-45-sonnet` | Google Anthropic Claude 4.5 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-6` alias: `claude-sonnet-4-6-com` | Anthropic Claude Sonnet 4.6 | Direct | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-120b-gov` | OpenAI GPT-OSS 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-20b-gov` | OpenAI GPT-OSS 20B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-nemotron-12b-vl-gov` | NVIDIA Nemotron Nano 12B v2 VL | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `aws-bedrock-nemotron-30b-gov` | NVIDIA Nemotron Nano 3 30B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-9b-gov` | NVIDIA Nemotron Nano 9B v2 | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-super-3-120b-gov` | NVIDIA Nemotron Super 3 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `deepseek-v3.2-com` | DeepSeek V3.2 | Direct | 128,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `deepseek-v4-flash` | DeepSeek V4 Flash | Direct | 128,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `google-gemini-2.5-flash` | Google Gemini 2.5 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-2.5-pro` | Google Gemini 2.5 Pro | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-20-flash` | Google Gemini 2.0 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3-flash-com` | Google Gemini 3 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.1-flash-lite-com` | Google Gemini 3.1 Flash Lite | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.1-pro-com` | Google Gemini 3.1 Pro | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.5-flash-com` | Google Gemini 3.5 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1` | Azure OpenAI GPT-4.1 | Azure OpenAI (Commercial) | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-mini` | Azure OpenAI GPT-4.1-mini | Azure OpenAI (Commercial) | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-nano` | Azure OpenAI GPT-4.1-nano | Azure OpenAI (Commercial) | 128,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-1-fast-non-reasoning` | X.AI Grok 4.1 Fast | Direct | 256,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-1-fast-reasoning` | X.AI Grok 4.1 Fast (Reasoning) | Direct | 256,000 | 16,384 | ✅ | ✅ | ✅ | | Chat Completions | `grok-4-20-non-reasoning` | X.AI Grok 4.20 (Fast) | Direct | 256,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-20-reasoning` | X.AI Grok 4.20 (Reasoning) | Direct | 256,000 | 16,384 | ✅ | ✅ | ✅ | | Chat Completions | `groq-70b` | Groq-70B | Groq Cloud | 128,000 | 8,192 | — | — | — | | Chat Completions | `groq-llama33` | Groq LLAMA 3.3 | Groq Cloud | 128,000 | 8,192 | — | — | — | | Chat Completions | `groq-llama4-scout` | Groq LLAMA 4-Scout | Groq Cloud | 128,000 | 8,192 | — | — | — | | Chat Completions | `kimi-2.6-com` | Moonshot Kimi K2.6 | Direct | 200,000 | 16,384 | ✅ | — | — | | Chat Completions | `mistral-large-3` | Mistral Large 3 | Azure OpenAI (Commercial) | 128,000 | 32,000 | ✅ | — | — | | Responses | `gpt-5` | Azure OpenAI GPT-5 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5-mini` | Azure OpenAI GPT-5-mini | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5-nano` | Azure OpenAI GPT-5-nano | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.1` | Azure OpenAI GPT-5.1 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.2` | Azure OpenAI GPT-5.2 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.4` | Azure OpenAI GPT-5.4 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.4-nano` | Azure OpenAI GPT-5.4-nano | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o1` | Azure OpenAI GPT-o1 | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o3` | Azure OpenAI GPT-o3 | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o3-mini` | Azure OpenAI GPT-o3-mini | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o4-mini` | Azure OpenAI GPT-o4-mini | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | ### Gov Tenants (FedRAMP / IL2–IL4) Profile when the tenant has `force_gov_models=true`. Superset of the commercial-equivalent models with `-gov` variants for partner models that are not yet generally available in commercial. ### Gov — 44 chat / reasoning models | API Shape | Public ID | Display Name | Provider / Hosting | Input Ctx | Output Ctx | Tools | Vision | Reasoning | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Anthropic Messages | `claude-haiku-4-5` alias: `google-claude-45-haiku` | Google Anthropic Claude 4.5 Haiku | Google Vertex AI | 200,000 | 32,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4` alias: `google-claude-4-opus` | Google Anthropic Claude 4.1 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-5` alias: `google-claude-45-opus` | Google Anthropic Claude 4.5 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-6` alias: `google-claude-46-opus` | Google Anthropic Claude 4.6 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-7` alias: `google-claude-47-opus` | Google Anthropic Claude 4.7 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-8` alias: `google-claude-48-opus` | Google Anthropic Claude 4.8 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4` alias: `google-claude-4-sonnet` | Google Anthropic Claude 4 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-5` alias: `aws-bedrock-claude-45-sonnet-gov` | AWS Gov Bedrock Claude 4.5 Sonnet | AWS Bedrock GovCloud | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-5-vertex` alias: `google-claude-45-sonnet` | Google Anthropic Claude 4.5 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-6` alias: `google-claude-46-sonnet` | Google Anthropic Claude 4.6 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-120b-gov` | OpenAI GPT-OSS 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-20b-gov` | OpenAI GPT-OSS 20B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-nemotron-12b-vl-gov` | NVIDIA Nemotron Nano 12B v2 VL | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `aws-bedrock-nemotron-30b-gov` | NVIDIA Nemotron Nano 3 30B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-9b-gov` | NVIDIA Nemotron Nano 9B v2 | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-super-3-120b-gov` | NVIDIA Nemotron Super 3 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nova-lite-gov` | AWS Gov Bedrock Nova Lite | AWS Bedrock GovCloud | 128,000 | 5,000 | ✅ | ✅ | — | | Chat Completions | `aws-bedrock-nova-micro-gov` | AWS Gov Bedrock Nova Micro | AWS Bedrock GovCloud | 128,000 | 5,000 | ✅ | — | — | | Chat Completions | `aws-bedrock-nova-pro-gov` | AWS Gov Bedrock Nova Pro | AWS Bedrock GovCloud | 300,000 | 5,000 | ✅ | ✅ | — | | Chat Completions | `google-gemini-2.5-flash` | Google Gemini 2.5 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-2.5-pro` | Google Gemini 2.5 Pro | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-20-flash` | Google Gemini 2.0 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.1-flash-lite-gov` | Google Gemini 3.1 Flash Lite Gov | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.5-flash-gov` | Google Gemini 3.5 Flash Gov | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1` | Azure OpenAI GPT-4.1 | Azure OpenAI (Commercial) | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-mini` | Azure OpenAI GPT-4.1-mini | Azure OpenAI (Commercial) | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-nano` | Azure OpenAI GPT-4.1-nano | Azure OpenAI (Commercial) | 128,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-1-fast-non-reasoning` | X.AI Grok 4.1 Fast | Direct | 256,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-1-fast-reasoning` | X.AI Grok 4.1 Fast (Reasoning) | Direct | 256,000 | 16,384 | ✅ | ✅ | ✅ | | Chat Completions | `grok-4-20-non-reasoning` | X.AI Grok 4.20 (Fast) | Direct | 256,000 | 16,384 | ✅ | ✅ | — | | Chat Completions | `grok-4-20-reasoning` | X.AI Grok 4.20 (Reasoning) | Direct | 256,000 | 16,384 | ✅ | ✅ | ✅ | | Chat Completions | `llma3` | LLAMA 3 | AWS Bedrock GovCloud | 128,000 | 8,192 | ✅ | — | — | | Chat Completions | `llma3-8b` | Meta Llama 3 8B | AWS Bedrock GovCloud | 128,000 | 8,192 | ✅ | — | — | | Chat Completions | `mistral-large-3` | Mistral Large 3 | Azure OpenAI (Commercial) | 128,000 | 32,000 | ✅ | — | — | | Responses | `gpt-5` | Azure OpenAI GPT-5 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5-mini` | Azure OpenAI GPT-5-mini | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5-nano` | Azure OpenAI GPT-5-nano | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.1` | Azure OpenAI GPT-5.1 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.1-gov` | Azure Gov OpenAI GPT-5.1 | Azure OpenAI Gov | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.2` | Azure OpenAI GPT-5.2 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.4` | Azure OpenAI GPT-5.4 | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-5.4-nano` | Azure OpenAI GPT-5.4-nano | Azure OpenAI (Commercial) | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o1` | Azure OpenAI GPT-o1 | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o3-mini` | Azure OpenAI GPT-o3-mini | Azure OpenAI (Commercial) | 200,000 | 100,000 | ✅ | ✅ | ✅ | ### DoD Tenants (IL5 / IL6) **DoD operators:** only the models in this table are approved in the DoD-locked profile (`force_dod_models=true`). Calling any other model ID will return `403 model_not_allowed`. This list mirrors the canonical allow-list in Ask Sage Client `src/config.js` and is the safe set to publish in a DoD environment. ### DoD-Approved — 26 chat / reasoning models | API Shape | Public ID | Display Name | Provider / Hosting | Input Ctx | Output Ctx | Tools | Vision | Reasoning | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Anthropic Messages | `claude-haiku-4-5` alias: `google-claude-45-haiku` | Google Anthropic Claude 4.5 Haiku | Google Vertex AI | 200,000 | 32,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-5` alias: `google-claude-45-opus` | Google Anthropic Claude 4.5 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-6` alias: `google-claude-46-opus` | Google Anthropic Claude 4.6 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-7` alias: `google-claude-47-opus` | Google Anthropic Claude 4.7 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-opus-4-8` alias: `google-claude-48-opus` | Google Anthropic Claude 4.8 Opus | Google Vertex AI | 200,000 | 64,000 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-5-vertex` alias: `google-claude-45-sonnet` | Google Anthropic Claude 4.5 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Anthropic Messages | `claude-sonnet-4-6` alias: `google-claude-46-sonnet` | Google Anthropic Claude 4.6 Sonnet | Google Vertex AI | 200,000 | 32,768 | ✅ | ✅ | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-120b-gov` | OpenAI GPT-OSS 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-gpt-oss-20b-gov` | OpenAI GPT-OSS 20B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | ✅ | | Chat Completions | `aws-bedrock-nemotron-12b-vl-gov` | NVIDIA Nemotron Nano 12B v2 VL | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `aws-bedrock-nemotron-30b-gov` | NVIDIA Nemotron Nano 3 30B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-9b-gov` | NVIDIA Nemotron Nano 9B v2 | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nemotron-super-3-120b-gov` | NVIDIA Nemotron Super 3 120B | AWS Bedrock GovCloud | 131,000 | 8,192 | ✅ | — | — | | Chat Completions | `aws-bedrock-nova-lite-gov` | AWS Gov Bedrock Nova Lite | AWS Bedrock GovCloud | 128,000 | 5,000 | ✅ | ✅ | — | | Chat Completions | `aws-bedrock-nova-micro-gov` | AWS Gov Bedrock Nova Micro | AWS Bedrock GovCloud | 128,000 | 5,000 | ✅ | — | — | | Chat Completions | `aws-bedrock-nova-pro-gov` | AWS Gov Bedrock Nova Pro | AWS Bedrock GovCloud | 300,000 | 5,000 | ✅ | ✅ | — | | Chat Completions | `google-gemini-2.5-flash` | Google Gemini 2.5 Flash | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-2.5-pro` | Google Gemini 2.5 Pro | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.1-flash-lite-gov` | Google Gemini 3.1 Flash Lite Gov | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `google-gemini-3.5-flash-gov` | Google Gemini 3.5 Flash Gov | Google Vertex AI | 1,000,000 | 8,192 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-gov` | Azure Gov OpenAI GPT-4.1 | Azure OpenAI Gov | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `gpt-4.1-mini-gov` | Azure Gov OpenAI GPT-4.1-mini | Azure OpenAI Gov | 128,000 | 32,768 | ✅ | ✅ | — | | Chat Completions | `llma3` | LLAMA 3 | AWS Bedrock GovCloud | 128,000 | 8,192 | ✅ | — | — | | Chat Completions | `llma3-8b` | Meta Llama 3 8B | AWS Bedrock GovCloud | 128,000 | 8,192 | ✅ | — | — | | Responses | `gpt-5.1-gov` | Azure Gov OpenAI GPT-5.1 | Azure OpenAI Gov | 272,000 | 128,000 | ✅ | ✅ | ✅ | | Responses | `gpt-o3-mini-gov` | Azure Gov OpenAI GPT-o3-mini | Azure OpenAI Gov | 200,000 | 100,000 | ✅ | ✅ | ✅ | --- ## Drop-in Configurations by Environment Paste one of the snippets below into `chatLanguageModels.json` based on the Ask Sage tenant your API key is associated with. The snippets are curated starter sets — expand from the catalog above as needed. ### Commercial Drop-in chatLanguageModels.json — Commercial ```json [ { "name": "Ask Sage (Commercial)", "vendor": "customendpoint", "apiKey": "${input:asksage-api-key}", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 - Ask Sage", "url": "https://api.asksage.ai/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 }, { "id": "gpt-5.5", "name": "GPT 5.5 (Reasoning) - Ask Sage", "url": "https://api.asksage.ai/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": true, "maxInputTokens": 272000, "maxOutputTokens": 128000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high" ], "reasoningEffortFormat": "responses" }, { "id": "claude-opus-4-8", "name": "Claude Opus 4.8 - Ask Sage", "url": "https://api.asksage.ai/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 64000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] }, { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 - Ask Sage", "url": "https://api.asksage.ai/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 32768, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] } ], "settings": { "gpt-5.5": { "reasoningEffort": "high" }, "claude-opus-4-8": { "reasoningEffort": "medium" }, "claude-sonnet-4-6": { "reasoningEffort": "medium" } } } ] ``` ### Gov Drop-in **Replace the base URL:** The `url` values below use a `YOUR-GOV-TENANT` placeholder. Before pasting this configuration into VS Code, swap that placeholder for the base URL your government Ask Sage tenant issued when you generated your API key. Do not point a government workload at the commercial endpoint. chatLanguageModels.json — Gov (FedRAMP / IL2–IL4) ```json [ { "name": "Ask Sage (Gov)", "vendor": "customendpoint", "apiKey": "${input:asksage-api-key}", "models": [ { "id": "gpt-4.1", "name": "GPT 4.1 - Ask Sage", "url": "https://api.YOUR-GOV-TENANT/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 }, { "id": "gpt-5.1-gov", "name": "GPT 5.1 (Gov Reasoning) - Ask Sage", "url": "https://api.YOUR-GOV-TENANT/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": true, "maxInputTokens": 272000, "maxOutputTokens": 128000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high" ], "reasoningEffortFormat": "responses" }, { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 - Ask Sage", "url": "https://api.YOUR-GOV-TENANT/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 32768, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] }, { "id": "claude-opus-4-7", "name": "Claude Opus 4.7 - Ask Sage", "url": "https://api.YOUR-GOV-TENANT/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 64000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] } ], "settings": { "gpt-5.1-gov": { "reasoningEffort": "high" }, "claude-sonnet-4-6": { "reasoningEffort": "medium" }, "claude-opus-4-7": { "reasoningEffort": "medium" } } } ] ``` ### DoD Drop-in **Replace the base URL:** The `url` values below use a `YOUR-DOD-TENANT` placeholder. Before pasting this configuration into VS Code, swap that placeholder for the base URL your DoD Ask Sage tenant issued when you generated your API key. Do not point a DoD workload at the commercial endpoint. **DoD-only:** The Claude IDs in this snippet (`claude-sonnet-4-6`, `claude-opus-4-7`) resolve to Google Vertex AI deployed inside an IL5 Assured Workloads folder — not commercial Vertex. `claude-sonnet-4-5` (which routes to AWS Bedrock GovCloud) is *not* in the `force_dod_models` allow-list, so it is omitted here. chatLanguageModels.json — DoD (IL5 / IL6) ```json [ { "name": "Ask Sage (DoD)", "vendor": "customendpoint", "apiKey": "${input:asksage-api-key}", "models": [ { "id": "gpt-4.1-gov", "name": "GPT 4.1 (Gov) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 }, { "id": "gpt-4.1-mini-gov", "name": "GPT 4.1 Mini (Gov) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/openai/v1/chat/completions", "apiType": "chat-completions", "toolCalling": true, "vision": true, "maxInputTokens": 128000, "maxOutputTokens": 32768 }, { "id": "gpt-5.1-gov", "name": "GPT 5.1 (Gov) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": true, "maxInputTokens": 272000, "maxOutputTokens": 128000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high" ], "reasoningEffortFormat": "responses" }, { "id": "gpt-o3-mini-gov", "name": "GPT o3 Mini (Gov) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/openai/v1/responses", "apiType": "responses", "toolCalling": true, "vision": false, "maxInputTokens": 200000, "maxOutputTokens": 100000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high" ], "reasoningEffortFormat": "responses" }, { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 (IL5 Vertex) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 32768, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] }, { "id": "claude-opus-4-7", "name": "Claude Opus 4.7 (IL5 Vertex) - Ask Sage", "url": "https://api.YOUR-DOD-TENANT/server/anthropic/v1/messages", "apiType": "messages", "toolCalling": true, "vision": true, "maxInputTokens": 200000, "maxOutputTokens": 64000, "thinking": true, "supportsReasoningEffort": [ "low", "medium", "high", "xhigh", "max" ] } ], "settings": { "gpt-5.1-gov": { "reasoningEffort": "high" }, "gpt-o3-mini-gov": { "reasoningEffort": "high" }, "claude-sonnet-4-6": { "reasoningEffort": "medium" }, "claude-opus-4-7": { "reasoningEffort": "medium" } } } ] ``` --- ## Why Custom Endpoint (and not OpenAI / Anthropic vendor) **Always use `vendor: "customendpoint"` for Ask Sage.** The Ask Sage compatibility endpoints are OpenAI- and Anthropic-style, but they are hosted by Ask Sage — not by OpenAI or Anthropic directly. - **Do not** use `vendor: "openai"` — VS Code's built-in OpenAI provider targets the official OpenAI API. - **Do not** use `vendor: "anthropic"` — VS Code's built-in Anthropic provider targets Anthropic's official API. For OpenAI-shaped endpoints VS Code sends the key as `Authorization: Bearer ...`. For Anthropic-shaped endpoints with `apiType: "messages"`, VS Code sends it as `x-api-key` — both are supported by Ask Sage. --- ## Optional — Use Ask Sage for Copilot Utility Tasks VS Code uses lightweight background models for utility tasks like title generation, commit messages, and intent detection. You can route those through Ask Sage too: VS Code settings.json ```json { "chat.utilityModel": "customendpoint/gpt-4.1", "chat.utilitySmallModel": "customendpoint/gpt-4.1-mini" } ``` The format is `${vendor}/${modelId}`. For Ask Sage models, the vendor is always `customendpoint`, so values look like `customendpoint/gpt-4.1-mini`. A fast, inexpensive model is recommended for `chat.utilitySmallModel` since it is invoked frequently. --- ## Configuration Reference The fields most relevant to Ask Sage models: | Property | Type | Notes | | --- | --- | --- | | `id` | string | The model identifier Ask Sage expects (e.g., `gpt-4.1`, `claude-opus-4-7`) | | `name` | string | Display name in the Copilot Chat model picker | | `url` | string | Full Ask Sage endpoint URL for this model's API shape | | `apiType` | string | `chat-completions`, `responses`, or `messages` — overrides the group default | | `toolCalling` | boolean | Set to `true` only if the model supports tool calling | | `vision` | boolean | Set to `true` only if the model supports image inputs | | `maxInputTokens` | integer | Context window for input tokens | | `maxOutputTokens` | integer | Maximum response length | | `thinking` | boolean | Set to `true` for reasoning-capable models (Responses or Anthropic with thinking) | | `supportsReasoningEffort` | array | Effort levels: typically `["low", "medium", "high"]`; Anthropic also supports `"xhigh"` and `"max"` | | `reasoningEffortFormat` | string | For `/responses` endpoints set to `"responses"` (sends nested `reasoning.effort`); defaults follow URL otherwise | | `streaming` | boolean | Optional, defaults to `true`; Ask Sage supports streaming via SSE | | `requestHeaders` | object | Optional extra headers; reserved/forwarding headers are ignored | For the complete reference (including provider-level fields and advanced options) see the [VS Code language models documentation](https://code.visualstudio.com/docs/copilot/customization/language-models#_model-configuration-reference). --- ## DoD and Managed Network Connectivity If your users connect through a DoD, DoW, or other managed network, certificate and proxy configuration may be required before VS Code can reach the Ask Sage endpoint. For the model allow-list approved in DoD environments, see the [DoD Tenants section](#dod-tenants-il5--il6) above. - If your environment requires a custom root certificate, configure it according to your organization policy — typically through the OS certificate store or the `http.proxyStrictSSL` / `http.systemCertificates` VS Code settings - Test reachability from a terminal, substituting the base URL issued to your government / DoD tenant: `curl -I https://api.YOUR-TENANT/server/openai/v1/models -H "Authorization: Bearer $KEY"` - If using a proxy, ensure VS Code's `http.proxy` setting is configured and matches your shell environment --- ## Troubleshooting ### Manage Language Models shows nothing Make sure `chatLanguageModels.json` is a **top-level array**, not an object with a `providers` property. **Correct:** ```json [ { "name": "Ask Sage", "vendor": "customendpoint" } ] ``` **Incorrect:** ```json { "providers": [] } ``` ### API key not found or authentication fails - Re-enter the key through **Chat: Manage Language Models** so VS Code stores it as a secret - Confirm the JSON contains an `${input:chat.lm.secret...}` reference for `apiKey` (not the raw key) - Verify the Ask Sage API key is still active in your account settings - Verify the endpoint URL matches the configured `apiType` — an Anthropic URL with `apiType: "chat-completions"` will fail authentication ### Model does not appear in the picker - Confirm the provider group `vendor` is `customendpoint` - Confirm each model has `id`, `name`, `url`, `toolCalling`, `vision`, `maxInputTokens`, and `maxOutputTokens` - For agent / tool-use scenarios, the model must have `toolCalling: true` — otherwise it is hidden from the picker - Reload the VS Code window after editing `chatLanguageModels.json` directly ### Reasoning effort does not appear in the picker - Set `thinking: true` on the model - Add `supportsReasoningEffort` with the effort values your endpoint accepts - For `/responses` endpoints, set `reasoningEffortFormat: "responses"` --- ## Privacy and Data Usage When configured through BYOK, chat requests for the selected model are sent to the Ask Sage endpoint you configured. The same Ask Sage tenant data-handling and logging policies apply as for any other Ask Sage API consumer. Refer to the [Ask Sage Privacy & Security FAQ](../faq/faq.html) for the specifics of retention, logging, and training behavior in your environment. --- ## Additional Resources [VS Code language model docs](https://code.visualstudio.com/docs/copilot/customization/language-models) [Ask Sage OpenAI compatibility](/docs/v2/api-documentation/OpenAI-Compatibility-Guide.html) [Ask Sage Anthropic compatibility](/docs/v2/api-documentation/Anthropic-Compatibility-Guide.html) --- # Model Context Protocol Source: /docs/v2/mcp-documentation/mcp-documentation.html # Model Context Protocol Unlock seamless AI integrations and extend your model's capabilities with structured, governed tool use. ---------------- ## Overview ### What MCP is, and why it matters on Ask Sage The **Model Context Protocol (MCP)** is a framework that lets Ask Sage models call external tools and services as part of a conversation. Instead of asking a model to *describe* what it would do, MCP gives the model a structured way to *actually do it* — read your calendar, file an issue, fetch a document — within a defined set of permissions and approvals. MCP is particularly useful when you want to extend the AI beyond what it already knows: adding new tools, editing existing ones, or interacting with external services. Each tool call is scoped, surfaced for approval, and logged, so the integration stays predictable instead of magical. ![MCP Tools Approval Interface](/assets/images/mcp-v2-tool-approval.png) Tool Call Approval Interface — every action is shown to you before it runs. ![Calendar Management Use Case](/assets/images/mcp-v2-calendar-example.png) Calendar Management Example — natural language in, structured tool call out. **Hosted on Ask Sage:** Microsoft 365 and GitHub integrations are built and run by Ask Sage. Each tool call is shown for approval before it runs and logged afterward — no setup beyond connecting your account. ---------------- ## Hosted MCPs ### Pre-built integrations, run by Ask Sage Hosted MCPs are enterprise-grade, pre-built integrations developed and maintained by Ask Sage. They cover common business platforms and are ready to enable for your tenant — no infrastructure on your side. **Available integrations:** [Microsoft 365](/docs/v2/mcp-documentation/mcp-m365.html), [GitHub](/docs/v2/mcp-documentation/mcp-github.html), [Box](/docs/v2/mcp-documentation/mcp-box.html), with additional integrations planned. **Requirements & access:** - **Account type:** Enterprise account with a minimum of 10M monthly tokens, or a dedicated Ask Sage tenant/instance. - **Activation:** Contact your administrator to request hosted MCP access through Ask Sage support at [support@asksage.ai](mailto:support@asksage.ai). ---------------- ## Where to Next ### Pick an integration to set up #### [Microsoft 365 MCP](/docs/v2/mcp-documentation/mcp-m365.html) Calendar, mail, OneDrive, and SharePoint from chat. #### [GitHub MCP](/docs/v2/mcp-documentation/mcp-github.html) Repositories, issues, and pull requests from chat. #### [Box MCP](/docs/v2/mcp-documentation/mcp-box.html) Files, folders, and shared links from chat. --- # Microsoft 365 MCP Source: /docs/v2/mcp-documentation/mcp-m365.html # Microsoft 365 MCP Connect and manage your Microsoft 365 data — calendar, mail, OneDrive, SharePoint — directly from Ask Sage. ---------------- ## Prerequisites ### What you need before you start - **Account type:** Enterprise account with a minimum of 10M monthly tokens, or a dedicated Ask Sage tenant/instance. - **Activation:** Contact your administrator to request hosted MCP access through Ask Sage support at [support@asksage.ai](mailto:support@asksage.ai). After we work with you or your administrator to enable the integration, you'll receive confirmation and users can follow the setup steps below. ---------------- ## Connecting Your Microsoft Account ### Link Microsoft 365 to your Ask Sage profile 1. **Navigate to Account Settings:** Click your user profile icon (typically in the bottom-left corner) and select **Account**. 2. **Initiate Microsoft Sign-In:** Scroll to the bottom of the Account settings panel to find the sign-in options. Click **Sign in with Microsoft**. ![Sign in with Microsoft button in Ask Sage account settings](/assets/images/mcp-v2-m365-signin-button.png) Sign in with Microsoft button 1. **Authenticate:** A Microsoft login window will open. Sign in with your Microsoft 365 credentials. 2. **Verify the connection:** The Ask Sage page refreshes automatically. Return to **Account** settings — the button will now read **Logout from Microsoft**, confirming you're connected. ---------------- ## Activating and Using the Microsoft 365 Tool ### Enable the tool in chat and pick a compatible model Once your account is connected, enable the tool in the chat interface to start using it. 1. **Access the Tools menu:** In the main chat window, click the settings icon (often shown as sliders) above the text input field to open the configuration panel. 2. **Enable the Microsoft 365 tool:** Under the *Tools* section, find **Microsoft 365** and click its toggle. The switch turns blue when active. ![Enabling the Microsoft 365 tool in Ask Sage](/assets/images/mcp-v2-m365-tool-toggle.png) Tool Configuration 1. **Select a compatible model:** Use a model that supports tool integration (MCP). Filter for these by selecting the *MCP* tag on the model selection screen. Models like **GPT-Auto** are designed to use these tools automatically. ![MCP-enabled model selection in Ask Sage](/assets/images/mcp-v2-model-picker-mcp-filter.png) Model Selection with MCP Filter ---------------- ## Making a Request ### Ask in natural language, approve the tool call You can now ask questions or give commands related to your Microsoft 365 data. 1. **Make a request:** Type a natural-language command into the chat. For example: "What is on my calendar for tomorrow?" 2. "Find the sales report from last quarter in my OneDrive." 3. "Send an email to 'jane.doe@example.com' with the subject 'Project Update'." 4. **Approve tool usage:** For security, Ask Sage prompts you before accessing your data. A **Tool Call Approval** card appears showing the specific action. Review and click **Approve**. ![Tool Call Approval card for a Microsoft 365 action](/assets/images/mcp-v2-m365-tool-approval.png) Tool Call Approval Once approved, Ask Sage executes the task and returns the requested information or confirms the action completed. ![Tool Call Execution card for a Microsoft 365 action](/assets/images/mcp-v2-m365-tool-execution.png) Tool Execution Result ---------------- ## Available Functions ### What the Microsoft 365 tool can do The Microsoft 365 tool exposes **14 functions** across Calendar, Email, and Files (OneDrive / SharePoint), grouped below. Optional arguments are shown in *italics*. #### Calendar | Function | Arguments | Description | | --- | --- | --- | | `list_calendar_events` | `start_date`, `end_date` *(`max_results`, `target_user_email`)* | List events from a calendar within a date range. | | `create_calendar_event` | `subject`, `start_time`, `end_time` *(`attendees`, `location`, `body`, `is_online_meeting`)* | Create an event with attendees, location, and optional online meeting. | | `update_calendar_event` | `event_id` *(`subject`, `start_time`, `end_time`, `attendees`, `location`, `body`)* | Update an existing event's properties. | | `delete_calendar_event` | `event_id` *(`send_cancellation`)* | Delete an event; sends cancellation first for meetings with attendees. | | `cancel_calendar_event` | `event_id` *(`comment`)* | Cancel a meeting and send cancellation notices to attendees. | | `search_calendar_events` | `query` *(`date_from`, `date_to`, `max_results`)* | Search events via the Microsoft Search API (KQL). | | `get_calendar_availability` | `start_time`, `end_time` *(`interval_minutes`)* | Get free/busy schedule with a configurable interval. | #### Email | Function | Arguments | Description | | --- | --- | --- | | `search_emails` | `query` *(`from_address`, `date_from`, `date_to`, `has_attachments`, `importance`, `max_results`)* | Search emails via the Microsoft Search API (KQL). | | `list_emails` | *(`folder`, `max_results`, `unread_only`)* | List emails from a mail folder, with an unread-only filter. | | `send_email` | `to_recipients`, `subject`, `body` *(`cc_recipients`, `bcc_recipients`, `importance`)* | Send an email with TO/CC/BCC recipients and importance level. | #### Files (OneDrive / SharePoint) | Function | Arguments | Description | | --- | --- | --- | | `list_items` | *(`path`, `site_id`, `drive_id`, `folder_id`, `max_results`)* | List files and folders by path, folder ID, or root across OneDrive and SharePoint. | | `search_files` | `query` *(`file_types`, `location`, `max_results`)* | Search files across OneDrive and SharePoint (KQL). | | `ms_get_file_content` | `item_id` *(`site_id`, `drive_id`, `encoding`)* | Download file content (text decoded, binary returned as base64). | | `get_item_metadata` | `item_id` *(`site_id`, `drive_id`)* | Get detailed metadata including sharing info and SharePoint IDs. | ---------------- ## Support ### Stuck on connection or tool use? **Need help?** If you encounter any issues connecting your account or using the tool, reach out to us at [support@asksage.ai](mailto:support@asksage.ai). --- # GitHub MCP Source: /docs/v2/mcp-documentation/mcp-github.html # GitHub MCP Manage repositories, issues, and pull requests directly from Ask Sage. ---------------- ## Prerequisites ### What you need before you start - **Account type:** Enterprise account with a minimum of 10M monthly tokens, or a dedicated Ask Sage tenant/instance. - **Activation:** Contact your administrator to request hosted MCP access through Ask Sage support at [support@asksage.ai](mailto:support@asksage.ai). After we work with you or your administrator to enable the integration, you'll receive confirmation and users can follow the setup steps below. ---------------- ## Connecting Your GitHub Account ### Link GitHub to your Ask Sage profile The first step is to connect your GitHub account to your Ask Sage profile. 1. **Navigate to Account Settings:** Click your user profile icon (typically in the bottom-left corner) and select **Account**. 2. **Initiate GitHub Sign-In:** Scroll to the bottom of the Account settings panel to find the sign-in options. Click **Sign in with GitHub**. 3. **Authorize:** A GitHub authorization window opens. Sign in with your GitHub credentials and click the green **Authorize Ask Sage GitHub MCP** button to grant the necessary permissions. 4. **Verify the connection:** After authorizing, the Ask Sage page refreshes automatically. Return to **Account** settings — the button will now read **Logout from GitHub**, confirming you're connected. ---------------- ## Activating and Using the GitHub Tool ### Enable the tool in chat and pick a compatible model Once your account is connected, enable the tool in the chat interface to start using it. 1. **Access the Tools menu:** In the main chat window, click the settings icon (often shown as sliders) above the text input field to open the configuration panel. 2. **Enable the GitHub tool:** Under the *Tools* section, find **GitHub** and click its toggle. The switch turns blue when active. ![Enabling the GitHub tool in Ask Sage](/assets/images/mcp-v2-github-tool-toggle.png) Tool Configuration 1. **Select a compatible model:** Use a model that supports tool integration (MCP). Filter for these by selecting the *MCP* tag on the model selection screen. Models like **GPT-Auto** are designed to use these tools automatically. ![MCP-enabled model selection in Ask Sage](/assets/images/mcp-v2-model-picker-mcp-filter.png) Model Selection with MCP Filter ---------------- ## Making a Request ### Ask in natural language, approve the tool call You can now ask questions or give commands related to your GitHub data. 1. **Make a request:** Type a natural-language command into the chat. For example: "List my repositories." 2. "Create an issue in the 'frontend' repo titled 'Fix login button bug'." 3. "Summarize the latest pull request in the 'backend' project." 4. **Approve tool usage:** For security, Ask Sage prompts you before accessing your data. A **Tool Call Approval** card appears showing the specific action. Review and click **Approve**. ![Tool Call Approval card for a GitHub action](/assets/images/mcp-v2-github-tool-approval.png) Tool Call Approval Once approved, Ask Sage executes the task and returns the requested information or confirms the action completed. ![Tool Call Execution card for a GitHub action](/assets/images/mcp-v2-github-tool-execution.png) Tool Execution Result ---------------- ## Available Functions ### What the GitHub tool can do The GitHub tool exposes **19 functions** across repositories & files, branches, issues, and pull requests, grouped below. Optional arguments are shown in *italics*. #### Repositories & files | Function | Arguments | Description | | --- | --- | --- | | `get_user_info` | *none* | Retrieve the authenticated user's GitHub profile. | | `list_repositories` | *(`repo_type`, `sort`)* | List repositories accessible to the user (all/owner/member, sortable). | | `get_repository` | `repo` | Get detailed repository metadata. | | `list_repository_contents` | `repo` *(`ref`, `recursive`)* | Retrieve the file tree (recursive by default) using the Git Tree API. | | `get_file_content` | `repo`, `path` *(`ref`)* | Download file content with automatic base64 decoding and binary detection. | | `create_file` | `repo`, `path`, `message`, `content` *(`branch`)* | Create a new file with content and a commit message. | | `update_file` | `repo`, `path`, `message`, `content`, `branch` *(`sha`)* | Update an existing file (auto-retrieves SHA if not provided). | | `delete_file` | `repo`, `path`, `message` *(`sha`, `branch`)* | Delete a file with a commit message. | #### Branches | Function | Arguments | Description | | --- | --- | --- | | `create_branch` | `repo`, `branch_name` *(`source_branch`, `source_sha`)* | Create a branch from another branch or a specific commit SHA. | | `list_branches` | `repo` | List all branches with protection status. | #### Issues | Function | Arguments | Description | | --- | --- | --- | | `create_issue` | `repo`, `title` *(`body`, `labels`, `assignees`)* | Create an issue with title, body, labels, and assignees. | | `list_issues` | `repo` *(`state`, `per_page`)* | List issues filtered by state (excludes pull requests). | #### Pull requests | Function | Arguments | Description | | --- | --- | --- | | `create_pull_request` | `repo`, `title`, `head`, `base` *(`body`, `draft`, `maintainer_can_modify`)* | Create a PR with head/base branches, draft support, and cross-repo format. | | `list_pull_requests` | `repo` *(`state`, `head`, `base`, `sort`, `direction`, `per_page`)* | List PRs with filtering, sorting, and pagination. | | `get_pull_request` | `repo`, `pull_number` *(`include_comments`, `include_commits`)* | Get detailed PR info with optional comments, reviews, and commit history. | | `update_pull_request` | `repo`, `pull_number` *(`title`, `body`, `state`, `base`)* | Modify a PR's title, body, state, or base branch. | | `merge_pull_request` | `repo`, `pull_number` *(`commit_title`, `commit_message`, `merge_method`, `sha`)* | Merge a PR via merge/squash/rebase with optional SHA verification. | | `get_pull_request_diff` | `repo`, `pull_number` *(`format`)* | Retrieve a PR's diff or patch content. | | `list_pull_request_files` | `repo`, `pull_number` *(`per_page`)* | List all changed files in a PR with diff patches. | ---------------- ## Support ### Stuck on connection or tool use? **Need help?** If you encounter any issues connecting your account or using the tool, reach out to us at [support@asksage.ai](mailto:support@asksage.ai). --- # Box MCP Source: /docs/v2/mcp-documentation/mcp-box.html # Box MCP Browse, search, and read your Box.com files, folders, and metadata directly from Ask Sage. ---------------- ## Prerequisites ### What you need before you start - **Account type:** Enterprise account with a minimum of 10M monthly tokens, or a dedicated Ask Sage tenant/instance. - **Tenant setup:** The Box integration must be **enabled and set up by your tenant superadmin** before it becomes available to users. Hosted MCP must also be enabled for your tenant. - **Activation:** Contact your administrator to request hosted MCP access through Ask Sage support at [support@asksage.ai](mailto:support@asksage.ai). - **Box account:** Each user connects their own Box account via OAuth (see below). The Box tools only appear in chat once your account is connected — disconnected users see no Box tools. **Read-only integration.** The Box MCP is **read-only**. It can browse, search, and read your Box content (files, folders, versions, metadata, comments, shared links), but it cannot upload, create, move, delete, or otherwise modify anything in Box. After we work with you or your administrator to enable the integration, you'll receive confirmation and users can follow the setup steps below. ---------------- ## Connecting Your Box Account ### Link Box to your Ask Sage profile The first step is to connect your Box.com account to your Ask Sage profile. 1. **Open Settings → Integrations:** Open **Settings**, then select the **Integrations** tab. You'll see the available integrations, including **Box**. 2. **Connect Box:** Click **Connect** next to *Box — "Connect Box to search and use files from your Box workspace in chat."* ![The Integrations tab in Ask Sage Settings showing the Box Connect button](/assets/images/mcp-v2-box-integrations-connect.png) Settings → Integrations 1. **Log in and authorize:** A Box window opens. Enter your Box email and password and click **Authorize**, or use **Use Single Sign On (SSO)**. This grants Ask Sage access to Box on your behalf. ![The Box log-in window granting Ask Sage access to Box](/assets/images/mcp-v2-box-oauth-login.png) Authorizing Box access 1. **Verify the connection:** After authorizing, you're returned to Ask Sage. The Box integration now shows as connected. ---------------- ## Activating and Using the Box Tool ### Enable the tool in chat and pick a compatible model Once your account is connected, enable the tool in the chat interface to start using it. 1. **Open the Tools menu:** In the main chat window, click the settings icon (shown as sliders) above the text input field to open the configuration panel, then open **MCP Tools**. 2. **Enable Box MCP:** Find **Box Mcp** in the list and click its toggle. The switch turns blue when active, and the entry shows **20/20 tools** enabled. ![Enabling Box MCP in the MCP Tools panel, showing 20/20 tools active](/assets/images/mcp-v2-box-tool-toggle.png) Enabling Box MCP (20/20 tools) 1. **Select a compatible model:** Use a model that supports tool integration (MCP). Filter for these by selecting the *MCP* tag on the model selection screen. Models like **GPT-Auto** are designed to use these tools automatically. ![MCP-enabled model selection in Ask Sage](/assets/images/mcp-v2-model-picker-mcp-filter.png) Model Selection with MCP Filter ---------------- ## Making a Request ### Ask in natural language, approve the tool call You can now ask questions or give commands related to your Box content. 1. **Make a request:** Type a natural-language command into the chat. Because the integration is read-only, requests are about finding and reading content. For example: "List the files in my 'Contracts' folder in Box." 2. "Search Box for the Q3 budget spreadsheet." 3. "Summarize the document 'Vendor Agreement.pdf' from Box." 4. "Show me the version history of this file." 5. "List the comments on 'Proposal.docx'." 6. **Approve tool usage:** For security, Ask Sage prompts you before accessing your data. A **Tool Approval Required** card appears showing the exact tool (e.g. `search_content`) and its parameters. Review them and click **Approve** (or **Deny**). ![The Tool Approval Required card for a Box search_content call](/assets/images/mcp-v2-box-tool-approval.png) Tool Approval Required Once approved, Ask Sage executes the request through Box and returns the result — for example, a list of the files found in the requested folder. ![Ask Sage returning a table of Box files after the tool call](/assets/images/mcp-v2-box-tool-execution.png) Results returned from Box ---------------- ## Available Functions ### A sample of what the Box tool can do The Box tool exposes **20 read-only functions**. All of them retrieve information from Box — none of them modify, create, or delete content. They are grouped below by area. #### Files & folders | Function | Arguments | Description | | --- | --- | --- | | `list_folder_items` | `folder_id` *(optional: `limit`, `offset`, `recursive`)* | List the files and subfolders contained in a Box folder. | | `get_file` | `file_id` | Retrieve metadata for a specific file. | | `get_folder` | `folder_id` | Retrieve metadata for a specific folder. | | `get_file_content` | `file_id` | Read the content of a specific file. | | `get_file_versions` | `file_id` | List the version history of a file. | | `get_file_version_content` | `file_id`, `version_id` | Read the content of a specific file version. | | `get_file_thumbnail` | `file_id` | Retrieve a preview thumbnail image (PNG/JPG) for a file. | #### Search & discovery | Function | Arguments | Description | | --- | --- | --- | | `search_content` | `query` | Search across your Box account for files and folders by name or content. | | `get_current_user_info` | *none* | Retrieve information about the connected Box user. | | `get_recent_items` | *none* | List items you have recently accessed in Box. | | `get_collections` | *none* | List your Box collections (e.g. Favorites). | | `list_collection_items` | `collection_id` | List the items contained in a Box collection. | #### Shared links | Function | Arguments | Description | | --- | --- | --- | | `resolve_shared_link` | `shared_link_url` | Resolve a Box shared link URL to the file or folder it points to. | | `get_shared_link_info` | `item_type`, `item_id` | Retrieve the shared-link metadata for a file or folder. | #### Metadata | Function | Arguments | Description | | --- | --- | --- | | `list_metadata_templates` | *none* | Discover the enterprise and global metadata templates available. | | `get_file_metadata` | `file_id` | Retrieve the metadata instances attached to a file. | | `get_folder_metadata` | `folder_id` | Retrieve the metadata instances attached to a folder. | | `metadata_query` | `from_` *(`{scope}.{templateKey}`)* | Search Box content using a structured (SQL-like) metadata query. | #### Collaboration | Function | Arguments | Description | | --- | --- | --- | | `get_comments_on_file` | `file_id` | List the comments on a file. | | `get_web_link` | `web_link_id` | Retrieve a Box web link (bookmark) record. | ---------------- ## Support ### Stuck on connection or tool use? **Need help?** If you encounter any issues connecting your account or using the tool, reach out to us at [support@asksage.ai](mailto:support@asksage.ai). --- # Subscription Management Source: /docs/v2/subscription-management/subscription-management.html # Subscription Management Sign up, pay, change, or cancel — the full self-service lifecycle for `asksage.ai` accounts. ---------------- ### Note for Enterprise Plan Users **Heads up:** If you are not an Admin but are part of an Enterprise plan, please contact your Admin to request additional tokens. The instructions below are intended for individual users. ---------------- ## The Subscription Lifecycle ### Overview Self-service subscriptions on [`chat.asksage.ai`](https://chat.asksage.ai) follow a simple four-stage lifecycle. Each stage has its own page below — visit them in order the first time, or jump to whichever stage you need. 1. [Sign Up](./signup.html) Create your Ask Sage account and wait for activation. → 2. [Pay](./payment.html) Choose a plan and complete checkout with Stripe. → 3. [Change](./change.html) Update your tier, payment method, top up tokens, or change billing email. → 4. [Cancel](./cancel.html) End your subscription whenever you need to. ### Where to Start [Sign Up — you don't have an Ask Sage account yet. →](./signup.html) [Pay — your account is activated and you're ready to choose a plan. →](./payment.html) [Change — you already have a subscription and want to upgrade, switch payment methods, add more tokens, or update billing details. →](./change.html) [Cancel — you need to end your subscription. →](./cancel.html) **Where this applies:** Self-service purchase is available on the commercial tenant at [`chat.asksage.ai`](https://chat.asksage.ai). Government tenants use a different procurement path — contact [sales@asksage.ai](mailto:sales@asksage.ai) for those. ---------------- ## Need Help? ### Talk to Sales If you have questions about your subscription or need assistance, our team is here to help. Reach out and we'll get back to you with options for your plan. [Contact — sales@asksage.ai →](mailto:sales@asksage.ai) --- # Sign Up Source: /docs/v2/subscription-management/signup.html # Sign Up Create your Ask Sage account on `chat.asksage.ai` and get ready to pick a plan. ---------------- ## Before You Start ### What You'll Need - An email address you can receive messages at. - A strong password (used only for sign-in). - Access to your email inbox to enter the verification code Ask Sage sends you. **Heads up:** New accounts on `chat.asksage.ai` include a 30-day free trial that activates as soon as you verify your email. You can choose a plan whenever you're ready. ---------------- ## Where to Find Sign-Up ### Two Ways In - **Direct link:** [https://chat.asksage.ai/register](https://chat.asksage.ai/register) - **From the login page:** go to [https://chat.asksage.ai](https://chat.asksage.ai) and click **Sign Up** beneath the sign-in form. ---------------- ## Step-by-Step ### Step 1 — Open the Registration Page Navigate to [`chat.asksage.ai`](https://chat.asksage.ai) and click **Sign Up** on the login screen. ![Login page with Sign Up button](/assets/images/subscription-management-v2-register-login-link.png) The login page on `chat.asksage.ai` — click **Sign Up** to create a new account. ### Step 2 — Fill the Registration Form Enter your email, a strong password, and your name. Submit the form when complete. ![Registration form](/assets/images/subscription-management-v2-register-form.png) The registration form on `chat.asksage.ai/register`. ### Step 3 — Verify Your Email After submitting the registration form, you'll be taken to a **Verify your email** screen. Check your inbox for a verification code from Ask Sage, enter it here along with your email, and click **Login**. ![Verify your email screen](/assets/images/subscription-management-v2-verify-email.png) Enter the verification code from your inbox to confirm the email on your new account. [Code didn't arrive? Check your spam folder, or email support@asksage.ai. →](mailto:support@asksage.ai) ### Step 4 — Sign In Once your email is verified, sign in at [`chat.asksage.ai`](https://chat.asksage.ai). You'll land on the platform with a 30-day free trial active, ready to choose a plan when you want to. [Pay — choose a subscription and purchase tokens. →](./payment.html) ---------------- ## Need Help? ### Talk to Sales If your account isn't activating, or if you have questions about which plan fits your use case, get in touch. [Contact — sales@asksage.ai →](mailto:sales@asksage.ai) --- # Pay Source: /docs/v2/subscription-management/payment.html # Pay Choose a plan and complete checkout with Stripe — tokens land in your account immediately. ---------------- ## Before You Start ### What You'll Need - An activated Ask Sage account on [`chat.asksage.ai`](https://chat.asksage.ai). If you don't have one yet, start with [Sign Up](./signup.html). - A payment card (Visa, Mastercard, American Express, or Discover). - A billing address. **About the screenshots:** The Stripe checkout screenshots on this page were captured with a Stripe test card so the flow could be documented without billing real money. Sensitive fields (card number, name, billing address, phone) are blurred. When you check out, you'll use a real card with the same form. ---------------- ## Step-by-Step ### Step 1 — Open Usage & Billing Sign in to [`chat.asksage.ai`](https://chat.asksage.ai). Click your name at the bottom-left of the sidebar to open the user menu, choose **Settings**, then click the **Usage & Billing** tab inside the Settings dialog. This is the entry point for every subscription action. ![Usage & Billing tab on a trial account](/assets/images/subscription-management-v2-usage-billing-trial.png) Usage & Billing on a fresh trial account — current plan, token meters, and the Manage Subscription button. ### Step 2 — Click Manage Subscription Click the **Manage Subscription** button. This opens the plan picker in a new browser tab. ### Step 3 — Choose a Plan The plan picker lists every tier with its included monthly token allowance and price. Each plan includes access to all models, document upload, and enterprise-grade security — tiers differ only in token allowance. Use the **Monthly / Yearly** toggle near the top to switch between billing frequencies. Yearly billing gives a small discount over the monthly price. ![Choose Your Plan screen with five tier cards](/assets/images/subscription-management-v2-plan-selection.png) Choose Your Plan — five monthly tiers from Starter to Ultimate. Click **Get Started** on the tier you want. You can always change it later (see [Change](./change.html)). ### Step 4 — Complete Stripe Checkout Selecting a plan opens Stripe Checkout. Your email is pre-filled from your Ask Sage account. Choose **Card** as the payment method, then enter: - Card number, expiration, CVC - Cardholder name - Billing address (autocompletes from address lookup, or click **Enter address manually**) - Phone number ![Stripe Checkout card form](/assets/images/subscription-management-v2-stripe-checkout-card.png) Stripe Checkout — Card payment form expanded. Review the order summary on the left — for a mid-month start, the first charge is prorated, then full price recurs each cycle. Click **Subscribe** to complete the purchase. **Card data:** Card details are submitted directly to Stripe. Ask Sage never sees or stores your full card number. ### Step 5 — Confirmation After payment succeeds, you'll be returned to Ask Sage. Reopen **Settings → Usage & Billing** to confirm your new plan is active — the **Current Plan** field now shows your chosen tier and the token meters reflect your new allowance. Stripe emails a receipt to the email on your Ask Sage account. ![Usage & Billing tab on a paid account](/assets/images/subscription-management-v2-usage-billing-active.png) Usage & Billing after payment — Current Plan, tokens reset date, and updated token meters. **What's now enabled:** Full access to the models included in your plan, your monthly token allowance, and the ability to top up additional tokens or change plans at any time. ---------------- ## After You Pay ### Next Steps [Change — switch tiers, update your card, top up tokens, or update your billing email. →](./change.html) [Cancel — end your subscription whenever you need to. →](./cancel.html) ---------------- ## Need Help? ### Talk to Sales If a payment doesn't go through, or you need help picking the right plan, get in touch. [Contact — sales@asksage.ai →](mailto:sales@asksage.ai) --- # Change Source: /docs/v2/subscription-management/change.html # Change Switch tiers, update your payment method, or change your billing email. ---------------- ## Two Places You'll Work ### Ask Sage Platform vs. Stripe Customer Portal Most subscription changes live in **two different places**. It's easy to get lost going between them, so here's the map: - **Inside the Ask Sage platform** ([`chat.asksage.ai`](https://chat.asksage.ai)) — check your token balance and open the path to the Stripe portal. - **Inside the Stripe customer portal** — change your plan, update your payment method, change your billing email, and download invoices. The portal opens in a new tab and looks different from Ask Sage. **The path is the same every time:** User menu → **Settings** → **Usage & Billing** → **Manage Subscription** → (plan picker opens) → **Manage Subscription** at the bottom of that page → (Stripe portal opens). ---------------- ## Finding the Manage Subscription Button ### Step 1 — Open Usage & Billing Sign in to [`chat.asksage.ai`](https://chat.asksage.ai). Click your name at the bottom-left of the sidebar to open the user menu, choose **Settings**, then click the **Usage & Billing** tab inside the Settings dialog. This view summarizes your current plan, token meters, and remaining balance. ![Usage & Billing tab](/assets/images/subscription-management-v2-usage-billing-trial.png) Usage & Billing — your plan, token meters, and the Manage Subscription button. ### Step 2 — Press Manage Subscription (twice) Press the **Manage Subscription** button. A new tab opens to a plan-picker page that shows your current plan and the other available tiers. This is *not* yet the Stripe customer portal. Scroll to the bottom of that page and press **Manage Subscription** again. *That* second click opens the Stripe customer portal in the same tab, where plan changes, payment method updates, billing email changes, and cancellation all happen. **Two buttons, same name:** The first **Manage Subscription** (inside Ask Sage) opens the plan picker. The second **Manage Subscription** (at the bottom of the plan picker) opens the Stripe portal. Everything below this section happens in the Stripe portal. ---------------- ## Change Your Plan or Tier ### Upgrade or Downgrade In the Stripe customer portal, find your current subscription and click **Update subscription**. Switch between **Monthly** and **Yearly** at the top if you want to change billing frequency, then click **Select** on the new tier and press **Continue**. Stripe will prorate the charge or credit for the rest of your billing period. ![Stripe portal Update subscription page with tier choices](/assets/images/subscription-management-v2-stripe-portal-update-plan.png) Stripe customer portal — Update subscription page. Current tier is marked Selected; press Select on a different tier and then Continue. **Pro Tip:** Watch your token usage for a couple of months before downgrading. If you frequently hit your monthly allowance, a larger plan is usually cheaper than repeated top-ups. ---------------- ## Change Your Payment Method ### Add, Set Default, or Remove a Card In the Stripe customer portal, the **Payment method** section on the main page lists your card on file. From there you can: - **Add a new card** — click **Add payment method**, enter the card details, and confirm. - **Set as default** — open the **More options** menu on a card. The default card is used for the next renewal. - **Remove a card** that's no longer in use — also in the **More options** menu. ![Stripe portal Add payment method form](/assets/images/subscription-management-v2-stripe-portal-payment-methods.png) Stripe customer portal — Add payment method form. **Heads up:** You can't remove the only payment method on file. Add the new card and set it as default first, then remove the old one. ---------------- ## Need More Tokens? ### Upgrade Your Tier If you've used your monthly allowance and need more tokens before the next reset, upgrade to a higher tier using the [Change Your Plan or Tier](#change-your-plan-or-tier) steps above. Stripe prorates the charge so you only pay the difference for the rest of the current billing cycle, and the larger allowance is available immediately. **Pro Tip:** Watch your monthly token usage for a couple of cycles before settling on a tier. If you frequently hit your allowance, the next tier up is usually cheaper than upgrading mid-cycle. ---------------- ## Change Your Billing Email ### Update Where Receipts Are Sent Your billing email is where Stripe sends invoices and receipts. It can be different from the email you sign in to Ask Sage with. In the Stripe customer portal, find the **Billing information** section on the main page and click **Update information**. Edit the email (and billing address if needed) and save. ![Stripe portal Update billing details form](/assets/images/subscription-management-v2-stripe-portal-billing-info.png) Stripe customer portal — Update billing details. Change the email here to redirect invoices and receipts. **Sign-in email vs. billing email:** Changing your billing email here only affects where receipts are sent. Your Ask Sage sign-in email is changed inside the Ask Sage platform, not here. ---------------- ## Need Help? ### Talk to Sales If a change in the portal doesn't take effect, or you can't see the option you expect, reach out. [Contact — sales@asksage.ai →](mailto:sales@asksage.ai) --- # Cancel Source: /docs/v2/subscription-management/cancel.html # Cancel End your subscription whenever you need to — your account and data stay intact. ---------------- ## Before You Cancel ### What Cancelling Does — and Doesn't — Do - **Stops future billing.** You won't be charged again at the next renewal. - **Keeps access until your paid period ends.** You can keep using the tokens you've already paid for through the end of the current billing cycle. - **Does not delete your account.** Your sign-in, datasets, agents, and chat history stay intact. - **Does not delete your datasets.** They remain available if you re-subscribe later. **Considering a smaller plan instead?** See [Change](./change.html) to downgrade to a lower tier rather than cancel outright. ---------------- ## Step-by-Step ### Step 1 — Open Manage Subscription Sign in to [`chat.asksage.ai`](https://chat.asksage.ai). Click your name at the bottom-left of the sidebar, choose **Settings**, open the **Usage & Billing** tab, and press **Manage Subscription**. A new tab opens to the plan-picker page — *not* the Stripe portal yet. Scroll to the bottom of that page and press **Manage Subscription** again to reach the Stripe customer portal, where cancellation happens. ![Usage & Billing tab with Manage Subscription button](/assets/images/subscription-management-v2-usage-billing-active.png) Usage & Billing — the first **Manage Subscription** button. A second one waits at the bottom of the page that opens. ### Step 2 — Cancel in the Stripe Portal In the Stripe portal, find your active subscription and click **Cancel subscription**. Stripe shows a confirmation page that reminds you the subscription stays active through the end of your current billing period. Press **Cancel subscription** on that page to confirm. ![Stripe portal Confirm cancellation page](/assets/images/subscription-management-v2-stripe-portal-cancel.png) Stripe customer portal — Confirm cancellation. The notice spells out the date your access ends. ### Step 3 — Confirmation Stripe confirms the cancellation on-screen (with an optional feedback survey you can skip) and emails a receipt to your billing email. The portal now shows a **Cancels Jul 1** (or whatever your end date is) badge on the subscription, and the line *"Your service will end on [date]"* replaces the next-billing-date line. ![Stripe portal showing the subscription canceled and the end-of-service date](/assets/images/subscription-management-v2-stripe-portal-cancel-confirmed.png) Stripe customer portal after cancellation — service end date is clear, and a **Don't cancel subscription** link is available if you change your mind before that date. **Changed your mind?** Until your service-end date, the Stripe portal shows a **Don't cancel subscription** link in place of **Cancel subscription**. Click it and confirm **Renew subscription** to keep your plan running on the same schedule. ---------------- ## After Cancellation ### What Happens Next - **Through end of billing period:** Your subscription stays active. You can continue using your remaining tokens normally. - **After the period ends:** Token spend on paid models stops. Your account stays signed in and your data stays in place. - **If you change your mind before the end date:** Open the Stripe portal again and click **Don't cancel subscription** to renew on the same schedule (no new checkout needed). - **If you change your mind after the end date:** Re-subscribe by going to Settings → **Usage & Billing** → **Manage Subscription** and choosing a plan. See [Pay](./payment.html). **Your data stays:** Cancelling does not delete your account, your datasets, or your chat history. They're waiting for you if you re-subscribe. ---------------- ## Need Help? ### Talk to Sales Cancelling because something isn't working for you? We'd like to hear about it before you go. [Contact — sales@asksage.ai →](mailto:sales@asksage.ai) --- # User Guides Source: /docs/v2/user-guides/user-guides.html # User Guides Step-by-step tutorials and best practices to help you master Ask Sage's powerful features --- ## Getting Started ### Quick Start Guides Get up and running with Ask Sage in minutes with onboarding tutorials, account setup walkthroughs, and first-time user guides. [Ask Sage 101 Field Guide](asksage-101/index.html) --- ## Core Features ### Ask Sage Datasets Master vector-powered datasets and RAG technology. Learn to organize, ingest, and leverage your organization's content for accurate, contextually relevant AI responses. **Core Skill:** Datasets are fundamental to Ask Sage's power. Understanding how to create and manage datasets will unlock the full potential of the platform. [Read Full Guide](ask-sage-datasets.html) --- ## Advanced Topics ### Advanced Techniques Master advanced workflows and optimization strategies with expert-level tutorials on custom integrations, API usage, workflow automation, and performance optimization. **Coming Soon:** Advanced tutorials are in development. --- ## Enterprise & Administration ### Enterprise Management Guides for administrators and enterprise users covering team management, security policies, usage analytics, billing administration, and enterprise deployment strategies. **Coming Soon:** Enterprise guides for administrators are being created. --- ## Use Case Tutorials ### Industry Solutions Real-world examples and industry-specific tutorials for software development, research, content creation, customer support, education, and business intelligence use cases. **Coming Soon:** Industry-specific use case guides are being developed. --- # Ask Sage Datasets Source: /docs/v2/user-guides/ask-sage-datasets.html # Ask Sage Datasets Organize, ingest, and leverage your organization's content with vector-powered datasets. Ground AI responses in your specific sources for accurate, contextually relevant results. --- ## Overview ### What Are Ask Sage Datasets? Ask Sage Datasets are organized collections of your organization's content—including text, images, and audio—that you ingest into the platform to ground AI-generated responses in your specific sources. Datasets enable you to ingest data once and reuse it across multiple prompts, models, and team members, ensuring consistent, accurate, and contextually relevant results. ### Accuracy & Relevance Generate responses grounded in your specific materials rather than generic web content ### Efficiency & Reuse Ingest content once and reuse across different prompts, models, and use cases ### Team Collaboration Share datasets to establish a single source of truth across your organization ### Advanced Search Use Search Datasets plugin to quickly locate specific facts and information ### Model Flexibility Use datasets with any GenAI model—never locked into a single provider ### CUI Support Classify datasets as Unclassified or CUI for controlled information --- ## Getting Started ### Selecting Datasets in Prompt Settings 1. Access Data & Settings Click the Data & Settings button below your prompt window → 2. Select Dataset(s) Choose one or multiple datasets for context → 3. Submit Prompt Send your prompt with dataset context **Pro Tip:** Selected datasets appear under your prompt window, making it easy to see what context you're using for each query. ### Attachments vs. Datasets Understanding the difference helps you choose the right approach: ### Chat Attachments - One-time use only - Single conversation - Not shareable - Quick, ad-hoc analysis ### Datasets - Permanent reusable storage - Available across all prompts - Shareable with team - Recurring reference material **Important:** Files you attach in a chat are for one-off use only. To save them permanently, you must explicitly ingest them into a dataset. ### Creating and Ingesting Datasets 1. Create Dataset Click Prompt Tools → Data & Settings → Create New Dataset → 2. Name & Classify Enter name (alphanumeric/hyphens) and classify as Unclassified or CUI → 3. Upload Files Drag/drop or browse to select files (max 50MB each) → 4. Ingest Click Ingest Files and wait for success confirmation **Example:** A dataset name like `product-docs-2025` or `research-papers-q1` helps organize your content effectively. **CUI Classification:** Requires CAC/PIV card or special activation. Contact [support@asksage.ai](mailto:support@asksage.ai) for CUI access. ### Supported File Formats Ask Sage supports a wide range of file types. Common formats include: ### Documents - .pdf - .doc, .docx - Word documents ### Spreadsheets - .xls, .xlsx - .csv - Tabular data ### Presentations - .ppt - .pptx - Slide decks ### Images & Media - .jpg, .png - .gif, .svg - Visual content ### Data Formats - .json, .xml - .html, .yaml - Markup languages ### Text Files - .txt, .rtf - .log files - Plain text **Maximum File Size:** 50MB per file. Images embedded in documents won't be extracted—upload them separately. ### Managing Your Datasets ### Share Collaborate by sharing datasets with team members ### Copy Duplicate for different use cases without re-ingesting ### View Details See metadata, file counts, and ingestion status ### Delete Remove datasets you no longer need --- ## Understanding Tokens and Usage ### Training vs. Inference Tokens ### Training Tokens - Used when ingesting data - Converting to embeddings - Building your datasets ### Inference Tokens - Used when querying - Generating responses - Daily interactions **Monitor Usage:** Check Settings → Tokens to track your consumption and remaining quota. Tokens reset monthly and do not roll over. --- ## Best Practices for Dataset Creation ### Key Principles Follow these best practices to get the most value from your datasets: ### Stay Focused Create purpose-built datasets for specific use cases rather than large "catch-all" collections - Clear dataset purpose - Relevant content only - Easier to manage ### Preprocess Files Clean and prepare your documents before ingestion for better results - Remove unnecessary pages - Fix formatting issues - Verify OCR quality ### Prioritize Quality Use high-quality, authoritative sources rather than maximizing quantity - Remove duplicates - Current information - Verified accuracy ### Maintain Hygiene Keep your datasets fresh and well-organized over time - Regular audits - Update outdated content - Consistent naming **Split Large Documents:** For documents over 100 pages, consider splitting them into smaller chunks (e.g., 20-page sections) for better retrieval and accuracy. --- ## Understanding RAG Technology ### What Is RAG (Retrieval Augmented Generation)? RAG is the core technology powering Ask Sage Datasets. It works by combining your ingested data with AI models to generate accurate, grounded responses. 1. Retrieve Query converts to embedding and searches dataset → 2. Rank Relevant passages ranked by relevance → 3. Augment Retrieved context combined with prompt → 4. Generate AI produces grounded, accurate response **Result:** Instead of generic answers, you get responses specifically grounded in your organization's data and knowledge. ### Why RAG with Datasets Wins ### Reduce Hallucinations AI can only reference what you've provided, not invent facts ### Stay Current Override AI training cutoffs with your latest information ### Add Expertise Inject your domain-specific knowledge into responses ### Full Transparency See exactly which sources informed each response **Technical Note:** Datasets store embeddings (numerical representations), not original files. This enables fast semantic search across your entire collection. --- ## Technical Considerations ### Vector Database Optimization ### Best For - Semantic search - Unstructured text - Document retrieval ### Not For - Tabular data analysis - SQL queries - Structured databases **Workaround:** For spreadsheets, attach them directly to prompts—Ask Sage will use Python to analyze the data. ### Token Efficiency Tips ### Optimize Usage - Select only relevant datasets - Use "None" when not needed - Monitor in Settings → Tokens ### CUI Compliance - Live feature not CUI-safe - Classify datasets correctly - Contact support for CAC/PIV --- # Sales/Cost Source: /docs/v2/asksage-sales.html # Pricing & Sales Flexible plans to fit your needs ![Ask Sage Logo](/assets/images/ask-sage-logo.png) ---------------- ## Get in Touch ### Talk to Sales Have questions about pricing, features, or enterprise solutions? Our sales team is ready to help. [Contact Sales sales@asksage.ai — reach out for quotes, demos, and enterprise inquiries →](mailto:sales@asksage.ai) [View Latest Pricing Visit asksage.ai/pricing for current plans and details →](https://www.asksage.ai/pricing) ---------------- ## Plans & Deployment ### Enterprise Purchases Buy Ask Sage tokens in bulk and assign them to your users (minimum 200,000 tokens per user) via our Administration UI, without paying a per-user fee. **Starts at $90/mo** for 2 million Ask Sage tokens per month. ### On-Premise & Cloud Deployment Ask Sage can be deployed on your Cloud enclaves and/or on-premise environments. Reach out to us for more information on how to deploy Ask Sage in your environment. **Custom deployments:** Email [sales@asksage.ai](mailto:sales@asksage.ai) to discuss requirements, security posture, and rollout timelines. --- # Ask Sage Tokens Source: /docs/v2/asksage-tokens/asksage-tokens.html # Ask Sage Tokens One token system, every model. The unit you spend on chat, agents, datasets, and Workbooks. ---------------- ## Tokens at a Glance ### What a token is, and why Ask Sage has its own In generative AI, a **token** is a unit of text the model processes — roughly a short word, a piece of a longer word, or a punctuation mark. Models charge by the token, both for what you send (the prompt) and what they send back (the response). Most platforms expose the underlying provider's token meter directly, which means switching models also switches the units, the rates, and the math. **Ask Sage tokens are different:** they're a model-agnostic currency. You spend Ask Sage tokens regardless of which underlying model handles the prompt — flagship, standard, lightweight, reasoning, CUI, Non-CUI — and the platform handles the conversion to provider tokens behind the scenes. That means one balance to watch, one set of refill mechanics, and one mental model that doesn't break when you switch models in [Model Compare](/docs/v2/model-compare/model-compare.html) or pin a different default for a workflow. **One currency, two flavors:** Ask Sage tokens come in two types — **Inference** (what you spend when models do work) and **Training** (what you spend when data gets ingested into a Dataset or Workbook). Training Tokens are also referred to as Embedding Tokens and are used in the Documentation interchangeably. They have separate balances and separate rates. ---------------- ## How Tokens Are Counted ### Prompt + response = total Every interaction with a model consumes tokens for both halves of the exchange: the prompt you send and the response you get back. If your prompt is 12 tokens and the response is 180 tokens, the interaction cost 192 tokens. Three things to keep in mind: - **Cost varies by model.** Flagship models cost more per token than standard or lightweight tiers. The same prompt sent to two models will spend different numbers of Ask Sage tokens. - **Prompt and response can be priced differently.** For most models, output (response) tokens are more expensive than input (prompt) tokens. A short prompt with a long response can cost more than a long prompt with a short response. - **Conversation history is included.** In a multi-turn chat, prior turns are sent with each new prompt as context. Long conversations cost more per turn than short ones, even if your latest message is brief. The [Conversation Context](/docs/v2/asksage-platform/getting-started/conversation-context.html) panel shows how much history is riding along on each send. **Compare uses double the tokens.** When you use [Model Compare](/docs/v2/model-compare/model-compare.html), your prompt is dispatched to two models simultaneously, so each send costs roughly 2× a regular chat. Use Compare deliberately for decisions, not as a default chat surface. ---------------- ## Inference Tokens ### What you spend when models do work **Inference tokens** are consumed any time a model produces a response. That covers most of what you'll do day-to-day on the platform. Things that spend inference tokens: - **Chat** — every message you send and every response the model returns. - **Personas** — the system prompt counts as part of the input on every turn, so heavier personas cost more per message than lighter ones. - **Datasets (RAG retrieval)** — when a Dataset is attached, retrieved chunks are added to the prompt as context. Bigger retrievals mean bigger prompts. - **[Workbook](/docs/v2/workbook/workbook.html) actions** — once data is in a Workbook, asking questions or running operations against it spends inference tokens (the ingestion itself is a training-token cost — see below). - **Model Compare** — both panes consume inference tokens on every send. - **Code Canvas** — generating code, running Quick Actions, and chat turns inside a canvas all spend inference tokens. - **MCP Tools and Deep Agent** — agentic workflows can chain multiple model calls per user turn, so a single instruction may spend more tokens than a normal chat. **Agentic workloads scale fast:** MCP Tools and Deep Agent can fan out into many sub-calls under a single user instruction. A "summarize my open tickets" prompt might internally make a dozen tool calls plus a synthesis step. That's powerful, but it's not free — watch your inference balance when you're iterating on agent workflows. ---------------- ## Training Tokens ### What you spend when data gets ingested **Training tokens** are consumed when content is processed into a vector database — embedded, indexed, and stored so that future prompts can retrieve from it. This is a one-time cost per piece of ingested content; you pay it when the data goes in, not when you query it later. Things that spend training tokens: - **Dataset ingestion** — uploading files, pasting text, or pointing to a source for inclusion in a Dataset. Each chunk gets embedded and stored. - **[Workbook](/docs/v2/workbook/workbook.html) ingestion** — same mechanic as Datasets, applied to the documents that ground a Workbook's bound conversation. The reason training tokens are billed separately is that ingestion is a different operation from inference. It uses embedding models rather than generative models, runs at a different cost basis, and only happens when data changes — not on every prompt. **[Workbooks](/docs/v2/workbook/workbook.html) straddle both:** A Workbook costs **training tokens** when you first ingest its source documents (or add new ones), and **inference tokens** every time you ask a question or run an action against the ingested content. Plan accordingly when comparing Workbook costs to plain chat: the upfront ingestion is the trade you make for cheaper, faster querying afterward. **Pricing reference:** Inference and training tokens are priced differently, and rates change. For current pricing, plan tiers, and bulk-purchase options, see [Sales/Cost](/docs/v2/asksage-sales.html). ---------------- ## Where to See Your Usage ### Find your balances in two clicks Token balances live in the platform's **Settings → Usage & Billing** panel. The path is the same on every screen. **Step 1.** Click your avatar in the bottom-left corner of the left rail to open the user menu, then select **Settings**. ![User menu with Settings highlighted](/assets/images/asksage-tokens-v2-menu.png) User menu — Settings, Dark Mode, Classic View, Help, Updates, Disclosures, Log out **Step 2.** In the Settings dialog, choose **Usage & Billing** from the left-hand tabs. ![Usage & Billing tab showing plan, reset date, inference and training token balances](/assets/images/asksage-tokens-v2-usage.png) Usage & Billing — current plan, monthly reset date, inference and training balances with progress bars The panel surfaces four things at a glance: - **Current plan** — your subscription tier (e.g. Enterprise, individual plan name). - **Reset date** — when this month's allotment refreshes (e.g. "Tokens reset Jun 1 · in 27 days"). Both balances reset together. The reset happens at 00:00 UTC, which may land earlier or later than midnight in your local timezone. - **Inference Tokens** — used vs. allotted, with a percentage and progress bar. - **Training Tokens** — same display, separate balance. The **Manage Subscription** button on this panel is the entry point for plan changes, refills, and Enterprise admin actions — see the next section. ---------------- ## Managing & Refilling Tokens ### Change your plan, top up, or contact an admin Once you can see your balances in **Settings → Usage & Billing**, three operational paths cover most situations: #### Top up or change plan Click **Manage Subscription** on the Usage & Billing panel. #### Compare plans or pricing See [Sales/Cost](/docs/v2/asksage-sales.html) for tiers, pricing, and bulk options. #### Enterprise: contact your admin Non-admin Enterprise users go through their org's admin for additional tokens. For step-by-step instructions on subscription changes inside the platform, see [Subscription Management](/docs/v2/subscription-management/subscription-management.html). **Tokens reset monthly, no rollover:** Both Inference and Training balances refresh at 00:00 UTC on the first of each month — not local midnight, so the reset may appear to happen late on the last day of the month or early on the 2nd depending on your timezone. Unused tokens do **not** carry forward — what you don't spend is gone. Plan ingestion-heavy work (Dataset and Workbook builds) early in the month so you have headroom for inference work later. ---------------- ## Gotchas ### Things that bite users - **No rollover.** Unused tokens at month-end are forfeit. If you're consistently leaving tokens on the table, you're on a higher plan than you need; if you're consistently running out, you're on a lower one. - **Compare doubles your spend.** Every prompt in Model Compare goes to two models. Useful for decisions, expensive as a daily driver. - **Flagship models cost meaningfully more per token.** A "what's the capital of France" answered by a flagship reasoning model is wasteful. Match the model tier to the difficulty of the work. - **Long conversations grow expensive.** Every turn in a chat sends the prior history along as context. A 50-turn chat costs more per send than a fresh one. Start a new chat when the topic shifts — check the [Conversation Context](/docs/v2/asksage-platform/getting-started/conversation-context.html) panel to see how full the window has gotten. - **RAG retrievals add to the prompt.** Datasets and Workbooks pull in retrieved chunks on every query. Big retrievals are useful but not free. - **Agentic flows can fan out.** One prompt to a Deep Agent or MCP-enabled chat can become many internal model calls. Inspect what the agent is doing if your spend looks higher than expected. - **Workbook ingestion is a one-time training-token cost; querying is ongoing inference.** Don't confuse the two when forecasting a Workbook's lifetime cost. - **Persona length is a per-message tax.** A multi-paragraph persona ships with every prompt. Trim what you don't need. **Spend deliberately:** The platform gives you the same currency across every model and every feature. Knowing where each token goes — chat, ingestion, agentic fan-out, Compare doubling — is how you keep the monthly burn predictable and the work productive. --- # Code Canvas Source: /docs/v2/code-canvas/code-canvas.html # Code Canvas An AI-paired code editor with chat, syntax highlighting, quick actions, and live preview for HTML and SVG ---------------- ## What is Code Canvas? ### Overview `Code Canvas` is a dedicated workspace that pairs a chat with a live code editor. Generate code with the assistant, edit it directly in the editor, run quick actions like *Find bugs* or *Refactor for readability*, and preview HTML or SVG output in real time. It's built for developers who want to iterate on code in a tight loop with an LLM, without losing the context of what's being built. ![Code Canvas](/assets/images/code-canvas-v2-hero.png) Code Canvas — chat on the left, live editor on the right, with a single workspace for paired AI iteration. **Getting Started:** Click `Code Canvas` in the left rail. The workspace opens with an empty Canvas Chat on the left and an empty editor on the right. ### Why a separate workspace for code? You can paste code into a regular Chat and ask for help. Code Canvas exists because that flow has limits: - **Code lives in messages, not in an editor.** In a chat, every iteration produces a new copy of the code in a new message. You scroll back and forth comparing versions. In Canvas, the code is a single live document — edit it, regenerate it, undo/redo it. - **No syntax highlighting in chat messages.** The editor in Canvas has language-aware syntax highlighting and line numbers. You can read what you're working on. - **No live preview in chat.** Canvas previews HTML and SVG output instantly in a side tab — no copy-pasting into a separate viewer to see what your component actually looks like. - **Pre-canned actions are one click away.** *Find bugs*, *Add error handling*, *Refactor for readability*, and others can be invoked directly on the code in the editor — no re-typing the same prompt every time. Code Canvas is for the focused, iterative work of *building* code. Regular Chat is for *talking about* code. ---------------- ## The Workspace ### Two-pane split Code Canvas is a two-pane split: - **Canvas Chat (left)** — a chat thread dedicated to this canvas. Header shows `Canvas Chat · [model]`. The `+` button starts a new canvas (clears the editor and chat). Composer at the bottom with model picker, prompt enhancer, voice input, and send. - **Editor (right)** — a live code editor with syntax highlighting and line numbers. Tab bar at the top: **Editor** (active by default) and **Preview** (active when the code is HTML or SVG). Language picker dropdown to the left of the toolbar. Toolbar (top-right): undo, redo, copy, download. - **Footer** — below the composer, two indicators: dataset state and CUI (Controlled Unclassified Information)/classification badge. When you start typing in the chat, the assistant generates code into the editor. When you edit code in the editor manually, the chat picks up your changes the next time you ask for something. The two panes stay in sync. ![Code Canvas Workspace](/assets/images/code-canvas-v2-workspace.png) The Code Canvas split — Canvas Chat on the left, Editor with Editor/Preview tabs on the right. ---------------- ## How to Use Code Canvas ### Step-by-Step Workflow 1. Start with a Prompt or Paste Code Ask the assistant to generate something, or paste existing code into the editor to work on. → 2. Iterate Refine through the chat, run Quick Actions, or edit the code directly in the editor. → 3. Preview, Copy, or Download Render HTML/SVG output in the Preview tab, copy to clipboard, or download as a file. ### Start with a Prompt or Paste Code Two entry points work for any new canvas: - **Generate from a prompt.** Type what you want in the chat — for example, *"Make a React counter component with a reset button."* The assistant writes code into the editor and explains what it did in the chat. - **Paste existing code.** Click into the editor, paste your code, then ask the chat to do something with it: *"Find bugs in this,"* *"Convert to TypeScript,"* or *"Refactor for readability."* Both flows feed the same workspace. You can mix them — generate a starter component, then paste in additional code to extend it. ### Iterate Three ways to make changes after the first version: - **Talk to the chat.** Ask follow-up questions or request changes in plain English: *"Add a step counter,"* *"Use Tailwind instead of inline styles."* The assistant updates the code in the editor. - **Run a Quick Action.** Open the composer panel (sliders icon) → **Quick actions** for one-click operations like Find bugs or Refactor. See the [Quick Actions](#quick-actions) section for the full list. - **Edit the code directly.** Click into the editor and type. The editor has syntax highlighting and line numbers. Use undo/redo in the toolbar to step backward and forward through your edits. ### Preview, Copy, or Download Once the code is where you want it: - **Preview** (HTML or SVG only) — click the **Preview** tab at the top of the editor pane to render the output. The Preview tab is greyed out for other languages. - **Copy** — toolbar copy icon copies the entire editor contents to your clipboard. - **Download** — toolbar download icon saves the editor contents to your computer as a file with the appropriate extension. Code in the editor does not execute (with the narrow exception of HTML and SVG rendering in the Preview tab). To actually run logic, copy or download the code into your IDE or runtime. ![Code Canvas Populated](/assets/images/code-canvas-v2-populated.png) A populated canvas — chat thread on the left, generated code in the editor on the right. ---------------- ## Quick Actions ### Pre-canned prompts that operate on your code Quick Actions are pre-canned prompts that operate on the current code in the editor. Open the composer panel (sliders icon at the bottom-left of the chat composer) → **Quick actions** to access them. | Action | When to use it | | --- | --- | | **Add comments** | The code works but isn't documented. Adds inline comments and docstrings without changing logic. | | **Make it shorter** | The code is verbose. Condenses without changing behavior — useful for trimming AI-generated boilerplate. | | **Convert to TypeScript** | You have JavaScript and want types. Converts in place; remember to switch the language picker to TypeScript afterward. | | **Find bugs** | The code looks right but isn't behaving. The assistant reviews for logic errors, edge cases, and likely bugs. Output goes to the chat, not the editor. | | **Add error handling** | The happy path works; you want graceful failure. Wraps risky operations in try/catch (or equivalent) and adds validation. | | **Refactor for readability** | The code works but is hard to follow. Renames variables, breaks up long functions, simplifies conditionals. | Quick Actions are greyed out when the editor is empty — they need code to operate on. Once you've generated or pasted code, they activate. ![Quick Actions menu](/assets/images/code-canvas-v2-quick-actions.png) Quick Actions menu — six pre-canned prompts that operate on the current editor contents. ---------------- ## The Editor ### A real code editor, not just a code-display block The right pane is a real code editor, not just a code-display block. #### Language picker Dropdown in the top-left of the editor pane. Sets syntax highlighting for the editor and the language used by the **Convert to TypeScript** Quick Action's target. Currently supported with full syntax highlighting: - JavaScript, TypeScript, JSX, TSX - Python - HTML, CSS, SCSS - JSON, YAML - Markdown - (more available — open the dropdown for the full list) Languages outside this list may still display in the editor but won't be highlighted. The picker also **auto-detects** when the assistant writes new content to the editor. If you ask for SVG, the picker switches to SVG. If you paste Python, it switches to Python. You can override the detection manually if needed, but the default behavior gets it right most of the time. #### Toolbar Top-right of the editor pane: - **Undo** — step backward through edits (both your manual edits and assistant-generated changes). - **Redo** — step forward through previously undone edits. - **Copy** — copy the entire editor contents to your clipboard. - **Download** — save the editor contents to a file with the appropriate extension for the selected language. #### Manual editing Click into the editor and type. The editor supports standard text-editing keystrokes (cut, copy, paste, line manipulation). Edits made manually are seen by the chat the next time you ask for something. ![Language picker](/assets/images/code-canvas-v2-language-picker.png) The language picker — sets syntax highlighting for the editor. ---------------- ## Live Preview ### Render HTML and SVG output instantly When the editor contains HTML or SVG, the **Preview** tab activates at the top of the editor pane. Click it to render the output side-by-side with where the editor was. The Preview tab activates **automatically** when previewable content lands in the editor — you don't have to flip the language picker or toggle a setting. If the assistant writes SVG, Preview lights up. If you paste in HTML, Preview lights up. If you switch to Python or JSON, Preview greys out again. #### What previews - **HTML** — renders the page as a browser would, including embedded CSS and inline JavaScript. - **SVG** — renders the vector graphic. #### What does NOT preview - JavaScript, TypeScript, JSX/TSX (logic doesn't execute) - Python (no runtime) - CSS, SCSS (need an HTML host to render against) - JSON, YAML, Markdown (data formats and text) For non-previewable code, the **Preview** tab is greyed out with the note *"(preview available for HTML / SVG)"* in the header. **Use Preview to:** verify a UI component renders correctly, check an SVG icon's appearance, validate that styling matches expectation. **Don't use it to:** test runtime behavior, verify logic, or simulate API calls — none of those happen in Preview. ![Preview tab](/assets/images/code-canvas-v2-preview.png) The Preview tab — HTML and SVG render in place; other languages stay in the editor. ---------------- ## What's Available in Code Canvas ### Quick reference Code Canvas has its own focused composer panel, distinct from regular Chats and Compare. | Control | Available | | --- | --- | | Code editor with syntax highlighting | ✓ | | Language picker (JavaScript, TypeScript, Python, HTML, CSS, JSON, YAML, Markdown, more) | ✓ | | Live Preview (HTML and SVG only) | ✓ | | Quick Actions (6 pre-canned prompts) | ✓ | | Persona | ✓ (defaults to Ask Sage) | | Datasets | ✓ | | File / image upload | ✓ | | Voice input | ✓ (mic icon on composer) | | Prompt enhancer | ✓ (sparkle icon on composer) | | Undo / Redo | ✓ (toolbar) | | Copy / Download | ✓ (toolbar) | | Model selection per canvas (incl. Auto) | ✓ | ### What's not available in Code Canvas The composer panel is intentionally narrow. Several controls available in regular Chats are not present here. | Feature | Where to use it | | --- | --- | | Web search | Regular Chats | | Temperature slider | Regular Chats | | Plugins | Regular Chats | | MCP Tools (per-chat) | Regular Chats | | Deep Agent | Regular Chats | | Prompt Library | Regular Chats | | Code execution / runtime | An IDE or runtime environment after Copy/Download | | Version control | An external system (Git) — Canvas only has session-scoped Undo/Redo | If you need a runtime environment, version history, or extended tools, build the code in Canvas, then take it to your IDE. ---------------- ## Limits & Gotchas ### Things that bite users - **Code does not execute (mostly).** Preview renders HTML/SVG, but no JavaScript runs as logic in the preview, no Python interpreter is attached, no API calls go out. Canvas is a code authoring tool, not a sandbox. - **Undo/redo is session-scoped.** Closing the canvas, refreshing the page, or starting a new canvas wipes the history. Canvas is not version control — use Git for that. - **The language picker is for the editor's syntax highlighter.** Switching it doesn't translate the code; it just changes how the code is displayed. To actually convert between languages, use the **Convert to TypeScript** Quick Action or ask the chat directly. - **Quick Actions need code to operate on.** They're greyed out with an empty editor. Generate or paste something first. - **"Find bugs" output goes to the chat, not the editor.** The assistant explains what it found in the chat panel; the editor stays unchanged. You then decide whether to apply the fixes. - **Copy ≠ Download.** Copy puts the code in your clipboard for pasting elsewhere. Download saves it as a file with the appropriate extension for the selected language. Use Copy for quick paste into an IDE; use Download when you want a file you can commit to Git. - **Preview reflects the current editor state, not the chat conversation.** If you've manually edited the code since the last assistant response, Preview shows your edits, not the assistant's version. - **One canvas at a time.** Starting a new canvas (the `+` button or "New canvas" in the left rail) clears the current chat and editor. There's no tab system for multiple parallel canvases — open a new browser tab if you need to work on two things in parallel. ---------------- ## After You've Got Working Code ### From canvas to production Canvas is a starting point, not a deployment target. Once your code is where you want it: 1. **Verify with Preview if applicable.** For HTML/SVG, click the Preview tab and confirm the output renders as expected. 2. **Get the code out of Canvas.** Either Copy (for paste-into-IDE workflows) or Download (for file-based workflows where you'll save and commit). 3. **Run it in a real environment.** An IDE, a sandbox, your local dev machine — anywhere with the actual runtime. Canvas is a code authoring tool, not a runtime. 4. **Commit to version control.** Canvas's session-scoped undo/redo is not version history. Get your code into Git (or your team's equivalent) before you close the canvas. 5. **If you need to come back and iterate later** — start a new canvas with your code pasted in, or use a regular Chat to discuss it without the editor overhead. ---------------- ## FAQ ### Common questions #### Can I save a canvas? Not as a persistent canvas, no — Code Canvas is a working surface, not a saved document. To preserve your work, Copy or Download the code from the editor before closing the canvas. #### What languages support syntax highlighting? JavaScript, TypeScript, JSX, TSX, Python, HTML, CSS, SCSS, JSON, YAML, Markdown, and more. Open the language picker in the editor's top-left to see the full list. Languages outside the list may still display but won't be highlighted. #### Why doesn't my JavaScript run in the Preview tab? Preview renders HTML and SVG markup as a browser would render the page. Inline `