# Siesta AI Documentation Generated: 2026-08-10T11:07:52.435Z ## Contents ### Product Specification - [Introduction](#doc-intro) - [Feature Matrix](#doc-feature-matrix) - [Login](#doc-prihlaseni) - [Controls](#doc-ovladaci-prvky) - [Chat](#doc-chat) - [Workflows](#doc-workflow) - [Recordings](#doc-recordings) - [Tasks](#doc-tasks) - [Agents](#doc-agents) - [Overview](#doc-agents-overview) - [Configuration](#doc-agents-configuration) - [Interfaces](#doc-agents-interfaces) - [Prompts](#doc-agents-prompts) - [Analytics](#doc-agents-analytics) - [Evolution](#doc-agents-evolution) - [Conversations](#doc-agents-conversations) - [Feedbacks](#doc-agents-feedbacks) - [History](#doc-agents-history) - [Tools](#doc-tools) - [Skills](#doc-skills) - [Conversations](#doc-conversations) - [Data](#doc-data-collections) - [Data Upload Limits](#doc-data-collections-upload-limits) - [Choose a Data Source](#doc-data-choose-a-source) - [Manual Upload](#doc-data-manual-upload) - [Google Drive Data Source](#doc-data-google-drive) - [Microsoft 365 Data Sources](#doc-data-microsoft-365) - [Azure Storage Data Sources](#doc-data-azure-storage) - [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion) - [Jira and Confluence Data Sources](#doc-data-atlassian) - [Firecrawl Data Source](#doc-data-firecrawl) - [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) - [Connections Management](#doc-connections-management) - [Memory](#doc-memory) - [Library](#doc-templates) - [Profile](#doc-profile) - [Organization](#doc-organization) - [General](#doc-organization-general) - [Api Keys](#doc-organization-api-keys) - [Settings](#doc-organization-settings) - [Security](#doc-organization-security) - [Analytics](#doc-analytika) - [Users](#doc-users) - [Teams](#doc-teams) - [Audit log](#doc-audit-log) - [Webhooks](#doc-webhooks) - [Help](#doc-help) - [Chrome Extension](#doc-chrome-extension) - [MacOS App](#doc-desktop-apps-macos) - [Windows App](#doc-desktop-apps-windows) - [Mobile App](#doc-mobile-app) - [Admin Guide](#doc-admin-guide-index) - [Plan Your Organization Setup](#doc-admin-guide-plan-organization-setup) - [Create Teams and Assign Users](#doc-admin-guide-create-teams-and-assign-users) - [Configure Shared and Private Connections](#doc-admin-guide-configure-shared-and-private-connections) - [Govern Data Collections and Sources](#doc-admin-guide-govern-data-collections-and-sources) - [Set Up Tools, APIs, and MCP Access](#doc-admin-guide-set-up-tools-apis-and-mcp-access) - [Define Access Policies and Visibility Rules](#doc-admin-guide-define-access-policies-and-visibility-rules) - [Prepare Agents and Workflows for Teams](#doc-admin-guide-prepare-agents-and-workflows-for-teams) - [Monitor Usage, Audit Logs, and Risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk) - [Review Tool Executions](#doc-admin-guide-review-tool-executions) - [Organizational AI Readiness](#doc-admin-guide-adoption-and-rollout-organizational-ai-readiness) - [Setting Realistic AI Expectations](#doc-admin-guide-adoption-and-rollout-setting-realistic-ai-expectations) - [Finding AI Initiative Candidates](#doc-admin-guide-adoption-and-rollout-finding-ai-initiative-candidates) - [Prioritizing AI Initiatives](#doc-admin-guide-adoption-and-rollout-prioritizing-ai-initiatives) - [Initiative Lifecycle and Governance](#doc-admin-guide-adoption-and-rollout-initiative-lifecycle-and-governance) - [Enterprise Kick-off](#doc-admin-guide-adoption-and-rollout-enterprise-kick-off) - [Rollout Roles and Delivery Cadence](#doc-admin-guide-adoption-and-rollout-rollout-roles-and-delivery-cadence) - [Deployment Reporting and Monthly Operations Review](#doc-admin-guide-adoption-and-rollout-deployment-reporting-and-monthly-operations-review) - [Security and Governance](#doc-security-and-governance-index) - [AI Threat Model](#doc-security-and-governance-ai-threat-model) - [Prompt Injection](#doc-security-and-governance-prompt-injection) - [Tool Governance](#doc-security-and-governance-tool-governance) - [Data Access and RAG](#doc-security-and-governance-data-access-and-rag) - [Human Approval](#doc-security-and-governance-human-approval) - [AI Auditability](#doc-security-and-governance-auditability) - [AI Incident Response](#doc-security-and-governance-incident-response) - [Layered Security Architecture](#doc-security-and-governance-layered-security-architecture) - [AI Safety and Quality](#doc-security-and-governance-ai-safety) - [Model Governance](#doc-security-and-governance-model-governance) - [Model Deployment and Data Residency](#doc-security-and-governance-model-deployment-and-data-residency) - [EU AI Act Readiness](#doc-security-and-governance-eu-ai-act-readiness) - [AI Go-Live Checklist](#doc-security-and-governance-ai-go-live-checklist) - [Deployment and Operations](#doc-deployment-and-operations-index) - [Deployment Models](#doc-deployment-and-operations-deployment-models) - [Azure Deployment Guide](#doc-deployment-and-operations-azure-deployment) - [Reference Architecture](#doc-deployment-and-operations-reference-architecture) - [Runtime Services](#doc-deployment-and-operations-runtime-services) - [Network Security](#doc-deployment-and-operations-network-security) - [Identity and Access](#doc-deployment-and-operations-identity-and-access) - [Secrets and Configuration](#doc-deployment-and-operations-secrets-and-configuration) - [Observability](#doc-deployment-and-operations-observability) - [Firewall and Egress](#doc-deployment-and-operations-firewall-and-egress) - [Infrastructure as Code](#doc-deployment-and-operations-infrastructure-as-code) - [Deployment Lifecycle](#doc-deployment-and-operations-deployment-lifecycle) - [Rollout and Handover](#doc-deployment-and-operations-rollout-and-handover) - [Open-Source Licenses](#doc-deployment-and-operations-open-source-licenses) - [User Guide](#doc-user-guide-index) - [Get Started with Siesta AI](#doc-user-guide-get-started-with-siesta-ai) - [Choose Tasks AI Can Do Well](#doc-user-guide-ai-working-practices-choose-tasks-ai-can-do-well) - [Recognize Tasks AI Should Not Own](#doc-user-guide-ai-working-practices-recognize-tasks-ai-should-not-own) - [Write Better AI Prompts](#doc-user-guide-ai-working-practices-write-better-ai-prompts) - [The Five-Part Business Prompt](#doc-user-guide-ai-working-practices-five-part-business-prompt) - [Improve and Review Prompts](#doc-user-guide-ai-working-practices-improve-and-review-prompts) - [Enterprise AI Use-Case Patterns](#doc-user-guide-ai-working-practices-enterprise-ai-use-case-patterns) - [Ask in Chat Effectively](#doc-user-guide-use-chat-effectively) - [Choose and Use Agents](#doc-user-guide-work-with-agents) - [Use Tasks to Track Work](#doc-user-guide-use-tasks-to-track-work) - [Use Connections Safely](#doc-user-guide-use-connections-safely) - [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) - [Repeat Work With Workflows](#doc-user-guide-create-useful-workflows) - [Use the Library](#doc-user-guide-use-templates) - [Continue Past Work](#doc-user-guide-use-recordings-and-conversations) - [Save Reusable Context](#doc-user-guide-manage-memory-and-context) - [Troubleshoot Common Problems](#doc-user-guide-fix-common-problems) - [Release Notes](#doc-releases) - [User Manual](#doc-user-manual) - [Build With Siesta AI](#doc-developers-index) - [REST API Reference](#doc-developers-rest-api) - [Getting Started](#doc-developers-rest-api-getting-started) - [Realtime API](#doc-developers-realtime-api) - [MCP](#doc-developers-mcp) - [Documentation MCP](#doc-developers-docs-mcp) - [Connections](#doc-connections) - [Web Plugin](#doc-developers-web-plugin) - [Playground](#doc-developers-web-plugin-playground) - [Roles](#doc-roles) - [Security](#doc-security) ### Connections - [OpenAI](#doc-connections-openai) - [Azure AI Foundry](#doc-connections-azure-ai-foundry-index) - [Model Router](#doc-connections-azure-ai-foundry-model-router) - [Increase of Azure AI Foundry Quota](#doc-connections-azure-ai-foundry-need-to-increase-ai-foundry-quota) - [Gemini](#doc-connections-gemini) - [Custom LLM](#doc-connections-custom-llm) - [MCP](#doc-connections-mcp) - [Rest API](#doc-connections-rest-api) - [Airtable](#doc-connections-airtable) - [Azure (Coming Soon)](#doc-connections-azure) - [Azure DevOps](#doc-connections-azure-devops) - [Azure Storage Account](#doc-connections-azure-storage-account) - [Clockify](#doc-connections-clockify) - [Confluence](#doc-connections-confluence) - [Email](#doc-connections-email) - [Firecrawl](#doc-connections-firecrawl) - [GitHub](#doc-connections-github) - [Gmail](#doc-connections-gmail) - [Google Ads](#doc-connections-google-ads) - [Google Analytics](#doc-connections-google-analytics) - [Google Calendar](#doc-connections-google-calendar) - [Google Docs](#doc-connections-google-docs) - [Google Drive](#doc-connections-google-drive) - [Google PageSpeed](#doc-connections-google-pagespeed) - [Google Search API](#doc-connections-google-search) - [Google Search Console](#doc-connections-google-search-console) - [Google Sheets](#doc-connections-google-sheets) - [Google Tag Manager](#doc-connections-google-tag-manager) - [Google Trends](#doc-connections-google-trends) - [HubSpot](#doc-connections-hubspot) - [Jira](#doc-connections-jira) - [LinkedIn](#doc-connections-linkedin) - [Microsoft Fabric](#doc-connections-microsoft-fabric) - [Microsoft Outlook](#doc-connections-microsoft-outlook) - [Money S3](#doc-connections-money-s3) - [Office 365 Excel](#doc-connections-office365-excel) - [Office 365 Word](#doc-connections-office365-word) - [OneDrive](#doc-connections-one-drive) - [Power BI](#doc-connections-power-bi) - [Seznam Sklik](#doc-connections-seznam-sklik) - [SharePoint](#doc-connections-sharepoint) - [Shopify](#doc-connections-shopify) - [Shoptet](#doc-connections-shoptet) - [Slack](#doc-connections-slack) ### Release Notes - [Release 1.2.6](#doc-releases-1-2-6) - [Release 1.2.5](#doc-releases-1-2-5) - [Release 1.2.4](#doc-releases-1-2-4) - [Release 1.2.3](#doc-releases-1-2-3) - [Release 1.2.2](#doc-releases-1-2-2) - [Release 1.2.1](#doc-releases-1-2-1) - [Release 1.2.0](#doc-releases-1-2-0) - [Release 1.1.12](#doc-releases-1-1-12) --- # Introduction import NavCardGrid from '@site/src/components/NavCardGrid'; import {MessageSquare, Workflow, Mic, ListChecks, Bot, Sparkles, Brain, Cable, Database, Library, Building2, Users, UsersRound, ScrollText, LineChart, Smartphone, Monitor, Puzzle} from 'lucide-react'; import {WindowsLogo, AppleLogo} from '@site/src/components/BrandIcons'; # Siesta AI Platform Siesta AI is an enterprise platform for building secure, model-independent AI agents on top of your own knowledge and tools. Connect internal documents, databases, and external services like calendars, email, and CRM, then let agents answer questions, take actions, and automate work while every response stays grounded in data you control. Any LLM works, whether in the cloud or on your own servers, so you decide where and how your data flows. Built-in analytics, feedback, and audit logs keep agent behavior measurable and accountable. ## Work The everyday surfaces where people get work done with Siesta AI. ## AI The building blocks you configure once and reuse across the platform. ## System Administer your tenant, the people in it, and the accountability trail behind every change. ## Apps & Extensions Use Siesta AI wherever you work, beyond a single browser tab. ## Getting started New to Siesta AI? Start with [Login](#doc-prihlaseni) and [Controls](#doc-ovladaci-prvky), then browse the [Feature Matrix](#doc-feature-matrix) for a full map of what the platform can do. --- *The documentation is continuously updated. For the latest information, please contact us at info@siesta.ai.* --- # Feature Matrix This matrix summarizes the main Siesta AI product modules from a product specification perspective. It is intended as a quick orientation layer before reading the detailed feature pages.
| Module | Availability | Primary Roles | Main Use Case | Dependencies | Known Limitations | | :--- | :--- | :--- | :--- | :--- | :--- | | Agents | Core | Admins, agent owners | Create and manage AI agents with instructions, models, data, tools, access, templates, analytics, and history. | Model connection, optional data collections, optional tools, access policies. | Agent quality depends on configuration, data quality, model choice, and tool governance. | | Chat | Core | Users, admins | Interact with configured agents, attach files, provide feedback, and review conversation history. | At least one available agent. | Access and available agents depend on user role and sharing policies. | | Public Chat | Configurable | Admins, external visitors | Expose an agent through a public URL for unauthenticated users. | Agent interface settings, tenant public chat setting, optional privacy link. | Should not be enabled for sensitive scenarios without reviewing security, safety, and data exposure. | | Widget | Configurable | Admins, website visitors | Embed an agent into an external website or portal. | Agent interface settings, embed configuration, optional OAuth client. | Public widget behavior depends on public chat and authenticated widget configuration. | | Realtime | Configurable | Users, external app users | Run interactive voice or realtime sessions with an agent over WebSocket. | Realtime-enabled model, conversation, realtime session, supported audio format. | Sessions expire, have idle and duration limits, and currently use supported formats such as `pcm16`. | | Workflows | Beta | Admins, process owners | Compose multi-step automation using triggers, tools, agents, conditions, and history. | Connections, tools, access policies, optional webhooks. | Workflow behavior depends on external service reliability, permissions, and node configuration. | | Tasks | Beta | Users, teams, admins | Track work created from conversations, agents, or integrations and process it with an assigned/default agent. | Task workspace, optional source conversation, optional assigned agent. | Auto-execution and workspace behavior should be validated before high-volume integrations. | | Desktop Apps | Configurable | Users, teams, technical operators | Use native Windows and macOS clients for audio capture, screen recording, Wisps dictation, recordings review, chat, and task-driven local productivity flows. | User desktop install, supported OS permissions, organization sign-in, optional trusted local tools. | Desktop value depends on local permissions, supported OS behavior, and whether the workflow needs native capture or trusted local execution. | | Skills | Core | Admins, agent owners | Define reusable abilities, instructions, and tool bindings that can be assigned to agents. | Available tools/functions, agent configuration. | Poorly scoped skills can make agent behavior less predictable. | | Memory | Core | Admins, agent owners | Maintain long-term organization knowledge pages and collections for agent context. | Memory collections/pages, agent assignment. | Must be curated and attached intentionally to avoid irrelevant context. | | Data | Core | Admins, knowledge owners | Create data collections from files and integrations, process documents, inspect chunks, and attach sources to agents. | Source content, provider connections, parsing/indexing pipeline. | Failed sync, unreadable documents, empty chunks, or strict retrieval settings can reduce answer quality. | | Connections | Core | Admins, integration owners | Manage model connections, external tools, credentials, shared/private access, governance, and token limits. | Provider credentials, OAuth/API keys, organization policies. | External service permissions, rate limits, and governance settings affect availability. | | External API | Configurable | Developers, integration owners | Let external systems call Siesta AI agents, files, tasks, workspaces, connections, data collections, and audit logs. | API key, organization ID, target resources. | API keys must be protected server-side; realtime requires WebSocket client support. | | Security | Core | Owners, admins | Manage tenant-wide sharing, profile editing, retention, prompt shield, content safety, and connection governance. | Organization settings, roles, access policies. | Disabling public or unsafe behavior can intentionally block previously available actions. | | Analytics | Core | Admins, managers | Review usage, costs, recordings, workflows, data activity, and agent performance. | Conversation, token, recording, workflow, and feedback data. | Analytics are historical and should be paired with limits/governance for prevention. | | Billing | Configurable | Owners, admins | Manage subscription plan, billing sessions, pricing, and usage visibility. | Billing provider configuration and organization subscription state. | Billing availability depends on configured payment provider and plan. | | Audit Logs | Core | Admins, compliance reviewers | Review administrative and system changes, including who changed what and when. | Audit logging and retention settings. | Available history depends on configured audit log retention. |
## Reading Order Start with [Agents](#doc-agents), [Chat](#doc-chat), [Connections](#doc-connections), and [Data](#doc-data-collections) for the core platform model. Then review [Desktop Apps](#doc-desktop-apps-windows), [Organization](#doc-organization), [Tool Executions](/tool-executions), and [REST API](#doc-developers-rest-api-getting-started) for operational surfaces and enterprise integration behavior. --- # Login ## Registering a New Account To create a new account, please fill in: - **Name** and **Surname** - **E-mail** - **Password** and **Confirm Password** Confirm your agreement with the terms, optionally decline marketing, and click on **Continue with Company Email**. Alternatively, you can use login via Google or Microsoft. ![Registration Screen](/img/login/registrace.png) ## Logging into the Application To log into the platform, enter: - **E-mail** - **Password** (can be shown/hidden using the eye icon) Then click the **Login** button, which will verify your details and log you into the system. On the login screen, the following options are available: ### Remember Me By checking this, you will remain logged in even after closing the browser. ### Password Recovery Link The link will open a form for password recovery if you do not remember your password. ### Create a New Account If you do not have an account yet, go to registration and create your access. ### One-Click Login - **Continue with Google** - **Continue with Microsoft** > If the login fails, an error message will appear regarding invalid or missing details. ![Current Login Screen](/img/login/login.png) ## Resetting a Forgotten Password In case you forget your password, you can reset it. Enter the email associated with your account, and after submission, you will receive an email with a unique link to set a new password. ![Password Reset Screen](/img/login/forgot-password.png) ## Update Password After opening the unique link from the email, fill in: - **New Password** - **Confirm New Password** By clicking the **update password** button, you will save the new password. --- # Controls The current appearance of the application screen after logging in. ## Left Panel - Main section with items: Chat, Workflows (label Beta), Recordings (label Beta), Analytics (Admin). - AI section: Agents, Conversations (Admin), Data, Connections, Library. - Settings section: Profile, Organization (Admin), Users (Admin), Teams, Audit log (Admin), Security, Webhooks. - A red badge with the number of active recommendations may appear next to the Security item. - Support section: Help. - At the bottom, the user card; when clicked, a menu appears with options: Switch to dark mode (crescent moon icon), language selection "English" with code "us", and the item Log out. Example of the main navigation in the left panel. ![Left panel with Security](/img/controls/left-panel-sidebar-security.png) Example of the user menu at the bottom of the panel. ![User menu table](/img/controls/left-table-user%20table-en.png) ## Dashboard The Dashboard provides a team-level overview of the most important activity in the platform. It serves as a quick entry point for checking agents, workflow runs, tasks, data sources, memory, recordings, skills, and connections. ![Team dashboard overview](/img/dashboard/team-dashboard.jpg) ### Team Selection Dashboard is tied to a team. At the top of the page, select the team whose data should be shown. If the user has no available team, the page shows an empty state. If the selected team has too little data, individual cards show an empty state instead of a table. ### Overview Cards Dashboard consists of several cards: - **Agents** - overview of agents available for the selected team. - **Recent tasks** - latest tasks in team workspaces. - **Recent memory changes** - latest changes in memory collections. - **Recent workflow runs** - latest workflow executions. - **Data sources** - overview of sources connected to the team. - **Recent recordings** - latest recordings. - **Skills** - available skills. - **Connections** - available integrations. ## Entity Sharing - For the entities Workflows, Agents, and Data, you can toggle visibility between Private and Shared in the Access section. - In Organization Access, you set the default permissions for the entire organization. - Sharing can be set for both Teams and individual users. - For each added team or user, you can choose permissions Can Use or Can Edit and revoke access at any time. ![Access and sharing configuration](/img/controls/sharing-access-teams-users.png) ## Conversation List - Header "Chat" and search field "Search" with a filter icon. - Names of conversations, the name of the agent used, on the right the date of the last message and a menu where conversations can be renamed or deleted. - The active row is highlighted. - At the bottom, you will find pagination "Page 1 of 30" with arrows. ![Conversation list](/img/controls/chat-list-en.png) ## Input Field - Title "How can I help?" with an agent icon. - Below the title, a set of suggestions (chips) with questions in Czech, e.g., "What is the biggest bottleneck in modern web applications?", "What technologies are currently shaping the development world?", "Why is the market rising or falling today?". - Input field with a placeholder "You can start typing", on the left a "+" button to add content. - On the right inside the field, agent selection "Chat Bot" with an avatar and a dropdown arrow, next to it an icon for the microphone and send (up arrow). ![Input field and agent selection](/img/controls/chat-input-agent-en.png) --- # Chat The Chat section is used for conversations with AI agents that are created and configured in the Agents section of the platform. Users can start new conversations, browse the history of previous chats, use prompt suggestions, upload supporting files, and provide feedback on responses. ## Chat Input and File Uploads The chat input supports both written instructions and attached context. Users can type a message, upload files from the attachment button, or drag and drop files directly into the chat area. This is useful when the agent should work with a document, spreadsheet, image, exported report, screenshot, or another file that is not already available through Data, Memory, or a connected system. When attaching files, describe what the agent should do with them. For example, ask the agent to summarize a PDF, compare two documents, extract action items from meeting notes, read a screenshot, or analyze a spreadsheet. Clear instructions help the agent focus on the right parts of the uploaded content. If the selected agent has **Code interpreter** enabled, it can perform more advanced file work, such as inspecting spreadsheets, transforming tabular data, cleaning CSV exports, generating charts, or creating downloadable output files. This makes chat suitable for lightweight analysis and file preparation without leaving the conversation. For sensitive or business-critical files, users should still verify the result before using it externally. ## Starting a New Conversation A new chat is automatically opened when the Chat tab is opened. Alternatively, if the user has an existing chat open, there is a **New Chat** button in the top right corner. At the start of a conversation, the chat shows the selected agent, the message composer, available input actions, and any prompt suggestions prepared for the user. Prompt suggestions work as reusable starting points: the user can click one instead of writing the first instruction from scratch, then adjust the text before sending it. The composer supports typed instructions, file attachments, drag-and-drop uploads, voice input, agent selection, and message sending. This gives the user one place to ask a question, provide context, upload supporting material, and choose the agent that should handle the request. When realtime voice is available for the selected agent, users can start from an already open conversation or directly from the empty-state composer before the first text message is sent. ![Chat prompt suggestions](/img/chat/chat-prompt-suggestions.png) By sending the first message, the chat is initialized, and the newly created chat appears on the right in the conversation list, where it can be renamed. ## Chat Interface The main screen is divided into two parts: - **on the left**, the history of all conversations is displayed (including the title, the agent used, and the date), - **on the right**, the actual communication with the selected agent takes place. ![Chat interface with conversation history and active chat](/img/chat/chat-prompt-suggestions.png) The user types their queries into the input field at the bottom of the screen and sends them by pressing the **Send** button. There is also an option to activate voice input, attach files, or drag and drop files into the conversation. The agent responds in real-time, with each message being stored within the given conversation. Public chat, widget embedding, authenticated widget mode, privacy links, and public realtime access are configured on the agent itself. See [Agents > Interfaces](#doc-agents-interfaces) for those settings. ### Filtering and Managing Conversations - The left panel allows for quick browsing of the history, including titles and the date of the last activity. - By clicking on **…** next to a conversation, you can quickly **rename** or **delete** the chat. - Filters (icon in the top panel of the list) allow filtering conversations by a specific agent. The filter for the selected agent can be removed by clicking on the trash icon and confirming the change with the **Send** button. ![Agent Filters](/img/chat/filters.png) ### Submitting a Query - The input field supports text, attachments, and voice dictation (microphone). - Submitting a query: arrow or keyboard shortcut **Enter** / **Cmd + Enter** (depending on settings). ![Input Field and Agent Switch](/img/chat/recording-en.png) The microphone status (active/disabled) is visible right next to the agent selection. When recording, an icon is activated, and the status is displayed in the input field. ## Realtime and Voice Conversations Siesta AI supports realtime conversation flows for interactive voice-style experiences. A realtime session is always connected to a specific conversation, so messages, transcripts, tool activity, feedback, and audit context remain tied to the same conversation history as standard chat. Realtime can be used in two contexts: - **Internal chat**: authenticated users start a realtime session from an existing or newly created conversation. - **Public chat**: public or embedded chat can use realtime only when public chat and realtime public access are enabled for the organization and agent. The realtime flow has two steps: 1. The client creates a `realtime-session` for the conversation. 2. The client connects to the returned WebSocket path and streams audio/events for that session. In the UI, realtime controls can expose: - a voice start action directly in the composer, - a stop action that lets the user end the active realtime turn without leaving the conversation, - persona or voice selection controls, - audio activity indicators, - approval waiting state when a tool call must be confirmed before the session can continue. Session behavior is controlled by platform limits. The current backend defaults include a short session token lifetime, an idle timeout of 60 seconds, a maximum session duration of 1,800 seconds, up to 2 concurrent sessions per user, and up to 100 concurrent sessions per organization. The supported input and output audio format is `pcm16`, and the default supported voice is `alloy`. If the session expires, becomes idle, exceeds the maximum duration, or violates origin/security checks, the client should create a new session before reconnecting. Realtime sessions remain tied to the same conversation, so transcripts, tool events, and persisted messages stay in the conversation history instead of being stored separately. For public chat and widgets, administrators should review public chat settings, allowed origins, content safety, prompt shield settings, and privacy disclosures before enabling realtime for customer-facing use. ## Feedback on Responses Under each agent response, it is possible to copy the response or click on the thumbs up or down icon, allowing the user to provide quick feedback on the agent's response. After submitting a rating, a **Send feedback** window will also appear, where a specific comment on the agent's response can be added. This feedback is automatically sent to the admin interface upon submission. This mechanism allows administrators to monitor the quality of responses, analyze strengths and weaknesses in the underlying data, and subsequently optimize agent settings. ## Sharing a Conversation The chat can be shared via a link. In the conversation detail, click on **Share** and choose who can open the link. The preview shows the content of the shared chat, including the latest messages and the prompt that initiated the conversation. If the shared conversation contains generated artifacts or realtime messages, verify the preview before sending the link so the recipient sees the intended final state. ![Chat Sharing Dialog](/img/chat/share-link-cz.png) ## HTML and Rich Content Preview Some agent or tool outputs can contain HTML-like content. Current dev chat behavior is safer than a plain raw render: - the chat can show a preview-oriented rendering path for supported content, - code-style fallback is still used when the content should not be rendered directly, - users should still verify the preview before sharing or copying output into an external system. --- # Workflows Workflows allow you to compose integration flows from pre-defined actions (HubSpot, Jira, Google Workspace, and others), and the orchestration is then triggered by agents or directly by users. This section is currently in beta mode. ## Where to find them - In the left menu, click on **Workflows (Beta)**. - A list of existing workflows will appear, along with search, pagination, and a button **Create workflows**. An empty list displays the text **No results**. ![List of workflows – empty state](/img/workflows/workflows-create.png) ## Creating a new workflow 1. Click on **Create workflows**. 2. In the right panel, fill in the **Name** and **Description** – these are also used for searching. 3. Drag actions from the left panel **Connections** onto the canvas (e.g., HubSpot, Jira, Google Calendar, Google Drive). 4. Connect the nodes by dragging lines – the output of the previous action is the input of the next. 5. In the node settings, fill in the parameters (record IDs, emails, calendars, projects, etc.). 6. Save by clicking on **Save workflows**. 7. Zoom controls are at the bottom left, mini-map at the bottom right. Empty canvas with the first trigger: ![Empty canvas with webhook](/img/workflows/workflow-webhook.png) Adding a node from the catalog: ![Node selection (Triggers/Tools/Agents)](/img/workflows/workflows-tools.png) ## Node Catalog The workflow builder groups available nodes into four catalog tabs: - **Triggers**: entry points that start a workflow, such as Webhook, Schedule, or Recording transcribed. - **Tools**: connection-backed functions from enabled connections and their tool functions. - **Agents**: assistant nodes that send input to a selected agent and return the assistant result. - **Operators**: system flow-control nodes that shape how data moves through the workflow. Organization settings affect what appears in the catalog. For example, Webhook nodes require the Webhooks organization feature, Recording transcribed requires Recordings, and Tools depend on connection availability and governance. ![Workflow operators catalog](/img/workflows/workflow-operators.png) ## System Operators Operators are built-in workflow nodes. They are not external connections and do not require credentials. Use them when the workflow needs to repeat work, collect results, or route around failures. | Operator | Output fields | What it does | | --- | --- | --- | | **Iterator** | `item`, `index` | Splits a collection or configured values into separate branches. Each item gets its own run path, and downstream nodes run once per item. | | **Aggregator** | `result`, `count` | Collects values produced inside iterator branches and returns one combined result after the repeated work is complete. | ### Iterator Use **Iterator** when one workflow step returns or receives multiple items and the next steps should run once per item. Inside each iteration: - `item` contains the current item value, - `index` contains the zero-based position of the item, - downstream steps are isolated for that iteration, - edge conditions are evaluated per item before the next node is queued. Typical use cases: - process every row returned by a data lookup, - create one ticket per matching record, - send one notification per item, - call an agent once for each item in a list. ### Aggregator Use **Aggregator** after an Iterator when the workflow needs to collect per-item results back into one output. Aggregator settings define which values are collected from upstream node output. When all iteration branches are complete, the Aggregator emits: - `result`: the aggregated collection, - `count`: the number of aggregated items. Use Aggregator when later workflow steps need a combined summary, a single payload, or one final assistant/tool call after all items have been processed. ### Error Handler Use **Error handler** when a workflow needs a dedicated path for failed node execution. The released backend supports error-edge routing into an Error handler node so the workflow can record, skip, or commit a controlled failure outcome instead of stopping without context. Use it when: - one branch should continue even if an upstream tool call fails, - the workflow should emit a handled error status instead of a silent stop, - operators want a reviewable fallback path for risky external actions. Even with Error handler available, still combine it with: - clear edge conditions, - tool approval and confirmation settings, - workflow run history, - node runs, Tool Executions, and Audit Log diagnostics. ### Edge settings (Conditions) You can open **Edge settings** on the lines between nodes. In this section, you set **conditions** that determine when the workflow should take a specific branch. Configurable items: - **Label** for naming the branch. - One or more rules in the **Condition** section. - **Operator** (e.g., `Text equals`) and comparison value. - **Add rule** to add another condition. ![Edge settings - conditions](/img/workflows/workflow-edge-settings-conditions.png) ### Typical actions and examples - **HubSpot**: GetDealById, GetContactById – reading a deal/contact before passing it to other systems. - **Jira**: GetUserAsync, AssignTicketAsync, CreateTicketAsync – enriching a contact or creating a ticket. - **Google Calendar**: CreateEventAsync – creating a meeting after successful data enrichment. - **Google Drive**: ListFilesAsync, ReadFileAsync – working with documents. - **LLM / Webhook**: calling a model or webhook to supplement logic, validation, or notification. You can find the procedure for creating a webhook on the [Webhooks](#doc-webhooks) page. ### Best practices - **Input validation**: verify IDs, emails, and required parameters before connecting additional nodes. - **API errors**: account for errors from integration services (timeout, rate limit) and add a fallback. - **Naming**: name nodes according to their function (e.g., “Find HubSpot Contact”, “Create Jira Ticket”). - **Security**: work only with access rights that are necessary for the given workflow; keep sensitive values in a vault/secrets. ## Editing and management - In the list of workflows, search for the name/keyword and open the item. - You can edit, save, and rerun the workflow – changes will take effect in new runs. - Recommended: after significant changes, test the flow on non-production data (test deals/tickets/calendar). ## Workflow Detail Opening a workflow takes you to its detail page at `/internal/workflows/[workflowId]`. The detail page is where you review the workflow canvas, edit nodes, test changes, and inspect how the workflow is configured. Use the detail page to: - review the trigger and connected actions, - inspect node inputs and outputs, - update node parameters, - adjust edge conditions, - check access and sharing, - run or rerun the workflow when the workflow is ready to test, - save changes before users or agents rely on the updated version. When diagnosing a workflow, start from the trigger, then follow each node in order. Check whether required inputs are present before looking at later nodes, because a missing ID, email, file, or token at the beginning often causes downstream errors. ## Running and Testing Run workflows with test data before sharing them broadly. This is especially important when a workflow writes to external systems such as Jira, HubSpot, Google Calendar, or email. Recommended testing flow: 1. Use a non-production record or test account. 2. Run the workflow once with the smallest possible input. 3. Verify every external side effect in the target system. 4. Check tool executions and logs if a node fails. 5. Only then share the workflow with a team or connect it to an agent. ### Change history In the right panel **History**, you can view previous changes to the workflow (added/moved nodes, initial state) and revert to earlier versions. ![Workflow history](/img/workflows/workflow-history-panel.png) ### Sharing workflow In the **Access / Sharing** section, you can set: - **Visibility** (`Private` / `Shared`), - **Organization Access** (e.g., `Can Use`), - **Team Access** to add specific teams. This determines who can use or manage the workflow within the organization. ![Workflow sharing access](/img/workflows/workflow-sharing-access.png) ## Diagnostics When a workflow does not behave as expected, check: - **Node configuration**: required parameters, IDs, email addresses, calendar IDs, project keys, and field mappings. - **Edge conditions**: whether a condition is too strict or points to the wrong branch. - **Connection access**: whether the workflow has access to the connection and function it needs. - **External API result**: whether the target service returned an error, rate limit, permission issue, or validation error. - **Tool Executions**: whether the underlying tool call is pending, failed, or waiting for approval. - **Audit Log**: whether a recent configuration or access change affected the workflow. If a workflow changed recently, compare the current version with the History panel before editing again. ## Common scenarios - **Sync HubSpot → Jira → Calendar**: obtaining a deal and contact, finding a user in Jira, creating a ticket and meeting. - **Incident intake**: creating a ticket, attaching files from Drive, and notifying via webhook/LLM. - **Onboarding**: creating a user in internal systems, adding to groups, and scheduling an introductory meeting. Sample workflows: ![Sample workflows with HubSpot and Outlook](/img/workflows/workflows-sample.png) --- # Recordings The Recordings module serves to record, store, manage, and automatically transcribe audio content in the Siesta AI application. Each recording is processed by AI upon insertion, and a text transcript is created, which can be further used in agents, workflows, or analytics. The section includes: - Overview of all recordings in a table - Recording detail with a player and transcript - Dialog for adding a new recording ## Overview of Recordings The main screen displays a list of recordings in a table with the following columns: - **Title** – The title of the recording entered by the user - **Created** – Date and time of creation - **Type** – Type of recording (e.g., mobile app, call) - **Media type** – The technical file/media type detected for the uploaded or recorded file - **Duration** – Total length of the audio recording - **Status** – Current processing status: - Queued – waiting for processing - Processing – transcription in progress - Completed – transcription is finished - **Actions** – Additional operations (e.g., detail, delete) Recordings can be searched using the search field. The **Add Recording** button is used to insert a new recording. ![Overview of Recordings](/img/recordings/recordings-overview.png) ## Adding a New Recording After clicking on **Add Recording**, a dialog opens with the following fields: **Fields** - **Recording Title** – Required field for entering the title. - **Type** – Dropdown list to specify the type of recording (e.g., Call). - **Media type** – derived from the uploaded file or browser recording format and shown later in list/detail views. - **Upload File or Record** – Options: - **Upload File** – Dragging a file or clicking to select from the computer - **Start Voice Recording** – Recording sound directly from the microphone **Actions** - **Cancel** – Closes the dialog without saving - **Add Recording** – Saves the recording and starts processing ![Dialog for Adding a Recording](/img/recordings/recordings-add-dialog.png) ## Recording Detail Each recording has its own detail page at `/internal/recordings/[id]`. The detail page includes: - **Player** - Playback controls (Play / Pause) - Playback progress slider - Volume control - Display of duration and current position - **Metadata** - Title - Created (date and time) - Duration - Type - Media type - Status - **Transcript** – Text transcript of the audio recording generated by AI. Once processing is complete, the transcript is displayed on the right side of the screen. ![Recording Detail](/img/recordings/recordings-detail.png) ## Processing States Each recording goes through the following steps: - **Uploaded** – file has been received - **Queued** – waiting for processing - **Processing** – transcription in progress - **Completed** – transcription is finished and available - **Failed** – transcription or processing did not complete successfully If a recording remains queued or processing for longer than expected, refresh the detail page and check whether the source file is valid audio. If the status is failed, upload the file again or use a shorter test recording to confirm whether the issue is file-specific. ## Transcript The transcript appears after processing is complete. Use it to: - review what was said in the recording, - copy relevant notes into a task, memory page, or workflow input, - verify whether names, dates, and technical terms were transcribed correctly, - decide whether the recording should be shared or used as source material. For long recordings, scan the transcript first, then replay the audio only around the section that needs verification. ## Sharing If recording sharing is enabled by organization security settings, the recording detail can expose sharing controls. Use sharing when someone outside the immediate workspace needs to review the recording or transcript. Before sharing: - confirm that the recording does not contain sensitive information, - check whether public recording sharing is allowed in Organization Security, - use the share link only for the intended audience, - revoke or avoid sharing when the recording includes confidential content. ## Typical Uses The Recordings section is suitable for: - Recording meetings - Capturing interactions from mobile applications - Transcribing calls or interviews - Creating data for AI agents and workflows - Archiving voice notes - Distinguishing between the business recording type and the underlying uploaded media type during troubleshooting --- # Tasks The **Tasks** section is used to review and manage tasks created from conversations or follow-up agentic processes. Users can browse tasks, filter them by status, open task details, and run them with a selected agent. Tasks are organized by **Task workspace**. The workspace determines which set of tasks the user is working with and which default agent is used to process them. ## Task Workspaces A task workspace is the operating context for a group of tasks. It can represent a personal queue, team queue, process queue, or integration-specific queue. A workspace can define: - name, - owner, - default agent, - auto-execution setting, - access policy, - audit and soft-delete history. ![Task workspace selection](/img/tasks/task-workspace-menu.png) When a task does not explicitly choose an agent, the workspace default agent can be used as the expected processing agent. If auto-execution is enabled, the workspace can be used for more automated task intake patterns where tasks are intended to move into agent processing with less manual setup. Use the edit action in the workspace menu to change the default agent, enable or disable auto-execution, and adjust workspace visibility. ![Task workspace settings](/img/tasks/task-workspace-edit.png) ## Task Overview At the top of the page you will find: - workspace selection, - search, - source agent filter, - status filter, - **Table / Kanban** view switch. The table primarily shows: - task **summary**, - source agent, - **status**, - creation date, - actions for opening the detail, related conversation, source conversation, or deleting the task. ![Task overview](/img/tasks/tasks-overview.png) ## Task Statuses A task can be in one of these statuses: - **Todo** - the task is waiting to be processed. - **In progress** - the task is being worked on. - **Review** - the output is waiting for review. - **Done** - the task is complete. In table view, set the status in the task detail. In kanban view, move tasks between columns to change their status. ## Detail and Run Click the task title to open the **Task detail** side panel. In the detail, you can edit: - **summary**, - **status**, - **prompt**, - the agent that should process the task. The **Run** or **Execute** button sends the prompt to the selected agent. If the task already has a follow-up conversation, the detail offers a link to the latest task conversation. If the task was created from another conversation, you can also open the source conversation. ![Task detail](/img/tasks/task-detail.png) Current task flows are designed to keep the handoff between chat and task execution tight. When a task is created from chat, the detail should make it easy to jump back to the original conversation and forward to the latest task-run conversation without losing context. ## Task Lifecycle Tasks can be created manually, from a conversation, by an agentic process, or through the [REST API](#doc-developers-rest-api-getting-started). A task can keep references to: - the workspace where it belongs, - the assigned agent that should process it, - the source agent that created or suggested it, - the source conversation that contains the original context, - the follow-up conversation created when the task is run. This makes tasks useful for handoff: a user can identify work in chat, turn it into a task, run the task with an agent, and later inspect both the original context and the task-specific conversation. ## Kanban View Kanban view is intended for quickly working with task status. Cards can be filtered by search and source agent. Dragging a card between columns changes the task status. ![Task kanban view](/img/tasks/tasks-kanban-view.png) To remove a task, use the **Delete** action or drag the card into the delete zone if it is available in kanban view. Both table and kanban views can contain enough records to require pagination or repeated filtering. If a task seems to disappear after a search or status change, first clear filters and return to the expected workspace before assuming the task was deleted. ## Recommended Use - Use workspaces to separate personal, team, or process tasks. - Keep summaries short and prompts specific so the agent receives a clear assignment. - Use **Review** for tasks that need human approval or additional input. - For tasks created from chat, check the source conversation when the context is unclear. - After running a task, open the latest task conversation to verify the actual agent output instead of relying only on task status. - For integration-created tasks, confirm the target workspace and default agent before enabling high-volume intake. --- # Agents Agents are configurable AI assistants that combine instructions, model settings, data collections, memory, tools, skills, sub-agents, interface settings, and access rules. Use the Agents section to create agents, review existing agents, open an agent detail, and control how each agent can be used across chat, public experiences, and integrations. ![Creating an agent](/img/agents/agents-list.png) The Agents list shows the agent name, assigned tools, model, conversation count, creator, access level, evolution status, favorite state, edit actions, and row actions. From the list, users can search agents, create a new agent, or create an agent from a saved template. An agent detail is organized into the same tabs as the application: | Tab | Purpose | | --- | --- | | [Overview](#doc-agents-overview) | Review the agent's current state, usage, feedback, and important summary cards. | | [Configuration](#doc-agents-configuration) | Control instructions, model, data, memory, tools, skills, access, and sub-agents. | | [Interfaces](#doc-agents-interfaces) | Expose the agent through public chat, web plugin, and authenticated widget settings. | | [Prompts](#doc-agents-prompts) | Manage reusable prompt records attached to the agent. | | [Analytics](#doc-agents-analytics) | Review agent-specific usage, messages, and token trends. | | [Evolution](#doc-agents-evolution) | Generate and apply prompt improvements from feedback. | | [Conversations](#doc-agents-conversations) | Inspect conversations created with this agent. | | [Feedbacks](#doc-agents-feedbacks) | Review user ratings, comments, and feedback message context. | | [History](#doc-agents-history) | Audit changes made to the agent configuration and related records. | ## When To Use Agents Create or edit an agent when a team needs a stable assistant with a clear role, governed access, and repeatable behavior. A production agent should have a clear description, model connection, system message, allowed data sources, approved tools, and an access policy that matches its audience. Agents can be used internally in chat, embedded into public or authenticated web experiences, connected to realtime flows, and composed with sub-agents. For reusable capabilities that apply across multiple agents, use the separate [Skills](#doc-skills) page. --- # Overview The **Overview** tab is the starting point for checking an agent's current state. It gives agent owners and admins a compact operational summary before they open deeper tabs. The current application renders these overview areas: - **General**: agent name, model, credentials, description, and assigned shared/private tools. - **Evolution**: whether prompt evolution is currently possible for the agent. - **Feedbacks**: recent feedback activity for the last period. - **Conversations**: conversation activity for the last period. - **Users conversations**: the top active users for the selected agent. ![Agent Overview](/img/agents/overview.png) ## General Card The General card shows the identity and runtime baseline of the agent: - name, - model name, - credential or AI connection name, - description, - assigned tools. The tool display combines shared tools and private tools. The card shows up to the visible tool limit and then displays a hidden count when more tools are attached. Tool icons include their visibility type so owners can distinguish organization-level tools from private user-context tools. The card also includes a favorite action and a **Start chat** action. Starting chat clears the current conversation context and opens chat with the selected agent. ## Health Signals The remaining cards are designed for quick triage: - use **Evolution** to see whether feedback can drive a new prompt evaluation, - use **Feedbacks** to spot recent positive or negative reactions, - use **Conversations** to understand current usage volume, - use **Users conversations** to see which users interact with the agent most often. If a metric suggests a problem, open the related tab for full context instead of editing the agent from the overview alone. --- # Configuration The **Configuration** tab controls how the agent behaves, what context it can use, which tools it can call, and who can access it. This tab is the main place to turn an agent from a draft into a production-ready assistant. ![Agent Configuration](/img/agents/configuration.png) ## Details The Details section defines the agent's basic behavior: - **Name**: the label shown in lists, chat selection, and detail pages. - **Description**: the agent purpose shown to admins and owners. - **AI Connection**: the provider or model connection used by the agent. - **Model Name**: the model available through the selected connection. - **Reasoning effort**: the reasoning level when the selected connection supports it. - **Initial Message**: the first message shown when a user starts a conversation. - **System Message**: the primary instruction that defines the agent's role, constraints, tone, and workflow. Changing the AI connection can reset the model selection when the current model no longer matches the selected connection type. For Azure AI Foundry connections, **Model Name** can be a direct model deployment or a model router deployment such as `model-router`. A router deployment keeps the agent configuration simple while Azure selects an underlying model per request according to the router's routing mode and approved model subset. ## Context And Knowledge The agent can be connected to several context sources: - **Data connection** assigns data source collections that can be used as retrieval context. - **Memory** assigns memory pages and memory collections that the agent can read as reusable context. - **Memory write** controls whether the agent may create or update Memory content during execution. - **Task workspace** connects the agent to a task workspace when task workflows are enabled. Use these sections to give the agent reliable business context before adding more tools or broad access. Treat Memory read and Memory write as separate decisions. An agent can use attached Memory for retrieval even when Memory write is disabled. Enable Memory write only for agents that should maintain curated knowledge and whose outputs will be reviewed. ## Access And Identity When the current user can manage access policy, the Configuration tab includes **Access** controls. Access defines whether the agent is available broadly, shared with selected audiences, or kept private. The **Icon** section sets the visual identity used in the agent list, chat selector, and other agent entry points. It includes both the icon and icon color. ## Model Settings The **Model configuration** section exposes model parameters through sliders: - temperature, - maximum length, - presence penalty, - frequency penalty. Tune these only after the system message and context are stable. Model settings can change style, creativity, verbosity, and repetition behavior. ## Tools, Skills, And Sub-Agents The Configuration tab can attach: - **Platform Tools**: built-in Siesta AI capabilities. - **Shared Tools**: organization-level tools available to the agent. - **Private Tools**: user-specific tools connected in a private context. - **Chat private connection options**: private connection types that chat users may attach while using this agent. - **Skills**: reusable capability definitions assigned to this agent. - **Sub-Agents**: other agents this agent can call or coordinate with. The standalone [Skills](#doc-skills) page remains separate from Agents. In the agent detail, skills are only assigned to the selected agent; they are not managed as a nested Agents section. ## Private Connections For Chat Users Private connection settings let users bring their own approved accounts into chat with the agent. For example, an agent can be allowed to work with a user's mailbox, calendar, or Drive connection without making that connection shared across the organization. Use this carefully. Only allow private connection types that match the agent's purpose, and remind users to verify which private account is attached before asking the agent to read or modify personal resources. --- # Interfaces The **Interfaces** tab controls where users can access the agent outside the internal agent detail. It includes the agent ID, public chat controls, web plugin snippets, public chat settings, widget placement options, and authenticated widget settings. ![Agent Interface](/img/chat/interfaces-en.png) ## Agent ID The tab shows the agent ID in a read-only copyable field. Use this ID when configuring external integrations, embed snippets, or backend flows that need to reference a specific agent. ## Public Chat When public chat is enabled for the organization, the tab can expose a **Public Chat** card. Turning it on creates a copyable chat URL for the agent. Public chat is still governed by organization-level security and the agent's own settings. If public chat is disabled globally, the agent cannot be made public from this tab. ## Web Plugin {#public-chat-plugin} When public chat is enabled for the agent, the **Web Plugin** card provides the script used to embed the chat widget on an external website or portal. The UI includes copy controls and an advanced settings button for widget placement options. The publicly accessible chat interface does not require registration or login unless authenticated widget mode is enabled. Visitors can communicate with the selected agent using the capabilities allowed by the agent and organization, including feedback, file uploads, reasoning visibility, realtime audio, and audit logging. Advanced embed settings generate a customized script with launcher position and pixel offsets, for example bottom-right placement with horizontal and vertical spacing. The preview in advanced settings is illustrative; the final appearance can still depend on the website layout and CSS. Advanced embed settings are temporary in the form. To apply them, update the generated snippet on the website where the widget is installed. Use the [developer Widget Playground](#doc-developers-web-plugin-playground) to test widget behavior in real time before embedding it into a customer website or internal portal. ![Public Chat Plugin](/img/chat/public-chat-plugin.png) ![Widget advanced settings](/img/chat/widget-advanced-settings.png) ## Public Chat Settings The Public Chat Settings panel controls what visitors can do in public chat: - submit feedback, - upload files, - see reasoning when allowed, - open the configured privacy link, - use realtime when it is enabled for the organization and the agent. Save public settings after changing them. Privacy links are normalized so plain domains can be stored as HTTPS URLs. Public chat settings are saved to the agent configuration. If sensitive data is handled, use authenticated chat and review public access, privacy, retention, and prompt shield settings before publishing. ![Public chat settings](/img/chat/public-chat-settings.png) ## Authenticated Chat Widget The authenticated widget mode lets the embedded chat require sign-in. The tab includes: - an enable switch, - a Google OAuth Client ID field, - confirm and discard controls for the client ID, - a generated script for the authenticated widget. Use authenticated widget mode for customer portals, intranets, or any public surface where the agent should know the signed-in user or avoid anonymous access. ![Authenticated chat widget settings](/img/chat/authenticated-chat-widget-settings.png) --- # Prompts The **Prompts** tab manages prompt records attached to the selected agent. A prompt record is an additional instruction entry that can be created, edited, and deleted without changing the main agent detail page directly. ![Agent Prompts](/img/agents/prompts.png) ## Prompt List The tab displays a paginated table of prompt records for the agent. The current table includes: - prompt text, - creation date, - row actions. Row actions let users edit or delete a prompt. Deleting a prompt requires confirmation. ## Creating A Prompt Use **Create prompt** to add a new prompt record. The create form requires prompt text before submission. After the prompt is created, the app returns to the prompt list. Prompt text should be specific, testable, and scoped to the behavior it is meant to influence. Avoid placing credentials, private customer data, or temporary troubleshooting instructions in reusable prompts. ## Editing A Prompt Opening prompt detail lets users update the prompt text or return to the prompt list. Prompt changes can affect future behavior, so treat them like production configuration changes. Use the [History](#doc-agents-history) tab when you need to audit changes around the agent over time. --- # Analytics The **Analytics** tab shows agent-specific usage and token data. It is separate from global Analytics because it focuses only on the selected agent. ![Agent Analysis](/img/agents/analytics.png) ## KPI Cards The tab loads analytics data for the selected agent and renders KPI cards from the returned metrics. Each card shows the total count and a "today" subtitle when a matching daily value is available. Use KPI cards to quickly compare overall activity with current-day activity. ## Token Usage Chart The token chart shows monthly token usage split into: - total tokens, - input tokens, - output tokens, - reasoning tokens. This helps owners understand whether a prompt, model, or workflow change increased the agent's cost profile. ## Monthly Messages Chart The messages chart shows monthly message volume for the selected agent. Use it to understand adoption, seasonality, and whether recent configuration changes affected usage. Analytics are most useful after rollout, after a model or prompt change, and before deciding whether an agent should be optimized, retired, or expanded. --- # Evolution The **Evolution** tab supports controlled improvement of the agent from real feedback. It compares the current prompt with an evaluated prompt and lets owners apply approved changes. ![Agent Evolution](/img/agents/evolution.png) ## Feedback Input The tab loads unapplied feedback for the agent. Users can review feedback records and exclude selected feedback items from the next evolution run. Evolution can start only when there is feedback available and no evaluated prompt is already waiting to be applied. ## Evolve The **Evolve** action sends the selected feedback context to the evolution flow. When it succeeds, the tab shows: - the current prompt, - the evaluated prompt, - a diff-style view between the two. Users can edit the evaluated prompt before applying it. The UI tracks whether the evaluated prompt has been modified and provides an undo action to return to the generated evaluated text. ## Apply Evolution The **Apply evolution** action saves the evaluated prompt back to the agent. After a successful apply, the tab shows a success alert and refreshes the feedback list. Use Evolution for deliberate, reviewable prompt improvement. Do not apply changes blindly: review the diff, confirm the feedback actually supports the change, and test the agent after applying it. --- # Conversations The **Conversations** tab lists conversations created with the selected agent. It is useful for quality review, support investigation, and understanding how users actually interact with the agent. ## Conversation List The tab reuses the conversation table filtered to the current agent. Agent-wide columns that are not useful in this context are hidden, and the row action opens conversation detail. Use the list to inspect: - conversation titles and metadata, - conversation activity, - user behavior patterns, - records connected to feedback or analytics spikes. ## Conversation Detail Opening a conversation shows the conversation header and message history. The message view includes agent messages, user messages, tool/action activity, and conversation status. Selecting an action opens an action detail sheet so reviewers can inspect the tool execution context. Use conversation detail before changing prompts or tools. The raw interaction often explains whether the issue came from the user's request, missing context, tool behavior, or the agent instructions. --- # Feedbacks The **Feedbacks** tab collects ratings and comments that users submitted for the selected agent's responses. Feedback is one of the main inputs for quality review and prompt evolution. ![Agent Feedback](/img/agents/analytics.png) ## Feedback List The tab shows a feedback table filtered to the current agent. Search is hidden in this context, and row actions open the selected feedback detail. Use the list to identify: - negative ratings that need review, - positive ratings that confirm useful behavior, - repeated complaint patterns, - feedback that should be used or excluded in Evolution. ## Feedback Detail Feedback detail shows: - feedback creation time, - agent name, - rating, - user name when available, - related conversation messages, - submitted feedback text. Review feedback detail before changing the agent. The same rating can mean different things depending on the conversation context and the exact message that received feedback. --- # History The **History** tab shows audit log records for the selected agent. It helps owners understand what changed, who changed it, and when it happened. ![Agent History](/img/agents/evolution.png) ## History List The tab loads audit log records filtered by the agent entity. The table supports pagination and row actions for opening detail. Use the list to track: - configuration changes, - access changes, - tool and data assignment updates, - prompt-related changes, - administrative edits around the agent. ## History Detail Opening a history record shows the audit log detail card and a changes card. This lets reviewers inspect the recorded change payload instead of relying only on current agent state. History is important when an agent starts behaving differently after edits. Check it before assuming that the model, data, or tool integration is responsible. --- # Tools A tool gives an agent a capability beyond writing a model response. It can read live information, work with another application, execute code, create a file, or operate Siesta AI itself. Siesta AI exposes two user-facing groups: ```text Tools ├── Connection Tools │ ├── Shared Tools │ └── Private Tools └── Platform Tools ├── Search, scraping, code, tasks, and orchestration └── Platform Management for Siesta AI administration ``` ## Choose the Right Tool | The agent needs to | Use | Example | | --- | --- | --- | | Read or change an external business application | Connection Tool | Gmail, Slack, Jira, HubSpot, Google Drive | | Use a team or organization credential | Shared Tool | Shared support mailbox or service-account Jira | | Act as the current user | Private Tool | Personal Gmail, calendar, or OneDrive | | Use a capability provided by Siesta AI | Platform Tool | Code Interpreter, Task Management, Web Scraper | | Create or update Siesta AI configuration | Platform Management | Create an agent, update a Skill, write a Memory page | | Answer from maintained indexed knowledge | Data or Memory | Policies, manuals, approved knowledge collections | | Call a custom interface | REST or MCP Connection Tool | Internal CRM API or MCP server | ## Connection Tools Connection Tools work with external systems. Their functions come from configured Connections, REST APIs, or MCP servers. Examples include reading a Drive file, sending a Slack message, creating a Jira issue, or querying an analytics service. - **Shared Tools** use Connections shared with the agent's audience and are suitable for team-owned or organization-owned accounts. - **Private Tools** resolve the current conversation user's own Connection and are suitable when actions must run under that user's identity. The difference is credential ownership and runtime identity, not the provider function itself. Connection functions can be disabled, enabled, or enabled with confirmation. Require confirmation for send, publish, create, update, delete, permission, financial, or production-impacting actions. ## Platform Tools Platform Tools are built-in capabilities assigned directly to an agent or Template. The backend constructs some functions directly; Google Search and Web Scraper use system-managed provider Connections but still appear to users as Platform Tools. The key relationship is: ```text Platform Tools ├── Task Management ├── Grounding with Google Search ├── Web scraper ├── Code interpreter ├── SiestaAI Help ├── Orchestration ├── JavaScript executor └── Platform Management ``` Platform Management is the privileged capability for administering Siesta AI. It belongs to the Platform Tools group. ![Platform Tools in agent configuration](/img/system-tools/system-tools-agent-configuration.png) ## How Platform Tools Reach an Agent Siesta.AI.App loads the available Platform Tools and stores their selected IDs on the agent. It keeps Shared and Private Connection Tools in separate form sections. Templates can also include Platform Tool assignments. Siesta.AI.Backend then creates the executable catalog. Platform Tools reach it in two ways: - **runtime builders** construct Task Management, Code Interpreter, SiestaAI Help, Platform Management, Orchestration, and JavaScript Executor, - **system-owned Connections** supply Google Search and Firecrawl functions implemented in Siesta.AI.Tools. System-owned connection functions bypass ordinary user connection ownership lookup because their credential belongs to the system organization. Organization-level connection governance still applies. ## Platform Management Platform Management creates, reads, searches, or updates Siesta AI objects. The frontend hides this privileged capability from normal Users. The backend adds its functions only when the agent has Platform Management assigned and the current user has the Owner or Admin role. Assignment alone is therefore not enough. An Owner/Admin role alone is also not enough. Both checks must pass for the `Platform_*` functions to enter the runtime catalog. ## Platform Tool Overview | Platform Tool | Runtime surface | What it does | Important prerequisite | | --- | --- | --- | --- | | Task Management | `Platform_CreateTask` | Creates a task in the agent's configured task workspace. | Agent must have `TaskWorkspaceId`. | | Grounding with Google Search | `GoogleSearch.Search` | Searches Google Custom Search and returns URLs, snippets, and limited scraped page context. | Assigned Platform Tool must reference the system GoogleSearch connection. | | Web scraper | Firecrawl functions | Scrapes, crawls, maps, or searches web content through Firecrawl. | Assigned Platform Tool must reference the system Firecrawl connection. | | Code interpreter | `CodeInterpreterAgent` | Delegates code, data, file, and artifact work to a hosted code interpreter agent. | System Code interpreter connection must contain project endpoint/name. | | SiestaAI Help | `siesta_help_resolve` | Diagnoses missing connection/tool setup and returns guidance or action cards. | Assigned Platform Tool. | | Platform Management | `Platform_*` functions | Creates, reads, searches, and updates Siesta platform objects. | Owner/Admin user context and assigned Platform Management. | | Orchestration | `run_function_batch` | Sends many inputs to a named sub-agent function. | Agent must have sub-agents for useful calls. | | JavaScript executor | `JsExecutorAgent` | Runs synchronous JavaScript with sub-agent, Excel, status, and artifact helpers. | Assigned Platform Tool. | ## Task Management Task Management exposes one function: `Platform_CreateTask`. Use it only when the user explicitly asks to create a task. The backend function description says: create a task only when the user explicitly asks and never call it proactively. ### What It Does `Platform_CreateTask` creates a `TaskItem` in the task workspace assigned to the current agent. It stores the current conversation and current agent as source references when the source conversation still exists. The created task receives an icon resolved from the requested icon, summary, and prompt. If the workspace has auto-execution enabled, the backend immediately starts task execution using the explicitly assigned agent or the workspace default agent. ### Inputs | Field | Required | Behavior | | --- | --- | --- | | `summary` | Yes | Short task summary. Empty values fail. | | `prompt` | No | Detailed task prompt. Defaults to an empty string. | | `icon` | No | Requested icon filename. The backend resolves it through the task icon resolver. | | `status` | No | Parsed as `Todo`, `InProgress`, `Review`, or `Done`; defaults to `Todo`. | | `assignedChatBotId` | No | Optional UUID of the agent assigned to the task. Invalid UUID fails. | | `assignedChatBotName` | No | Optional exact agent name. If multiple agents match, the backend asks for `assignedChatBotId`. | ### Output And Failure Modes On success, the tool returns task ID, summary, status, and a button labeled **Open task**. The call fails when: - `summary` is missing, - the agent has no task workspace, - the workspace is inaccessible or the user cannot write to it, - `assignedChatBotId` is invalid, - `assignedChatBotId` and `assignedChatBotName` refer to different agents, - `assignedChatBotName` is missing, ambiguous, or inaccessible. ## Grounding With Google Search Grounding with Google Search is implemented through the `GoogleSearch` tool connection. The Platform Tool links to a system-owned GoogleSearch connection, and the runtime adds its connection function to the agent. ### Function `GoogleSearch.Search` performs a Google Custom Search request and returns ranked results. The implementation also tries to fetch each result URL and extract a short text context from paragraphs, headings, and list items. It removes common non-content tags such as scripts, styles, navigation, headers, footers, iframes, SVGs, and noscript blocks. ### Inputs | Field | Required | Behavior | | --- | --- | --- | | `query` | Yes | Search query. It should be specific. | | `count` | No | Number of results from 1 to 10. Values are clamped; default is 3. | | `country` | No | Google `gl` country code, for example `us`, `cz`, or `sk`; default is `cz`. | | `timePeriod` | No | Google `dateRestrict`, for example `d1`, `w1`, `m1`, or `y1`. | ### Output And Use The model receives: - result title, - result URL, - snippet, - optional scraped page text, truncated to keep context small. The user-facing result lists found URLs and can include a **View on Google** button. Use this tool when the answer depends on current public information, search result ranking, or time-bounded research. Do not treat search results as verified internal truth; the assistant should compare and cite sources when accuracy matters. ## Web Scraper Web scraper is implemented through the Firecrawl tool connection. The Platform Tool links to the system Firecrawl connection. It is read-oriented: it fetches external content but does not write to the target website. ### Functions | Function | Inputs | Backend behavior | | --- | --- | --- | | `ScrapePageAsync` | `url`, `onlyMainContent` | Calls Firecrawl `scrape`, requests markdown, and returns the page title plus markdown. | | `CrawlSiteAsync` | `url`, `limit`, `includePaths`, `excludePaths` | Starts a Firecrawl crawl, polls until completion or timeout, and combines page markdown with source URLs. | | `MapSiteAsync` | `url`, `search`, `limit` | Calls Firecrawl `map` and returns discovered links, including title/description when available. | | `SearchWebAsync` | `query`, `limit` | Calls Firecrawl `search` and returns markdown or descriptions from top web results. | ### Output And Use Use Web scraper when the user gives a specific URL, asks to inspect a site, wants SEO/content review, wants a site map, or needs page content turned into structured context. Important boundaries: - It can fetch sensitive URLs if the agent is allowed to see them, so prompts should be clear about what may be scraped. - It depends on the Firecrawl API key and configured API URL. - Crawl jobs can fail, time out, or return no pages. - External page content can be stale, misleading, copyrighted, or policy-restricted. ## Code Interpreter Code interpreter exposes `CodeInterpreterAgent`. The function delegates the user request to a hosted code interpreter agent. The tool builder deliberately tells the model not to solve, plan, write code, choose file names, or define implementation details before delegation. The assistant should pass the user's intent directly or minimally reformatted. ### What It Does The backend: 1. Loads the system `Code interpreter` connection from the system organization. 2. Reads the configured project endpoint and project name. 3. Creates an Azure AI Project client and a hosted code interpreter agent using `gpt-4.1`. 4. Uploads current conversation attachments to the code interpreter sandbox when file bytes are available. 5. Appends available input filenames to the delegated prompt. 6. Runs the hosted agent. 7. Collects text output. 8. Downloads generated container files referenced by annotations. 9. Uploads generated files to Siesta AI artifacts. 10. Returns the text result and file metadata. ### Inputs And Outputs | Field | Required | Behavior | | --- | --- | --- | | `prompt` | Yes | Original user request for the coding specialist. | The output can include: - plain text result, - generated artifact file IDs, - file names, - file size, - content type. Use Code interpreter for programming, scripting, calculations, file transformation, data analysis, chart/file generation, and debugging tasks that benefit from executing code. ## SiestaAI Help SiestaAI Help exposes `siesta_help_resolve`. It is a diagnostic and guidance tool for connection setup, tool assignment, and platform documentation questions. It does not create permissions by itself. It resolves what the user appears to need and can return either a normal help answer or an action card with setup buttons. Enable it on the agent in **Configuration -> Platform Tools** by turning on **SiestaAI Help** in the Platform Tools list. ![Platform Tools in agent configuration](/img/system-tools/system-tools-agent-configuration.png) ### Inputs | Field | Required | Behavior | | --- | --- | --- | | `userRequest` | Yes | Original user request that needs help or connection diagnostics. | | `capability` | No | Best matching capability, such as `email.send`, `calendar.create_event`, `drive.read_file`, `slack.send_message`, `jira.create_issue`, `connections.setup`, or `connections.assign`. | | `targetService` | No | Explicitly named service such as Gmail, Outlook, Google Calendar, Google Drive, Slack, Jira, or HubSpot. Do not infer Gmail/Outlook from generic "email". | | `targetServices` | No | Explicitly named services when the user asks to set up or assign multiple connections. | | `targetServiceMentionedByUser` | No | True only when the user explicitly named the service. | | `targetAgentId` | No | Agent ID that should receive connection/tool setup. Prefer IDs returned by Platform Management. | | `targetAgentName` | No | Agent name when no target ID is available. | | `targetAgentMentionedByUser` | No | True when the user asked to configure a specific agent. | | `intent` | No | Use `connection_setup`, `connection_assignment`, `connection_diagnostics`, or `platform_docs`. | | `topic` | No | Canonical documentation topic such as `workflows`, `connections`, `agents`, or `tools`. | ### Output And Use The result includes a title, message, state metadata, optional docs URL, and sometimes a primary button/action. If action labels are returned, the assistant should tell the user to use the shown buttons instead of explaining a long manual navigation path. Use it when the user says an agent cannot use Gmail, Outlook, Drive, Slack, Jira, HubSpot, calendar, or another external service; when they ask how to connect a tool; or when they ask for platform documentation. ## Platform Management Functions Platform Management exposes privileged `Platform_*` functions for operating Siesta AI itself. They are gated in two ways: - the agent must have Platform Management assigned, - the current user must be Owner or Admin in chat execution. Platform Management is hidden from normal Users. Internally, this capability is still stored as the system-tool record named `Platform Tools`. The documentation uses Platform Management to distinguish it from the complete Platform Tools group. ### Agent Functions | Function | What it does | Important fields | | --- | --- | --- | | `Platform_CreateAgent` | Creates a new agent. The new agent uses the current agent's model and connection unless overridden. | `name`, `systemMessage`, `description`, `modelName`, `temperature`, `maxTokens`, `presencePenalty`, `frequencyPenalty`, `initialMessage`, `reasoningEffortLevel` | | `Platform_CreateAgentFromTemplate` | Creates an agent from a template exactly using the template configuration. | `templateId` | | `Platform_GetAgent` | Reads a single agent. Omit ID or pass `self` for the current agent. | `id` | | `Platform_ListAgents` | Searches organization agents by name. | `search`, `limit` | | `Platform_UpdateAgent` | Updates an existing agent. Omit ID or pass `self` for current agent. Only provided fields are changed. | Agent fields plus `skillIds`, `memoryCollectionIds`, `memoryPageIds`, `systemToolIds`, `subAgentIds` | | `Platform_ListConversations` | Lists recent private conversations for an agent. Hidden, shared, and public conversations are excluded. | `agentId`, `search`, `limit` | | `Platform_ListMessages` | Lists recent messages from a private conversation. Hidden, shared, and public conversations are excluded. | `conversationId`, `search`, `role`, `limit` | `Platform_UpdateAgent` replaces full assignments for arrays that are provided. Passing `skillIds`, `systemToolIds`, or `subAgentIds` means "set the complete list", not "append". Passing memory collection/page arrays replaces all current memory page assignments. `Platform_GetAgent` returns agent details including prompt, model settings, skills, memory collections/pages, assigned Platform Tools, and sub-agents. ### Skill Functions | Function | What it does | | --- | --- | | `Platform_CreateSkill` | Creates a skill with `name`, `instructions`, and optional `description`. | | `Platform_GetSkill` | Reads one skill, including full instructions. | | `Platform_ListSkills` | Searches organization skills by name. | | `Platform_UpdateSkill` | Updates name, instructions, or description. Only provided fields are changed. | Skills define reusable behavior for agents. Updating skill instructions can change behavior for every agent that uses the skill. ### Template Functions | Function | What it does | | --- | --- | | `Platform_GetTemplate` | Reads one agent template including full configuration. | | `Platform_ListTemplates` | Searches organization templates by name. | Templates can copy prompts, model settings, skills, memory assumptions, and Platform Tools into new agents. Review templates before using them to create privileged agents. ### Memory Functions | Function | What it does | Important fields | | --- | --- | --- | | `Platform_CreateMemoryCollection` | Creates a Memory collection in the current organization. | `name` | | `Platform_GetMemoryCollection` | Reads a Memory collection. | `id` | | `Platform_ListMemoryCollections` | Searches Memory collections. | `search`, `limit` | | `Platform_UpdateMemoryCollection` | Updates collection name. | `id`, `name` | | `Platform_CreateMemoryPage` | Creates a Memory page inside a collection. | `collectionId`, `name`, `body`, `order`, `parentId` | | `Platform_GetMemoryPage` | Reads a Memory page. | `id` | | `Platform_UpdateMemoryPage` | Updates page name, body, order, or parent. | `id`, `name`, `body`, `order`, `parentId` | Memory created through Platform Management becomes reusable context. Treat it as operational knowledge, not temporary chat output. ## Orchestration Orchestration exposes `run_function_batch`. ### Inputs | Field | Required | Behavior | | --- | --- | --- | | `functionName` | Yes | Name of the sub-agent function to execute for every input. | | `input` | Yes | Array of input strings. | The backend creates a private conversation for the selected sub-agent for each input string, sends the input as a message, and combines the results. It runs in parallel with a maximum concurrency of 40. Use it for repeatable batch work such as classification, summarization, scoring, extraction, or repeated specialist review. Do not use it when a single direct answer or one sub-agent call is enough. ## JavaScript Executor JavaScript executor exposes `JsExecutorAgent`. It runs synchronous JavaScript in a Jint engine and returns log output plus the final expression result. Objects and arrays are converted through `JSON.stringify` for readable model output. ### Available Helpers | Helper | Behavior | | --- | --- | | `log(message)` | Adds internal log output returned with the result. | | `logStatus(message)` | Publishes a real-time status update visible to the user. | | `callAgent(name, prompt)` | Synchronously creates a private conversation with a named sub-agent and returns its response. | | `callAgentsParallel(names, prompts)` | Calls multiple sub-agents in parallel; `names` and `prompts` must have equal length. | | `readExcelFile(fileName, sheetName, maxRows?)` | Reads rows from an attached Excel file. | | `listExcelSheets(fileName)` | Lists sheet names in an attached Excel file. | | `writeExcelFile(fileName, sheetName, rows)` | Writes rows to a new Excel file. | | `createExcelDocument(fileName, sheetName, rows)` | Creates an Excel file and attaches it as a downloadable conversation artifact. | | `searchExcelRows(fileName, sheetName, columnName, searchValue)` | Searches rows by case-insensitive column value match. | | `getExcelColumnStats(fileName, sheetName, columnName)` | Returns numeric column stats: min, max, sum, average, count. | | `copyFileAsArtifact(sourceFileName, newFileName)` | Copies a conversation attachment into artifacts and returns file metadata. | | `editArtifactFile(fileId, content)` | Replaces content of an artifact previously created for editing. | ### Usage Rules - All helper functions are synchronous. - Do not use `async`, `await`, or Promises. - Use `logStatus()` before significant work so the user sees progress. - Use it when loops, branching, aggregation, spreadsheet processing, or controlled sub-agent orchestration are clearer in code than in natural language. - Limit it to trusted/admin or power-user agents because it can call sub-agents, process files, and create artifacts. ## Governance Notes Enable Platform Tools intentionally. - **Task Management** can create persistent work and may auto-execute tasks. - **Grounding with Google Search** and **Web scraper** read public or reachable external content, which can be stale, misleading, sensitive, or policy-restricted. - **Code interpreter** can execute code and create files; review outputs before operational use. - **SiestaAI Help** guides setup but does not grant permissions. - **Platform Management** can change agent behavior, Skills, Memory, sub-agents, and Platform Tool assignments. - **Orchestration** can create many sub-agent conversations quickly. - **JavaScript executor** can run scripted logic, call sub-agents, process Excel files, and create artifacts. When Platform Tools are included in a Template, newly created agents can inherit them. Review Platform Tool assignments before publishing Templates broadly. Use [Tool Executions](/tool-executions) to inspect arguments, results, status, errors, and approvals. ## User-Safe Examples ```text Use web search to verify this, then cite what you found. Do not rely only on memory. ``` ```text Scrape this URL and summarize only facts visible on the page. ``` ```text Create a task from this conversation with summary, prompt, and status Todo. ``` ```text Check whether this agent has the right connection assigned. If not, show me the setup action. ``` ```text Analyze this spreadsheet and create a downloadable cleaned version. ``` ```text Use the JavaScript executor to read the attached Excel file, group rows by owner, and create a cleaned workbook. ``` --- # Skills The Skills section allows you to define and manage specific abilities that you can subsequently assign to your [Agents](#doc-agents). While the system prompt determines the agent's identity, skills define their specific capabilities and tools available for task completion. ![Overview of the Skills section](/img/skills/skills-overview.png) ## Organization vs. System Within the Skills section, we distinguish between two basic categories of abilities that you will find in the top tabs: * **Organization**: Here you will find a list of skills created directly within your organization. You can freely create, edit (pencil icon), or delete (trash icon) these skills. * **System**: Contains predefined system skills (e.g., for trend analysis or SEO) that are available to everyone on the platform. These skills cannot be directly edited, but you can use the copy icon to leverage them as a basis for your own skills. ## Creating and Editing a Skill You can create a new ability by clicking the **Create** button in the upper right corner. In the detail view (or during editing), you define the following parameters: * **Name**: A clear and concise name for the skill (e.g., *Writing an Article for the Web*). * **Description**: A brief description of what this skill does and its purpose. * **Instructions**: A key section where you define the instructions provided to the agent when this skill is activated. Here you describe the procedures and steps the agent should follow. * **Tools**: A selection of functions and external tools available to the agent within this skill (e.g., sending an email via Gmail or creating a ticket in Jira). In the current workflow, skill editing is meant to be a reusable configuration step, not a one-off chat tweak. When multiple agents need the same procedure, update the shared skill instead of duplicating the logic in each agent's system prompt. ![Creating a Skill](/img/skills/skill-create.png) ## Difference Between System Prompt and Skill The Siesta AI platform consistently separates the agent's identity from their abilities, which brings several advantages: | Feature | System Prompt (Role) | Skills (Ability) | | :--- | :--- | :--- | | **Definition** | Who the agent is (role, behavior, tone, boundaries). | What the agent does (abilities, tools, procedures). | | **Stability** | Maintains the identity and tone of communication stable. | Allows for flexible addition or modification of skills. | | **Reusability** | Specific to a particular agent. | Easily shared across different agents and teams. | ### Why Use This Section? 1. **Scalability**: Once created, a skill (e.g., “Reporting Bugs to Jira”) can be assigned to ten different agents without needing to rewrite their instructions. 2. **Security**: By updating a skill in one place, you automatically enhance the abilities of all agents using it. 3. **Clean Management**: Separating identity (behavior) from technical tasks (tools) leads to more predictable and accurate agent outcomes. ## Linking with Agents Once you have created a skill, you can assign it to an agent in their configuration under the **Skills** section. The agent will then automatically recognize when to use the given skill and its associated tools to resolve the user's request. After changing a skill, review the affected agents and confirm that: - the skill label and description are still understandable to admins, - the attached tools still match the intended scope, - the updated behavior should apply to every agent that uses that skill. --- # Conversations The Conversation feature serves to provide a clear display of the history of interactions between users and individual AI agents within the Siesta AI platform. ![Overview of Conversations](/img/conversations/conversations-overview.png) ## Feature Description ### Overview of All Conversations An administrator or authorized user can see a list of all previously conducted conversations sorted by date. The displayed information in the overview includes: - **Date and time of the conversation start** - **User's email** - **Subject / topic of the conversation** (e.g., “Specified deadline for termination of employment") - **Number of messages in the conversation** - **Name of the agent** with whom the communication took place (e.g., “HR Agent”) Use filtering and search to narrow the list by user, agent, date, or conversation context when investigating a specific issue. Administrators can also enable **Flagged only** to focus on conversations marked by safety or moderation checks. When the flagged-reason column is available, the row shows a flagged badge; open it to review the stored reason before deciding whether the issue belongs in agent configuration, safety settings, or user follow-up. ### Conversation Detail Clicking on a row opens the conversation detail at `/internal/conversations/[id]`. The detail shows the full message history, including user inputs, assistant responses, and any visible execution context. Use this view when you need to understand exactly what the user asked, how the agent responded, and whether the answer relied on tools, uploaded files, or prior context. When reviewing a conversation detail, check: - the first user request and the agent selected for the conversation, - follow-up messages that changed the context, - files or images attached by the user, - response formatting and cited information, - errors, missing answers, or interrupted generation, - whether the user submitted feedback on a response. ### Feedback Option Individual responses can be rated positively (thumbs up) or negatively (thumbs down), and a comment can be added. This information is subsequently displayed in the Feedback section and helps fine-tune the accuracy of responses. Feedback from a conversation is useful for: - identifying weak answers, - improving agent prompts, - checking whether the right data collection was attached, - deciding whether an issue belongs in agent evolution work. ### Sharing If sharing is enabled by organization security settings, a conversation can be shared through a link. Sharing is useful for support, review, or handoff, but it should be used carefully when the conversation contains sensitive data. Before sharing: - confirm that public conversation sharing is allowed, - remove or avoid sharing conversations with confidential information, - share only with the intended audience, - use Audit Log if you need to verify sharing-related changes. ### Artifacts Agent responses can include artifacts: generated files or structured outputs attached to a specific assistant message. Artifacts are different from user-uploaded attachments and from documents stored in Data collections. They are outputs produced during a conversation and remain connected to the message that created them. Artifacts can be opened or downloaded from the conversation detail when the viewer has access to the conversation. If a conversation is shared, artifact visibility follows the same sharing and security model as the conversation itself. If public sharing is disabled by tenant policy, users should not rely on shared artifact links for external handoff. Use artifacts for outputs such as generated reports, files, exports, or other downloadable results. For long-term source knowledge, use [Data](#doc-data-collections) instead. ### Realtime Context Realtime and voice sessions are stored as part of the same conversation model. A realtime session is not a separate object that replaces conversation history; it is a temporary transport for interacting with an agent while preserving the conversation thread. When reviewing a realtime conversation, check the same operational signals as standard chat: selected agent, user context, transcript/messages, tool executions, approvals, feedback, and any artifacts generated during the session. ### Audit and Tool Activity Conversation review often connects to Logs: - Use **Tool Executions** to inspect tool calls created by the conversation. - Use **Audit log** to check administrative changes that may have affected access, sharing, or agent behavior. ### Access Rights Access to these records is governed by user roles. While regular users do not have access to the feature, administrators and the management team can view the complete history of all conversations. --- # Data Data collections turn files and records from external systems into reusable, searchable knowledge for Siesta AI agents. This section explains every Data source currently available in the dev application and what belongs in each field. ## The Data Model 1. A **connection** stores authentication for an external system. 2. A **data collection** is the access-controlled business container. 3. A **data source** defines exactly what to import through a connection. 4. **Documents and chunks** are the processed content that retrieval can search. 5. An **agent** retrieves from one or more assigned collections. Credentials belong in **Connections**. Folder IDs, paths, blob selectors, project or space keys, and URLs belong in the Data-source form. ## Start Here | Goal | Guide | | --- | --- | | Compare all sources and decide where content belongs | [Choose a Data Source](#doc-data-choose-a-source) | | Upload a controlled file snapshot | [Manual Upload](#doc-data-manual-upload) | | Set the default or user-specific Data upload allowance | [Data Upload Limits](#doc-data-collections-upload-limits) | | Synchronize Google folders or Shared Drives | [Google Drive](#doc-data-google-drive) | | Synchronize OneDrive or SharePoint folders | [Microsoft 365](#doc-data-microsoft-365) | | Read blobs or Azure file shares | [Azure Storage](#doc-data-azure-storage) | | Automate a governed local or on-premises document feed | [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion) | | Import Jira projects or Confluence spaces | [Atlassian](#doc-data-atlassian) | | Scrape one page or crawl a bounded website | [Firecrawl](#doc-data-firecrawl) | | Configure processing, retrieval, sync, and diagnose failures | [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) | ## When To Use Data Use a collection when several users or agents should reuse the same approved source material, content should synchronize, processing and logs must be inspectable, or the knowledge needs a private, team, or organization access boundary. For a single temporary file, a chat attachment can be simpler. For durable knowledge, use a collection. ## Create a Collection Open **Data** and select **Create collection**. ![Create data source collection dialog showing the visibility options](/img/data-collections/collections-create-dialog.png) - **Name**: use a durable business name such as `Customer Support — Approved Knowledge`. - **Description**: record content scope, owner, exclusions, and intended agents. - **Visibility**: choose one of three access scopes: - **Private**: only you and people you explicitly grant access to can use the collection. - **Entire organization**: all organization members receive the permission selected under **Organization permission**. - **Selected teams**: only members of the teams added under **Team Access** receive access. The collection is the access boundary. Do not mix confidential HR documents and public product documentation merely because both are stored in Google Drive. ## Add A Data Source Open a collection and select **Add data source**. Manual Upload is independent of Connections. Every integration-backed source first needs a compatible entry under [Connections](#doc-connections). All connected-source forms share: - **Name** identifying this specific import, - optional **Description** with owner, scope, and exclusions, - **Connection ID** selecting stored authentication, - **Sync frequency**: On Demand, Daily, Weekly, or Monthly. If Connection ID is empty, create or request access to the correct connection and return to the collection. Never paste a secret into this selector. ![Available data-source types](/img/data-collections/available-data-sources.png) After clicking the desired data source, you configure it. ![Manual Upload data-source configuration](/img/data-collections/manual-upload-configuration.png) :::caution Advanced content extraction costs Enabling Advanced content extraction increases cost. It uses Azure Document Intelligence, billed per page. Enable it only for scanned or table-heavy documents. ::: ## Inspect Before Agents Use It Check source status, representative files, `Indexed` and `Readable` state, extracted chunks, and Logs. A successful run proves that processing completed; it does not prove that every expected document is present, useful, current, or safe for the collection audience. --- # Data Upload Limits Data Upload Limits lets administrators control how much data each user may upload to Data sources in the organization. The value is a per-user upload allowance in megabytes (MB), not a maximum size for one file, a collection-access setting, or a model context limit. ## Open Upload Limits 1. Open **Data**. 2. Turn on **Admin** mode. 3. Select **Upload limits** next to **Create collection**. ![Upload limits button in the Data admin view](/img/data-collections/upload-limits-entry.png) The button and page require permission to manage users. If **Upload limits** is not visible after you enable Admin mode, ask an organization administrator to review your role. ## Set the Default Limit **Default limit** is the organization-wide fallback for users who do not have a custom upload limit. 1. Enter the allowance in MB. 2. Select the main **Save** button on the right. The field is required and accepts non-negative whole numbers only. Empty values, negative numbers, and decimals cannot be saved. The **Save** button becomes available after the value changes and is valid. Changing the default does not overwrite existing user-specific limits. ## Set a User-Specific Limit The table lists users and lets you replace the default with an individual value: 1. Use **Search** to find the user's email address. 2. Enter a non-negative whole number in the user's **Limit** field. 3. Select the disk **Save** button at the end of the same row. Each row is saved separately. A custom value remains active for that user even when the organization default changes later. Saving a row creates a custom limit, even when the value matches the current default. There is currently no action on this page that returns a custom limit to automatic default inheritance, so save user-specific values deliberately. In the example below, the default limit is **100 MB** and **Demo User 4** has a custom **500 MB** limit. These values illustrate the controls; they are not recommended or factory defaults. ![Default and user-specific upload limits with anonymized demo users](/img/data-collections/upload-limits-settings.png) :::info Upload limits do not grant access An upload limit controls Data-source upload allowance. It does not decide which collections a user can see, use, or edit. Configure collection visibility and team access separately through [Data governance](#doc-admin-guide-govern-data-collections-and-sources). ::: ## How the Limit Is Enforced The allowance is the combined amount of data uploaded for the user across their Data sources. When a new document would exceed the applicable limit, that document is skipped with the reason **User storage limit exceeded**. Content that has already been uploaded and processed remains available. :::caution Zero is not unlimited Saving `0` as the default or a user-specific limit prevents new documents with a positive size from being ingested. Use `0` only when you intend to stop further uploads. ::: Review the limits periodically alongside [data-storage utilization](/analytics#data). Raise them when approved ingestion work requires more capacity, and reduce obsolete exceptions when responsibilities change. ## Troubleshooting ### Upload Limits is not available - Confirm that you are in **Data** with **Admin** mode enabled. - Ask an organization administrator to verify that your role can manage users. ### Save is disabled - Enter a value different from the currently saved value. - Use a required, non-negative whole number such as `0`, `100`, or `500`. - Use the main **Save** button for the default and the disk button in the user's row for an individual limit. ### A user still cannot upload - Check the user's individual value first. - If the user has no custom value, review **Default limit**. - Confirm that the correct Save action completed successfully. - If the allowance is sufficient, verify collection access and [Manual Upload](#doc-data-manual-upload) configuration. --- # Choose a Data Source Choose the system that owns the current version. A synchronized source is better than repeated uploads when content changes; Manual Upload is better when every version must be deliberately approved. ## Decision Table | Source | Use when | Enter in Data | Avoid when | | --- | --- | --- | --- | | Manual Upload | You have a small/test set, approved snapshot, or local export | One or more files | A live folder changes frequently | | Google Drive | Google folders or Shared Drives own the live documents | Folder ID(s), recursive/shared-drive switches | The files belong to Microsoft 365 | | OneDrive | One Microsoft user owns or receives the files | Drive-relative folder path(s) | A team site/library owns the content | | SharePoint | Frequently changing team content lives in a site or document library | Exact library/folder path(s) | The files are personal OneDrive content | | Azure Storage Account | An external system or pipeline publishes large blob volumes | Blob name/path/selector | The source is an SMB-style file share | | Azure File Share | A large local/on-premises repository is exposed through Azure Files | Exact share name(s) | The source is a blob container or is not available through Azure Files | | Jira | Current project issues should be searchable | One Project Key | You need one issue or arbitrary JQL | | Confluence | One maintained space is the knowledge base | One Space Key | You need a single temporary page | | Firecrawl | An approved website has no native connector | URL, mode, limit, optional path regexes | The site is authenticated or copying is not permitted | ## Supported Files and Limits The current RAG readers explicitly support these file formats for file-based Data sources: | Content | Supported extensions | | --- | --- | | JSON | `.json` | | Text and source code | `.txt`, `.csv`, `.sql`, `.xml`, `.js`, `.mjs`, `.cjs` | | PDF | `.pdf` | | Word | `.docx` | | Excel | `.xls`, `.xlsx` | | PowerPoint | `.pptx` | | Markdown | `.md` | The **Other** file class in the app is a filter category, not a guarantee that a parser exists. Do not assume that legacy `.doc` or `.ppt` files, images, or other binary formats can be indexed. Scanned PDFs and image-heavy Office documents may require advanced content extraction; always confirm their **Indexed** and **Readable** state and inspect representative extracted text. ### Manual Upload and ZIP limits These hard limits apply to [Manual Upload](#doc-data-manual-upload), not universally to individual objects discovered by synchronized connectors: - Each uploaded file, including a top-level ZIP archive, can contain at most `200,000,000` bytes: 200 MB, or approximately 190.7 MiB. - One source-creation request can contain at most 1,000 directly selected files. - ZIP is a transport container for Manual Upload, not a searchable RAG format by itself. ZIP extraction is limited to 1,000 entries across the uploaded archives in one request, `200,000,000` uncompressed bytes per entry, and `500,000,000` uncompressed bytes in total. An entry's compression ratio cannot exceed 100:1, and its name cannot exceed 512 characters. Nested ZIP files, empty entries, unsafe paths, malformed or unreadable entries, and entries that exceed a limit are skipped. If no uploaded file or archive entry can be imported, source creation fails. ### User RAG quotas The Manual Upload per-file limit is separate from the cumulative ingestion allowance described in [Data Upload Limits](#doc-data-collections-upload-limits). The backend default is 500 MB per user, but an administrator can change the organization default or set a user-specific value. A `0 MB` allowance blocks new documents with a positive size. Advanced content extraction has a separate analyzed-page allowance. A page limit of `0`, or a blank page-limit field in the app, means unlimited analyzed pages. These allowances apply across the user's Data sources. Synchronized connectors can also be constrained by their provider and the ingestion service, so the 200 MB Manual Upload limit must not be treated as a universal per-object connector limit. See [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) for extraction and indexing checks. ## Connection Versus Data Source The connection stores authentication; the Data source stores scope. For example: ```text Connection: Support Google account (OAuth) Data source: Folder ID 1AbC..., include subfolders Collection: Customer Support — Approved Knowledge ``` Never paste API keys, OAuth tokens, Azure connection strings, or passwords into folder, blob, project, space, or URL fields. ## Quick Recommendations - Choose **SharePoint** for frequently changing team-owned documents that should synchronize from a governed site or library. - Choose **Manual Upload** for small or test file sets and for snapshots whose replacement should be deliberate. - Choose **Azure Storage Account** for large volumes delivered by external applications, exports, or automated pipelines. - Choose **Azure File Share** for large repositories originating on local or on-premises servers after they are exposed or synchronized through Azure Files. ### Automated local or on-premises feed When an internal file server remains the source of truth, use a controlled synchronization service to publish only approved content to Azure File Share. Keep uploader write access separate from the Siesta AI reader, publish metadata after files are complete, and pilot update and deletion behavior. Follow [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion). ## Choose the Collection Boundary Split collections when audience, owner, confidentiality, sync frequency, retention, or intended agents differ. Provider type alone is not the boundary: a collection may combine Jira and Confluence when they serve the same team and policy, while two Google folders may need separate collections if one is confidential. Use durable business names such as `Finance — Month-end Procedures`, then identify implementation in the source name, such as `Finance SharePoint — Approved library`. ## Source Ownership by Role Users normally choose the material, verify documents, and test answers. Admins prepare shared connections, approve collection visibility, review least privilege, choose a service identity, and own credential rotation. See [Use Sources](#doc-user-guide-upload-and-use-data-collections) and [Govern Data](#doc-admin-guide-govern-data-collections-and-sources). --- # Manual Upload Use Manual Upload for signed documents, approved snapshots, exports, and files without a supported live provider. It creates a processed copy in Siesta AI and does not remain linked to the file on the user's computer. ## Before You Start - Put files with the same audience and purpose in one collection. - Remove secrets, private keys, credential exports, and material outside the collection audience. - Resolve obsolete or contradictory versions before upload. - Use a synchronized connector instead when the source changes regularly. ## Configure the Source 1. Open **Data**, select a collection, and choose **Add data source → Manual Upload**. 2. Enter a durable **Name**, for example `Support policies — 2026 Q3`. 3. Use **Description** for owner, version, scope, and replacement policy. 4. Add at least one file under **Upload files**. 5. Review processing options only when you have a retrieval test. 6. Confirm, wait for processing, then inspect representative files and chunks. ![Manual Upload configuration form with Name, Description, file upload, Retriever, and Processing sections](/img/data/sources/manual-upload-configuration.png) *Manual Upload keeps the files and the searchable-content settings in one configuration form.* | Field | What to enter | | --- | --- | | Name | A recognizable snapshot or release name | | Description | Owner, approval date, scope, and expected replacement | | Upload files | One or more local files; at least one is required | | Retriever | Keep the defaults unless a measured retrieval test justifies changing query rewrite, ranking, or result count | | Processing | Expand to review extraction and file-processing options; change them only against representative documents | Processing can expose file classes and JSON metadata or feature settings. The current UI supports JSON, Text, PDF, Word, Excel, PowerPoint, Markdown, and Other file classes. File extension support does not guarantee good extraction: scanned PDFs, embedded spreadsheets, and image-heavy presentations must be checked after processing. See [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) before changing Retriever or Processing defaults. ## User Guidance Use Manual Upload when you deliberately control change. Include the version in the source name and ask the owner what to do with the previous source when a replacement arrives. Two conflicting versions are a common cause of inconsistent answers. ## Admin Guidance Define [Data Upload Limits](#doc-data-collections-upload-limits), collection access, retention, and who may delete or replace a source. A successful upload does not make the content safe to share. Review both the upstream document classification and the collection audience. ## Verification Open **Files** and confirm expected names, `Indexed` and `Readable` state, and extracted text. Test one fact that exists, one that is absent, and one that would expose a stale version. --- # Google Drive Data Source Use Google Drive for live folders and Shared Drives that should refresh through the permissions of a connected Google account. ## Prepare the Connection and Folder 1. Create or obtain access to a [Google Drive connection](#doc-connections-google-drive). 2. Use a team-owned identity for shared production knowledge where possible. 3. Confirm that the connected account—not only your personal account—can open every intended folder. 4. Open the folder in Drive and copy only the ID after `/folders/`. For `https://drive.google.com/drive/folders/1AbCDefGh`, enter `1AbCDefGh`, not the entire URL. ## Configure the Source | Field | What to enter | Why it matters | | --- | --- | --- | | Name | Purpose and folder, for example `Support Drive — Approved policies` | Distinguishes this import in logs and agents | | Description | Owner, scope, exclusions | Makes reviews and incident response faster | | Connection ID | The stored Google Drive connection | Selects authentication; never paste a token | | Sync frequency | On Demand, Daily, Weekly, or Monthly | Controls how quickly upstream changes arrive | | Include subfolders | Enable only when the entire tree is in scope | Recursive access can import much more content | | Include shared drives | Enable for Shared Drive content | Allows discovery beyond a user's personal drive | | Folders | One or more folder IDs | Defines the imported scope; at least one is required | ![Google Drive data-source form with connection, synchronization, scope switches, folder IDs, Retriever, and Processing](/img/data/sources/google-drive-configuration.png) *Google Drive uses folder IDs. The two switches deliberately widen discovery to subfolders or Shared Drives.* After creation, verify that shortcuts, duplicates, drafts, and archived versions did not widen the scope. A folder can process successfully while still containing the wrong documents. Keep Retriever and Processing at their defaults until representative questions show a measurable need to change them. See [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting). ## When Google Drive Is the Right Choice Choose it for Google-owned collaborative content that changes regularly. Choose Manual Upload for a signed snapshot, OneDrive for Microsoft user-owned files, or SharePoint for a governed Microsoft team library. ## User Guidance Name the collection in prompts and require source names in answers. If a file is missing, check the Folder ID, subfolder switch, Shared Drive switch, and the connected account's access before changing retrieval settings. ## Admin Guidance Prefer a dedicated identity for production sources, document token ownership, and test reauthorization. Removing a user's upstream access, OAuth consent, or employment can stop future synchronization. Shared Drive scope should be intentional and least-privileged. --- # Microsoft 365 Data Sources Siesta AI exposes separate OneDrive and SharePoint Data sources. Both use a stored Microsoft connection and accept folder paths, but they represent different ownership models. ## Choose OneDrive or SharePoint | Choose | When the content belongs to | Main risk | | --- | --- | --- | | OneDrive | One Microsoft user or files shared directly with that user | Access can disappear when the user or sharing changes | | SharePoint | A team site, department, or document library | Wrong site/library path or service-account permission | Use SharePoint for policies and shared production knowledge that should survive individual employee lifecycle changes. Use OneDrive for personal or individually owned working content. ## Prepare the Connection Create the appropriate [OneDrive connection](#doc-connections-one-drive) or [SharePoint connection](#doc-connections-sharepoint). Confirm the connected Microsoft account can open the exact folder in the intended drive, site, and library. ## Configure OneDrive | Field | What to enter | | --- | --- | | Name | Purpose and owning drive, for example `Operations OneDrive — Reports` | | Description | Owner, folder scope, and exclusions | | Connection ID | Stored OneDrive connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Folder paths | One or more paths relative to the connected drive | ![OneDrive data-source form with connection, synchronization, folder-path, and Processing fields](/img/data/sources/onedrive-configuration.png) *OneDrive accepts drive-relative folder paths and exposes Processing without the common Retriever section.* Examples: ```text Documents/Customer Onboarding Shared/Approved Reports ``` Do not enter a local path, Windows drive letter, OAuth secret, or a full browser URL in **Folder paths**. ## Configure SharePoint | Field | What to enter | | --- | --- | | Name | Purpose and site/library, for example `HR SharePoint — Policies` | | Description | Business owner, site/library, scope, and exclusions | | Connection ID | Stored SharePoint connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Folder paths | Exact library/folder path available to the connected account | ![SharePoint data-source form with connection, synchronization, folder-path, Retriever, and Processing fields](/img/data/sources/sharepoint-configuration.png) *SharePoint accepts paths within the selected site or library and exposes both Retriever and Processing.* Examples: ```text Shared Documents/Policies Shared Documents/Operations/Runbooks ``` Path spelling and the tenant's library names matter. Access inherited from an expiring share link is fragile; production sources should use explicit service-account access. ## Processing Difference The current OneDrive creation form does not expose the same Retriever controls as most other sources. SharePoint does. Document only and change the controls visible in the selected form; do not assume both Microsoft forms are identical. Use the definitions in [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) for the shared controls. ## Verification and Troubleshooting If the source returns no files, verify the selected connection, exact relative path, site/library ownership, and account permission. Then inspect **Files** and **Logs**. A technically successful run must still be checked for expected document names and readable content. --- # Azure Storage Data Sources Use Azure Storage Account for blobs and Azure File Share for named SMB-style shares. They may use the same storage account, but they are different Data sources and selectors. ## Prepare the Connection An admin first creates an [Azure Storage Account connection](#doc-connections-azure-storage-account). The credential or connection string belongs in Connections. Never paste `DefaultEndpointsProtocol=...`, an account key, or SAS secret into the Data-source selector. Prefer a read-only, container/share-scoped credential where the released connection design supports it. Record the owner and rotation process without copying the secret into descriptions or tickets. ## Azure Storage Account (Blobs) Use it for application exports, generated documents, archive feeds, and repositories published to Blob Storage. | Field | What to enter | | --- | --- | | Name | Feed and purpose, for example `Production exports — Approved PDFs` | | Description | Owner, account/container context, selector convention, exclusions | | Connection ID | Stored Azure Storage connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Blobs | One or more blob names, paths, or selectors expected by the configured source | At least one Blob value is required. The current form validates presence, not whether the selector matches readable data. Always inspect resulting files and logs. ## Azure File Share Use it for lift-and-shift repositories or operational content whose source of truth is an Azure file share. | Field | What to enter | | --- | --- | | Name | Share and purpose, for example `Operations share — Runbooks` | | Description | Owner, share scope, exclusions, and retention | | Connection ID | Stored Azure Storage connection with access to the share | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | File Shares | One or more exact Azure file-share names | ![Azure File Share data-source form showing the required connection warning, synchronization, File Shares, Retriever, and Processing](/img/data/sources/azure-file-share-configuration.png) *Create a compatible Azure File Share connection first. Until one exists, Connection ID remains unavailable and the form links to Connections.* Enter a share name such as `operations-documents`. Do not enter `/Volumes/Docs`, `Z:\\Docs`, a blob container URL, or a file path. At least one non-empty share name is required. The values describe different layers: | Value | Example | Purpose | | --- | --- | --- | | File Share name | `operations-documents` | Value entered in the Siesta AI **File Shares** field | | UNC path | `\\\\storageaccount.file.core.windows.net\\operations-documents` | Network path used when a Windows host connects to Azure Files | | Mapped drive | `Z:\\` | Local alias available only on the server where the share is mounted | Siesta AI needs the share name, not the UNC path or mapped drive. A synchronization service may use `Z:\\` locally while publishing files, but that path has no meaning to the Siesta AI source. ### Metadata and automated feeds The current Azure File Share form can pass **JSON Metadata Definitions** to the ingestion service. Use this field only with a documented and tested JSON contract. Confirm during a pilot how the deployed ingestion service discovers metadata, matches it to files or chunks, and handles invalid or missing entries. Use [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) for the shared Retriever and Processing settings. For an end-to-end pattern that copies an approved local repository into Azure Files, publishes a JSON manifest, and validates agent answers, see [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion). ## Which One Should You Use? Use the object that already owns updates: blobs for pipeline/object delivery, File Share for an SMB-style share. Do not choose File Share merely because the storage account also exposes one. ## Admin Verification After key rotation, run a controlled synchronization and verify representative documents. Split sources when account/container/share ownership, audience, retention, or schedule differs. A successful status without expected files is not an acceptance test. --- # Automated File Ingestion with Azure File Share Use this pattern when approved documents originate on a local or on-premises file server and must reach Siesta AI automatically. A synchronization service publishes a controlled copy to Azure File Share. Siesta AI then reads that share into a Data collection for an agent. This is an integration pattern, not a new API. The exact metadata-to-document joining behavior must be confirmed in a pilot with the deployed ingestion service. ## Architecture ```text +------------------+ | Internal share | | Source of truth | +--------+---------+ | v +------------------+ | Sync service | | Filter and copy | +--------+---------+ | v +------------------+ | Azure File Share | | Landing zone | +--------+---------+ | v +------------------+ | Siesta AI | | Data collection | +--------+---------+ | v +------------------+ | Agent | | Answers + sources| +------------------+ ``` The synchronization service and Siesta AI use separate access paths: - The **synchronization identity** writes approved files and metadata to Azure File Share. - The **Siesta AI Connection** reads the same share for ingestion. Do not give Siesta AI write access merely because the uploader requires it. Do not place the uploader credential in the Siesta AI Data-source fields. ## Responsibilities | Role | Responsibility | | --- | --- | | Document owner | Approves folders, file types, exclusions, status values, retention, and deletion behavior | | Azure administrator | Creates the Storage Account and share, configures networking, identity-based SMB access, RBAC, ACLs, logging, and credential rotation | | Synchronization operator | Runs the trusted sync service, applies filters, publishes files and metadata atomically, and monitors transfer failures | | Siesta AI administrator | Creates the Connection, Data collection, and Azure File Share source; sets access and sync frequency; validates ingestion | | Agent owner | Assigns the collection, defines citation and absent-answer behavior, runs evaluation tests, and monitors answer quality | One person may hold several roles, but each responsibility still needs a named owner and a backup. ## Phase 1: Prepare the Azure Landing Zone 1. Create or select an Azure Storage Account that supports Azure Files. 2. Create a dedicated file share for the ingestion boundary. 3. Choose a stable share name, such as `approved-documents`. 4. Restrict network access to the trusted sync host and the approved Siesta AI ingestion path. 5. Enable Azure diagnostic logging and define retention. 6. Define separate uploader and reader identities. Prefer identity-based SMB authentication. Grant the synchronization identity the `Storage File Data SMB Share Contributor` role at the narrowest practical scope and apply matching file and directory ACLs. The role allows share-level access; ACLs control access inside the share. Follow the Microsoft guidance for [Azure Files share-level permissions](https://learn.microsoft.com/en-us/azure/storage/files/storage-files-identity-assign-share-level-permissions). The Siesta AI reader should receive only the access required by the deployed Connection design. If the current integration uses a Storage Account connection string, treat it as a broad secret, store it only in Connections, rotate it, and never copy it into a source description or selector. ## Phase 2: Mount the Share on a Trusted Windows Server Run the sync process on a managed server that can read the internal repository and reach Azure Files. Azure Files SMB access requires outbound TCP port 445. Test the route before troubleshooting credentials. ### Portal-assisted mount 1. Sign in to the Azure portal. 2. Open **Storage accounts**, select the target account, then open **Data storage > File shares**. 3. Select the ingestion share and choose **Connect**. 4. Select **Windows**, choose a drive letter such as `Z:`, and select the approved authentication method. 5. Copy the generated PowerShell command. 6. Open PowerShell as Administrator on the trusted server and run the command. 7. Confirm that the share is available in File Explorer and that the sync identity can create, replace, and remove a test file within its approved folder. See Microsoft's [Windows Azure Files mount guide](https://learn.microsoft.com/en-gb/azure/storage/files/storage-how-to-use-files-windows) for current prerequisites and commands. ### Do not confuse these values | Value | Example | Where it is used | | --- | --- | --- | | Azure File Share name | `approved-documents` | **File Shares** in the Siesta AI Data source | | UNC path | `\\\\storageaccount.file.core.windows.net\\approved-documents` | Windows SMB access and mount commands | | Mapped drive | `Z:\\` | Local path used by the sync service on that server | | Internal source path | `\\\\fileserver\\departments\\manuals` | Upstream path read by the sync service | Enter only the exact share name in the Siesta AI **File Shares** field. Do not enter `Z:\\`, a UNC path, a folder inside the share, or a Blob Storage URL. ### Account-key fallback A Storage Account key can be used when identity-based SMB access is not available, but it is a less secure fallback. The key grants broad access as the Storage Account identity, bypasses individual user authorization, and must be protected and rotated. Do not interpret a user's Azure RBAC assignment as effective SMB access when the mount authenticates with an account key. ## Phase 3: Select and Synchronize Files The sync service must publish a curated dataset, not mirror every accessible file. ### Selection policy - Allow only approved root folders and file types. - Exclude drafts, temporary files, archives, obsolete folders, backups, and unsupported formats. - Reject files outside the approved audience or confidentiality boundary. - Preserve stable relative paths or stable document IDs across updates. - Update an existing document instead of creating a duplicate for every run. - Define whether a removed upstream file is deleted, marked deprecated, or retained for a fixed period. - Write an operational log with run ID, start/end time, counts, bytes, skipped items, removals, and errors. Never log secrets or document contents. Start with a whitelist, for example: ```text Approved roots: \\fileserver\departments\manuals\approved File types: .pdf, .docx, .xlsx, .pptx, .md, .txt Excluded names: ~$*, *.tmp, *.bak Excluded paths: drafts, archive, obsolete, temp ``` ### Atomic publishing Siesta AI must not ingest a half-written batch. Upload each file under a temporary name or staging path, validate its size or checksum, then atomically rename or move it to the final path. Publish the completed metadata manifest only after all documents in the batch are ready. If atomic rename is not available in the selected implementation, publish to a versioned staging folder and switch a tested release pointer or equivalent deployment boundary only after validation. ## Metadata Contract Use JSON as the canonical metadata format because the Azure File Share form exposes **JSON Metadata Definitions**. CSV may exist upstream, but the synchronization process must convert it to the supported JSON contract unless the deployment explicitly supports CSV. The following sidecar manifest is an integration contract. Confirm during the pilot how the deployed ingestion service discovers the manifest, joins entries to files or chunks, validates unknown fields, and handles missing entries. ```json { "schema_version": "1.0", "generated_at": "2026-07-21T08:30:00Z", "documents": [ { "document_id": "operations-boiler-startup-v3", "file_path": "manuals/operations/boiler-startup.pdf", "source_path": "\\\\fileserver\\operations\\approved\\boiler-startup.pdf", "title": "Boiler Startup Procedure", "category": "Operations", "owner": "Operations Engineering", "version": "3.0", "status": "approved", "last_modified": "2026-07-20T14:05:31Z", "confidentiality": "internal", "tags": ["boiler", "startup", "safety"] } ] } ``` ### Field definitions | Field | Requirement | | --- | --- | | `document_id` | Required, stable, unique identifier. Keep it unchanged when the same logical document receives a new version. Do not derive it from a temporary filename. | | `file_path` | Required path relative to the root of the Azure File Share, using `/` separators. It must resolve to exactly one published file. | | `source_path` | Original internal path for audit and troubleshooting. Do not expose it in user-facing citations unless approved. | | `title` | Human-readable document title used for review and, when supported, citations. | | `category` | Controlled business category, not an arbitrary folder dump. | | `owner` | Team or role accountable for content accuracy. Prefer a durable group name over a personal email. | | `version` | Source-controlled version string. Use one convention consistently. | | `status` | Lifecycle state. Recommended values: `approved`, `deprecated`, `archived`, `draft`. Only explicitly approved values should be ingestible. | | `last_modified` | Source modification time in RFC 3339 format, including timezone, such as `2026-07-20T14:05:31Z`. | | `confidentiality` | Controlled classification such as `public`, `internal`, `confidential`, or an organization-approved value. | | `tags` | JSON array of normalized search and governance labels. Use stable terms and avoid duplicates that differ only by case. | Validate the manifest before publication. Reject duplicate `document_id` values, missing files, absolute `file_path` values, invalid timestamps, unsupported statuses, and classifications that do not match the target collection. ## Phase 4: Configure Siesta AI 1. Ask an admin to create an [Azure Storage Account Connection](#doc-connections-azure-storage-account) with read access to the landing zone. 2. Create a collection with a business name, owner, audience, and retention policy. 3. Add **Azure File Share** as the Data source. 4. Select the prepared Connection. 5. Enter the exact Azure File Share name under **File Shares**. 6. Choose an initial **On Demand** sync frequency for the pilot. 7. Add and test **JSON Metadata Definitions** only according to the deployed ingestion contract. 8. Run ingestion, then inspect Files, chunks, status, and Logs. 9. Assign the collection to a test agent before any production agent. The local Siesta AI application and backend confirm that `JSON Metadata Definitions` are passed into Azure File Share source creation. They do not by themselves prove how an external RAG service joins a sidecar manifest to every chunk. Treat that behavior as unverified until the pilot demonstrates it. ## Phase 5: Pilot, Monitor, and Release Run the following tests in an isolated collection: | Test | Expected result | | --- | --- | | New approved file | One readable, indexed document appears with the expected title and source | | Updated file with the same `document_id` | The new content replaces or versions the logical document without an unintended duplicate | | Draft or excluded path | The file is skipped and recorded in the sync log | | Removed source file | The documented delete, deprecate, or retain policy is applied | | Malformed metadata | The batch or entry fails safely with a useful non-secret error | | Empty share | The run completes safely and does not erase valid production content unless explicitly designed to do so | | Known-answer question | The agent answers from the collection and cites a traceable document | | Absent-answer question | The agent states that the answer is not in the collection instead of guessing | | New source version | After synchronization, the agent uses the new approved version | Before production, record the baseline document count, excluded count, last successful run, expected schedule, owners, alert recipients, recovery procedure, credential rotation procedure, and deletion semantics. Monitor both halves of the pipeline: - **Sync service:** source scan failures, rejected files, transfer errors, manifest validation, duration, and last successful publication. - **Siesta AI:** source status, last and next sync, indexed/readable files, processing failures, retrieval quality, citations, and access/audit events. Pause or detach the collection if the landing zone contains unapproved data, metadata no longer matches files, a deletion causes unsafe answers, or the agent cites an obsolete version. --- # Jira and Confluence Data Sources Use Jira when project issues are the source of truth. Use Confluence when maintained pages in one space are the source of truth. Both require an Atlassian connection, but their Data selectors are different. ## Prepare the Connection Create a [Jira connection](#doc-connections-jira) or [Confluence connection](#doc-connections-confluence) with site URL, account email/username, and API token. For shared production knowledge, use a service account that can read only the required projects or spaces. Credentials belong in Connections. Data receives only a Project Key or Space Key. ## Jira | Field | What to enter | | --- | --- | | Name | Purpose and project, for example `SUP — Support issues` | | Description | Project owner, issue scope, audience, and exclusions | | Connection ID | Stored Jira connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Project Key | One project key, for example `SUP` or `ENG` | ![Jira data-source form with connection, synchronization, Project Key, Retriever, and Processing fields](/img/data/sources/jira-configuration.png) *Jira scopes one source by Project Key and exposes the common Retriever and Processing sections.* Do not enter `SUP-123`, a board name, project display name, URL, or JQL. One source accepts one project key. Split projects when audience or retention differs. Use Jira ingestion instead of CSV exports when current issue descriptions and changes should remain searchable. ## Confluence | Field | What to enter | | --- | --- | | Name | Purpose and space, for example `HELP — Product help` | | Description | Space owner, official content scope, and exclusions | | Connection ID | Stored Confluence connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Space Key | One short space identifier, for example `HELP` | ![Confluence data-source form with connection, synchronization, Space Key, and Processing fields](/img/data/sources/confluence-configuration.png) *Confluence scopes one source by Space Key and does not show the common Retriever section.* The Space Key is not a page ID or full URL. In the current form, the selected connection determines which space value is available. Confluence does not expose the same chunking and Retriever controls as most other creation forms. For the settings that are available, use [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) as the common reference. ## User Guidance Keep Jira and Confluence in one collection only when they share audience and purpose. In prompts, distinguish issue evidence from maintained documentation and require document or issue names in answers. ## Admin Guidance Re-test after service-account permission changes or token rotation. Atlassian permissions limit upstream reading, while collection and agent access form additional distribution boundaries after ingestion. --- # Firecrawl Data Source Use Firecrawl for a public or explicitly approved website when no native connector owns the content. It can scrape one page or crawl a bounded section; it must not be used to bypass authentication or content policy. ## Prepare the Connection Create a [Firecrawl connection](#doc-connections-firecrawl) with an API key and API URL, typically `https://api.firecrawl.dev`. Approve the target domain and confirm that retrieval and reuse are permitted. ## Configure the Source | Field | What to enter | | --- | --- | | Name | Domain and purpose, for example `Public product docs — Current` | | Description | Owner, approved domain/path, exclusions, and review date | | Connection ID | Stored Firecrawl connection | | Sync frequency | On Demand, Daily, Weekly, or Monthly | | Scrape type | `Scrape` for one page; `Crawl` for a bounded section | | Scrape URL | Complete valid `https://` starting URL | | Limit | Integer of at least 1; current app default is 10000 | | Include paths regex | Optional allowed path expression, for example `^/docs` | | Exclude paths regex | Optional blocked expression, for example `^/docs/archive` | ![Firecrawl data-source form with connection, synchronization, scrape type, and starting URL](/img/data/sources/firecrawl-configuration.png) *The upper part of the Firecrawl form selects the stored connection, schedule, mode, and starting URL.* Start with a small limit, inspect results, then increase deliberately. The high application default is a ceiling, not a recommended starting value. Example: ```text Scrape type: Crawl Scrape URL: https://example.com/docs Limit: 50 Include paths regex: ^/docs Exclude paths regex: ^/docs/(archive|preview) ``` ## Scrape or Crawl Use **Scrape** for a stable policy page, landing page, or one exact URL. Use **Crawl** for a documentation tree with consistent paths. Exclude login, logout, search, calendar, preview, archive, account, and query-variant routes. ![Firecrawl Scrape type selector showing Scrape and Crawl options](/img/data/sources/firecrawl-scrape-type.png) *Choose Scrape for one URL or Crawl for a bounded site section.* ![Firecrawl crawl-scope fields for limit and include or exclude path regular expressions](/img/data/sources/firecrawl-crawl-scope.png) *For a crawl, constrain volume and paths before changing Retriever or Processing settings.* Do not crawl authenticated apps, personal dashboards, customer portals, staging systems containing private data, or websites you are not allowed to copy. Firecrawl being technically able to fetch a URL is not approval to ingest it. ## Verify the Result Check representative pages, expected exclusions, duplicate titles, navigation-only content, and old versions. Narrow regexes and lower the limit before tuning retrieval. Broad input scope cannot be repaired reliably by the agent prompt. See [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) for the shared Retriever and Processing controls. --- # Processing, Sync, and Troubleshooting Source scope decides what enters the collection. Processing decides how it becomes searchable. Retrieval decides which chunks reach an agent. Change defaults only against a repeatable evaluation set. ## JSON Features and JSON Metadata Definitions When a Data source imports JSON, these two settings describe the role of named fields: | Setting | Practical question | Recommended use | Typical keys | | --- | --- | --- | --- | | **JSON Features** | From which content should the AI draw? | Meaningful text that should support retrieval and answers | `title`, `description`, `summary`, `content`, normalized comment text | | **JSON Metadata Definitions** | How should the system identify, classify, or potentially filter the document? | Stable identifiers and controlled classification values | `id`, `category`, `author`, `language`, `createdAt`, `customerId` | The fields are available in the current creation forms for Manual Upload, Google Drive, OneDrive, SharePoint, Azure Storage Account, and Azure File Share. Do not put the same key in both lists without a specific reason and a retrieval test. ### Prepare the JSON contract Before configuring either list, collect: - one to three representative JSON objects, - examples of questions that users will ask, - the classifications or filters they expect to use, - examples of nested, optional, or structurally inconsistent objects. Prefer concise text with business meaning for features and stable, normalized scalar values for metadata. Exclude binary content, access tokens or signed URLs, internal processing values, duplicated text, and large objects without a clear retrieval benefit. Nested objects, arrays, missing values, and a key that changes data type between records require a stable upstream contract. Flatten nested values into documented keys, normalize dates and identifiers, and combine useful arrays or comments into a deliberate text field when necessary. Do not assume that an untested nested path will be interpreted as intended. ### Example configuration Consider this representative object: ```json { "id": "policy-1042", "title": "Password reset policy", "summary": "Rules for resetting an employee account password.", "content": "After a reset, the employee must create a new password and confirm multifactor authentication.", "category": "Identity", "author": "Security Operations", "language": "en", "createdAt": "2026-08-01T09:30:00Z", "_etag": "internal-revision-value" } ``` Recommended values: ```text JSON Features: title, summary, content JSON Metadata Definitions: id, category, author, language, createdAt ``` | Key | List | Reason and expected effect | | --- | --- | --- | | `title` | Features | Adds the document's subject and terminology to searchable content. | | `summary` | Features | Supplies a concise description that can improve retrieval for broad questions. | | `content` | Features | Contains the facts from which answers should be produced. | | `id` | Metadata | Provides a stable identifier for the logical record. | | `category` | Metadata | Classifies the record for review and intended category filtering. | | `author` | Metadata | Records the accountable source or team. | | `language` | Metadata | Provides a normalized language classification for intended filtering. | | `createdAt` | Metadata | Preserves a sortable, normalized timestamp when the RAG service supports it. | | `_etag` | Neither | It is an internal processing value with no user-facing retrieval benefit. | This split should support a content question such as “What must an employee do after a password reset?” and is intended to support a filter such as “Identity documents in English.” Test both behaviors against the deployed RAG service before relying on them. :::info Confirmed backend behavior The frontend presents both settings as repeatable lists of field names and removes entries whose content is only whitespace before creating the Data source. The application backend does not verify that a name exists in the imported JSON and passes the received lists unchanged to the RAG client's `JsonFeatures` and `MetadataDefinitions` properties. The application backend sends these values during Data-source creation. It does not store them separately in its own database, return them in the current Data-source detail, or accept them through the current update endpoint. Define and test the lists before creating a production source. ::: :::caution RAG behavior must be verified The application and backend do not establish exactly how the separate RAG service indexes selected features, applies metadata filters, resolves nested paths, handles missing or mixed-type values, or resolves a key present in both lists. Treat the recommendations above as a qualified starting point. Pilot representative records, inspect extracted documents and chunks, and test at least one content question and one intended metadata filter. ::: ## Shared Connected-Source Fields Every integration-backed source requires **Name**, optional **Description**, **Connection ID**, and a sync frequency. Connection ID is a selector for stored authentication; it is never a field for a secret. ## Sync Frequency | Frequency | Use for | | --- | --- | | On Demand | Signed policies, reviewed releases, quarterly exports | | Daily | Operational documentation, active projects, changing shared folders | | Weekly | Maintained but non-urgent knowledge | | Monthly | Slow-moving archives and reference material | Manual Upload has no upstream system to synchronize. Faster is not automatically better: it uses provider and processing capacity and makes unreviewed upstream changes available sooner. ## Retriever Settings Most forms expose **Skip query rewrite**, **Skip LLM ranking**, and **Maximum result count** (validated from 1 to 15). Query rewrite can improve conversational recall; skipping it can help exact identifiers. LLM ranking can improve relevance at additional latency. Keep defaults until measured tests justify a change. OneDrive and Confluence do not expose the same Retriever section in the current creation UI. ## Processing Settings Depending on the source, the UI exposes file-type filters, advanced extraction, [JSON Features and JSON Metadata Definitions](#json-features-and-json-metadata-definitions), chunking strategy, vector size, and quantization. Current forms default vector size to 3072 and quantization to None. - Jira and Firecrawl do not expose file-type filtering. - Confluence does not expose a chunking selector. - Manual Upload hides chunking selection in the current form. - OneDrive omits the common Retriever section. Advanced extraction can help tables, layout, and images but must be tested on representative files. Vector or chunking changes can require reprocessing and invalidate earlier quality comparisons. ## Inspect Before Production Use **Overview** for schedule, totals, last and next sync; **Files** for document, indexed, and readable state; **Logs** for run outcomes; and document detail for extracted chunks. Test: 1. a known present answer, 2. a known absent answer, 3. conflicting versions, 4. a recently changed item, 5. an expected exclusion. ## Troubleshooting Matrix | Symptom | Check first | | --- | --- | | Connection ID is empty | Compatible connection exists and is visible or shared correctly | | Successful source contains zero files | Selector/path/key spelling, account permission, supported file types | | Google folder missing | Folder ID, Shared Drive/subfolder switches, connected account access | | Microsoft folder missing | Exact relative path, correct drive/site/library, account access | | Azure source empty | Blob selector or exact share name, credential validity | | Jira or Confluence empty | Project/Space Key and service-account permission | | Firecrawl contains irrelevant pages | Narrow include regex, add exclusions, lower limit | | Document exists but is not retrieved | Indexed/Readable state, chunks, agent assignment, retrieval settings | | Scheduled refresh stopped | Connection health, token expiry, Logs, schedule, provider quota | ## Incident Response If incorrect content creates material risk, detach or disable the collection from production agents, preserve non-secret diagnostic evidence, identify whether the cause is permission, selector, sync, extraction, indexing, or retrieval, fix it on a test agent, and re-run the evaluation set before restoration. --- # Connections Management import NavCardGrid from '@site/src/components/NavCardGrid'; import {LayoutGrid} from 'lucide-react'; # Connections Connections represent the central place where all integrations of the Siesta AI platform with external services are managed, whether they are action tools, knowledge libraries, or the AI models themselves. Thanks to this section, administrators have an immediate overview of what resources are available and can add, modify, or remove them with just a few clicks. By integrating a new service, it immediately appears throughout the system and can be assigned directly when creating or modifying an agent. The Connections section is used to work with external systems. Connections allow Siesta AI to link with third-party tools (APIs, SaaS platforms, internal systems) so that agents and workflows can read data, write changes, or trigger actions. ## How It Works - **Management**: In the Connections section, you activate a specific connection, set access (OAuth / API key), and assign it to agents or workflows. - **Usage**: Connection actions are called from prompts, tools, or automations (e.g., send an email, retrieve data from CRM). - **Security**: Access tokens are stored in encrypted form, and all operations are fully audited. Released connections can cover several practical families at once: - business SaaS tools such as Jira, Confluence, Slack, HubSpot, and Gmail, - Microsoft and Google document/data access such as OneDrive, SharePoint, Drive, Word, and Excel, - repository and engineering tooling such as GitHub and Azure DevOps, - model and infrastructure connections such as OpenAI and Azure AI Foundry. ## Overview of the Connections Section - A search field at the top for quick filtering of connections. - A table with columns: **Name**, **Type**, **Created**, **Access** + actions on the right (menu **...**). - A **Add Integration** button to create a new connection. - Examples of available connections: Jira, Confluence, Azure DevOps, GitHub, OneDrive, SharePoint, Clockify, OpenAI, Azure AI Foundry, Office 365 Word, Office 365 Excel, and Outlook Calendar. ![Overview of Connections](/img/connections/connections-list.png) ![Connection Detail](/img/connections/connection-detail-scopes.png) In the detail of individual connections, permission scopes and allowed functions can be set. Administrators specify which actions are available, whether they require confirmation, and what access the connection has (shared or private). ## Connection Governance Connection governance defines which integration types and functions are available across the organization. It is managed as part of organization security and affects agents, workflows, and tool execution behavior. Governance has two levels: - **Connection type policy** controls whether a whole connection type is enabled or disabled for the organization. - **Function override** controls individual functions inside a connection type when the connection supports function-level governance. Function access modes are: - **Disabled** - agents and workflows cannot use the function. - **Enabled** - the function can run when the agent or workflow has access to the connection. - **EnabledWithConfirmation** - the function is available, but execution must be approved before it continues. Use stricter governance for data-modifying functions, such as sending emails, creating tickets, updating CRM records, writing files, or triggering external workflows. Read-only functions can often be enabled with lower risk, but they should still follow the principle of least privilege. Connection access still matters: - **Private** connections are available only to their owner unless explicitly assigned where supported. - **Shared** connections can be reused by multiple users, agents, or workflows according to access rules. Governance and access work together. A user may have access to a connection, but a disabled function remains unavailable. A function set to confirmation can be proposed by an agent, but it appears in [Tool Executions](/tool-executions) as waiting for approval before it runs. ## Token Limits Some AI/model connections include **Token limits**. Open the connection detail and choose the token limits view to define daily and weekly token budgets for that connection. Token limits can be managed at several levels: - **Organization defaults**: baseline daily and weekly limits for the connection. - **User limits**: overrides for individual users who need tighter or broader budgets. - **Team limits**: overrides for teams that share a specific workflow or operational budget. Limits are configured in millions of tokens. Leaving a field empty means that no explicit limit is set for that period at that level. User and team limit records can also be disabled when an override should exist but not currently apply. ![LLM token limits](/img/analytics/llm-token-limits.png) Use token limits when: - one shared model connection is available to many users, - a team runs high-volume research or automation, - a pilot workflow should have a predictable budget, - admins need to prevent accidental overuse without removing access. When a configured budget is exceeded, the conversation should stop with a clear token-limit message instead of a generic model failure. Token limits are preventive guardrails. Use [Analytics](/analytics) Cost charts to understand historical input, output, reasoning, model, and agent token trends, then adjust organization, user, or team limits to match the expected operating budget. For Azure AI Foundry model router deployments, configure Siesta AI limits on the model connection that points to the router deployment. Treat the router as one shared budget boundary in Siesta AI, then use Azure Monitor and Azure Cost Management when you need to inspect the distribution across underlying models. See [Azure AI Foundry Model Router](#doc-connections-azure-ai-foundry-model-router). ## Adding a New Connection After clicking on **Add Connection**, a dialog opens with a search field and a list of available connections (e.g., Gmail, Google Calendar, Google Drive, Slack App, OpenAI). Depending on the selected type of connection, the user is redirected to the provider's page, where they must allow Siesta AI access to the service. After successful confirmation, the user is prompted to name their new connection. After entering the name and confirming, the new connection is added. Available connection types depend on the released tool surface and tenant configuration. In current dev releases, the catalog can include both classic business tools and operational helpers such as GitHub and Azure DevOps repository automation, Clockify work tracking, document and spreadsheet generation, calendar access, analytics, and website-performance integrations. ![Adding a Connection](/img/connections/connections-add-connection.png) --- # Memory The Memory section serves as a central knowledge base for your entire organization. It represents long-term memory where you can store strategic documents, processes, product knowledge, or specific know-how. You can then attach these documents to individual [Agents](#doc-agents), and they can actively use them when generating responses. When enabled for an agent, Platform Tools can also help create and maintain Memory content. For example, an agent can gather approved public information from a website, combine it with internal instructions or a skill, and draft structured Memory pages about the company, products, strategy, terminology, or operating procedures. This turns one-time research into reusable knowledge that other agents can use later. Use this capability deliberately: generated Memory should be reviewed by a responsible user before it becomes a trusted source for production agents. Memory access now has two parts at the agent level: - **Memory read**: the agent can use attached collections and pages as retrieval context. - **Memory write**: the agent can create or update Memory content while it works. This split lets teams attach trusted Memory for answers without automatically allowing the agent to change that Memory. The screenshot shows the Product memory collection opened on the **Core Concepts** page. The left panel contains the collection selector, sharing status, collection actions, and the page tree. The main editor shows the selected page with formatting controls for headings, lists, links, tables, undo/redo, and code view. Use this view to maintain structured product knowledge that agents can retrieve later. The current Memory UI keeps the collection sidebar visible while moving between a collection overview and a specific page. This makes it easier to stay oriented when editing larger collections with nested pages. ![Memory section interface](/img/memory/memory-product-core-concepts.png) ## Collections and Structure Knowledge in Memory is organized into **Collections**, which function as thematic folders. Collections allow you to logically separate data for different teams or projects (e.g., Marketing, Sales, HR). You can find the collection menu in the top right corner in the dropdown. After clicking this menu, you will see all the collections you currently have access to and the button **Create new collection**. After selecting it, you will enter the name of the collection, and confirming it will create the collection. - **Creating a collection**: Allows you to group related documents under one name. - **Sharing**: Collections can be private or shared within a team or the entire organization. - **Management**: Each collection has controls for setting permissions (shield icon), editing the name (pencil icon), and deleting the collection (trash icon). Opening a collection takes you to `/internal/memory/[collectionId]`. This route represents the selected collection and shows its page tree. Use collection-level controls for permissions and collection management; use page-level controls for content changes. The collection route is also the fallback view when no specific page is selected. From there, users can pick a page from the sidebar without losing the surrounding collection context. ## Pages and Nesting Within each collection, you can create individual **Pages**. The platform supports a hierarchical structure, meaning that pages can be nested within each other (creating subpages). - **Creating a new page**: Using the page icon with a plus sign, located above the list of existing pages. - **Nesting**: By hovering over an existing page, clicking on the three dots icon, and selecting the **New subpage** button, you can build complex wiki systems or structured manuals. - **Deleting a page**: In the same menu as creating a subpage, there is also an option to delete the page. Opening a page takes you to `/internal/memory/[collectionId]/[pageId]`. The URL identifies both the collection and the selected page, so a page always belongs to a specific collection. Because the route includes both ids, links to Memory pages are more stable for direct navigation, reviews, and handoff between users working in the same collection. Recommended structure: - keep top-level pages broad and stable, - use subpages for procedures, product notes, policies, or project-specific details, - avoid mixing unrelated teams or topics in one collection, - keep page names short enough to scan in the tree. ## Content Editor When selecting any page, a text editor opens on the right side of the screen, allowing users to format knowledge so that it is understandable and clear for agents and users. - **Changing the page title**: After clicking on any page, you can edit its title by clicking on it above the text editor. - **Formatting**: Support for headings (H1–H6), bold text, italics, underline, lists (bullets, numbering), and undo/redo options. - **Links and code**: Ability to insert hyperlinks or code blocks for technical documentation. - **Saving**: after editing content, wait until the editor has saved before navigating away. **Tip:** For effective agent functioning, we recommend keeping pages in Memory clearly structured using headings and bullet points, which facilitates semantic searching of the data. Use headings to create sections that agents can retrieve accurately. Prefer short factual paragraphs over long mixed notes. ## Sidebar and Ownership Context The sidebar is the main navigation surface for Memory work. It can show: - the current collection, - the collection owner, - sharing status, - page tree actions, - collection-level actions such as rename, permissions, or delete. Collection ownership matters when multiple teams maintain different knowledge areas. Before editing or sharing a collection broadly, verify that the displayed owner and sharing mode match the intended governance. ## Linking with Agents For practical use of the Memory section, it is necessary to link specific collections or pages with particular Agents. - **Contextual responses**: If a specific collection or page from Memory is assigned to an agent, it will first search these sources for every query. - **Timeliness**: Any changes made in the Memory section will immediately reflect for all agents using that source. Therefore, it is not necessary to reconfigure individual agents. - **Sourcing**: An agent can draw facts from this data or use specific terminology from your company. ## Example Use - On the page, you can define, for example, **Company contacts** (see the image above), where you will structurally describe the company's employees, their positions, and contacts. - Thanks to this knowledge, Agents to whom you attach this page will know the structure of your company and assist employees in contacting colleagues, thereby saving their time. - In the case of a new employee joining, there is no need to rewrite the data for each Agent separately; it is enough to update the information only on the given page in the Memory section (the "Single Source of Truth" strategy). --- # Library The Library in Siesta AI contains reusable agent templates. They allow you to save an agent's configuration (model, behavior, connected tools) and quickly create new instances from it. The Library enables users to choose from prepared templates that serve as a starting point for creating new AI agents. Templates contain preset parameters, logic, data access, and integrations, simplifying the repeated deployment of frequently used configurations. ![Overview of templates](/img/templates/templates-overview.png) Templates address three things: - Standardization of work - Sharing know-how (community vs. private) - Rapid deployment of new agents - Controlled organization-wide reuse ## Basic Concept A template is not a running agent. It is a blueprint that only defines how an agent should be created. From one template, you can create: - 1 agent - 10 agents - 100 agents ## Saving an Agent as a Template Action: **Save As Template** A template is created from an existing agent configuration. Procedure: 1. The user clicks on **Save As Template** in the agent settings. 2. A modal window opens where the user fills in: - **Name** - template name - **Description** - purpose description ![Modal for saving template](/img/templates/template-save-modal.png) 3. Confirming will save the template. 4. The saved template appears in the Library with the current template cards, categories, search, and tabs. ![Current templates page](/img/templates/templates-overview.png) What gets saved: - Name and description - Model (e.g., gpt-5) - Behavior parameters (temperature, penalties, max length) - Shared Tools (e.g., Jira, GoogleSearch, HubSpot) - Private Tools (if any) The template does not save runtime state or conversation history. ## Shared Tools vs. Private Tools **Shared Tools** - Tools available at the workspace or organization level - Automatically connected when creating an agent after being saved in a template **Private Tools** - Tools specific to a user or project - The template remembers their reference, but the user must have permissions - If permissions are missing, agent creation will fail ## Creating an Agent from a Template Action: **Create agent** After selecting a template, a detailed overview of the configuration is displayed: - Template ID - Name and description - Used model - Behavior settings - List of connected tools + status (Already connected) ![Creating an agent from template](/img/templates/template-create-agent.png) ## Library ### Tabs **Community Templates** - Publicly available templates - Created by the team or community - Read-only (cannot be edited) - Suitable as best practices or starting points **Organization Templates** - Shared within the current organization - Intended as approved internal starting points for repeated use - Governed by template access policy instead of being globally public - Suitable for onboarding, internal standards, and team-specific operating patterns **My Templates** - Templates created by the user - Can be deleted, edited, and reused ![Tabs, categories, and template cards](/img/templates/templates-overview.png) ## Access Policy and Governance Templates can now use an access policy similar to other governed workspace objects. - Use **private** access when a draft template is not ready for broader reuse. - Use **organization** access when the template should be available to other users in the workspace. - Limit write access to owners or designated maintainers when the template defines a standard operating pattern. Users who can read a template can use it as a starting point for a new agent. Users who can write a template can update its configuration and access policy for the intended audience. ## Visualization of Templates Each template is displayed as a card containing: - Name - Short description - Icons of connected tools The card allows for a quick visual check of what the template contains before use. ## Typical Use Cases - Work agent: one template -> dozens of internal agents with the same behavior - Onboarding: new team member = quick creation of an agent without manual configuration - Best practice enforcement: template as the only allowed entry point - Organization standard: one approved internal template -> many teams start from the same governed baseline - Community sharing: verified configurations without sharing sensitive data ## Summary The Library in Siesta AI is a controlled way to scale agents. Its templates allow for sharing know-how, maintaining standards, and speeding up work without compromising security. --- # Profile The Profile section is used to manage your personal account information, linked login providers, and account security. Opening `/internal/profile` redirects to the **Account** tab. Current tabs: - **Account** - **Security** ## Account Information Use the **Account** tab to edit basic profile information: - **First Name** and **Last Name** - **Email** (login address) - **Phone Number** You can save changes by clicking the **Save Changes** button. If you want to discard the edits, use **Cancel**. ### Linked Accounts The **Linked Accounts** section shows which external login providers are connected to the account, such as Google or Microsoft. Connected providers can be linked or unlinked from this tab. ![Profile Information and Linked Accounts](/img/profile/profile-details.png) ## Security Use the **Security** tab for actions that affect account access. ### Change Password The **Change Password** section requires: - **Current Password** - **New Password** - **Confirm Password** On the right is an overview of the password requirements that need to be met (e.g., at least 8 characters, at least one lowercase letter, and at least one number/symbol/space). ### Delete Account To deactivate the account, you must check **Confirm Account Deactivation** and then confirm by clicking the **Deactivate Account** button. This action affects your own user account. Organization-level user lifecycle and admin actions are managed from [Users](#doc-users). ![Change Password and Delete Account](/img/profile/profile-security.png) --- # Organization import NavCardGrid from '@site/src/components/NavCardGrid'; import {CreditCard, KeyRound, Settings, ShieldCheck} from 'lucide-react'; # Organization Use **Organization** to manage workspace-wide settings for Siesta AI. This area is for owners and admins who need to review subscription details, create API keys, configure SSO, set organization defaults, and control tenant-level security behavior. Organization is organized into the same tabs as the application: The separate administration pages for [Users](#doc-users), [Roles](#doc-roles), [Teams](#doc-teams), [Audit log](#doc-audit-log), and [Security Center](#doc-security) remain standalone sections. Use them when you need to manage people, permissions, team membership, audit history, or security findings rather than the organization configuration form itself. If you need to manage AI/model token budgets, open [Connections](#doc-connections). Organization focuses on workspace-level administration and security defaults. --- # General The **General** tab contains the organization’s plan, usage, and identity details. It is the first place to confirm which workspace you are administering. Use General to review: - the current organization plan and billing entry point, - free-token usage when it applies to the plan, - the organization name, - the organization ID used by API clients and support workflows. The organization ID should be treated as an identifier, not as a secret. API authentication still requires a valid API key and the appropriate access permissions. ![General tab with subscription and usage information](/img/organization/organization-general-tab.png) User membership, teams, API keys, feature availability, and security policy are managed in their dedicated pages or Organization tabs. --- # Api Keys Use **Api Keys** when an external system needs to call Siesta AI without an interactive user login. Typical examples include backend integrations, scheduled jobs, and internal services that use the external API. An API key belongs to the organization and records the user who created it. The table lets administrators: - search keys by name, - create a named key, - review its creation time and creator, - reveal or copy its value when configuring an integration, - delete a key that is no longer needed. ![Api Keys tab with a safely filtered key list](/img/organization/organization-api-keys-tab.png) For requests to the external API, send the API key together with the organization ID: ~~~http X-Api-Key: X-Org-Id: ~~~ Keep API keys out of prompts, public documentation, screenshots, frontend code, and shared messages. Store them in the calling system’s secret manager or environment variables. If a key is exposed, create a replacement, update the integration, and delete the old key. Use names that identify the system, environment, and purpose, for example: - crm-prod-sync - datawarehouse-dev-import - webhooks-prod-dispatch --- # Settings The **Settings** tab controls organization-wide feature availability, app access, and reusable content imports. These settings affect the whole workspace and should be changed by an owner or administrator. ## Feature Availability The **Feature availability** section contains: - **Agents**: agents are always available; select the default agent used across the organization. - **Public Chat**: controls whether public chat surfaces can be enabled. - **Webhooks**: controls availability of webhook entry points. - **Api Keys**: controls access to organization API-key management. - **Recordings**: controls the Recordings module. - **Select AI for transcription**: chooses the AI connection used to transcribe recordings. - **Enable Transcribe**: enables transcription with the selected AI connection. The transcription connection must be available to the organization. If transcription is enabled, select a compatible AI connection before saving. ![Settings tab with feature availability and transcription controls](/img/organization/organization-settings-tab.png) ## Apps & Extensions Use **Apps & Extensions** to control whether organization members can access: - the Mobile App, - the Browser Extension, - the Desktop App. Disabling an item removes that distribution surface for members; it does not change the permissions, tools, or data available to an already configured agent. ## Content Import **Content import** accepts a JSON package containing global categories, skills, and reusable Library content. Review the package and its source before importing because the imported objects become available at organization scope. ![Settings tab with app access and content import](/img/organization/organization-settings-apps-tab.png) ## Troubleshooting If Settings cannot be saved: - confirm that the selected default agent still exists and belongs to the organization, - confirm that transcription is not enabled without a compatible AI connection, - check feature availability before looking for a missing module elsewhere, - verify that the import package uses the expected JSON structure. --- # Security The **Security** tab centralizes SSO, user-management policy, integration governance, AI safety, and data retention. It is the only Organization tab for SSO configuration; there is no separate SSO Config tab. ## SSO Config The **SSO config** section provides Microsoft and Google identity providers. Enable the provider you want to configure, complete the fields shown by the application, and save the Security form. Treat tenant IDs and client IDs as configuration identifiers. Store client secrets securely and never place them in documentation, screenshots, prompts, or shared messages. ## User Management User Management contains: - **Sharing** controls for public conversation and recording links, - **Editable Profile Fields** for choosing which profile attributes members can change, - **Teams Synchronisation** for importing organization groups from Microsoft Entra ID. If identity data is directory-managed, restrict editable profile fields so users cannot override authoritative values. Configure Microsoft SSO before starting Entra group synchronization. ![Security tab with SSO and user-management controls](/img/organization/organization-security-tab.png) ## Integration The **Tool Connections** section is the organization-wide control point for external services. Use it to decide which providers are approved before users create connections or make those services available to agents and workflows. Each switch enables or disables an integration for the organization. Keep services disabled until they have passed your security, legal, and data-governance review. Where an integration includes a **Functions** section, expand it to review the operations exposed by that provider and leave unnecessary capabilities disabled. After changing the policy, select **Save**. Before disabling an integration that is already in use, review dependent connections, agents, and workflows because the affected capability may no longer be available to them. These organization-level controls sit above individual connection access, agent tool assignment, and workflow configuration. ![Organization Security integration controls for enabling and disabling tool connections](/img/organization/organization-security-integrations.png) ## AI AI security contains: - **Prompt Shield Filter** for prompt-injection and jailbreak protection, - **Content Safety Filter** for risky user prompts, - category switches for violence, sexual content, hate, and self-harm. Category switches become active when the main Content Safety Filter is enabled. ## Data Data retention can automatically remove: - audit-log entries after the configured number of days, - soft-deleted records after the configured number of days. Choose retention periods that satisfy recovery, support, audit, and governance requirements. ![Security tab with AI safety and data-retention controls](/img/organization/organization-security-controls.png) The standalone [Security Center](#doc-security) presents recommendations and findings. Organization Security is where the underlying tenant-wide policy is configured. ## Troubleshooting If Security settings do not behave as expected: - confirm that the current user has owner or administrator access, - check SSO configuration before troubleshooting provider sign-in, - check Feature availability in [Settings](#doc-organization-settings) when a module is missing, - check Tool Connections when an integration or function is unavailable, - check retention settings when records disappear earlier than expected. --- # Analytics ## Usage Use **Usage** to understand overall activity in the platform. This tab is the first place to check when you want to know whether users are actively working with agents and conversations. The Usage screenshot shows headline KPIs for conversations, messages, connected data sources, and active agents. Below the KPIs, the monthly conversations chart makes adoption trends visible across the calendar year. The side panel lists recent negative feedback so admins can jump from an analytics signal into the conversations or agents that need follow-up. ![Usage analytics](/img/analytics/usage.png) Typical questions: - Are conversations and messages increasing or decreasing? - Did activity change after a rollout, workflow update, or agent configuration change? - Are users engaging with the expected assistants? ## Cost Use **Cost** to track token and model spend. This tab helps admins understand how AI usage translates into consumption and where limits or optimization may be needed. The Cost tab is connected to the same cost and token accounting that powers organization usage controls. The date range selector applies to all cards and charts on the tab, so change it first before comparing totals. The headline cards separate token usage into: - **Input token count**: tokens sent into model requests, including user messages, instructions, retrieved context, tool context, and other prompt material. - **Output token count**: tokens generated by the model in the final answer or intermediate assistant output. - **Reasoning token count**: internal reasoning tokens reported by models that expose reasoning usage. - **Total token count**: combined input, output, and reasoning tokens for the selected range. The **Token Consumption** chart shows daily token volume split by input, output, and reasoning tokens. Use it to find the exact day where usage increased before opening conversations, workflows, or agent analytics for deeper investigation. ![Cost token consumption](/img/analytics/cost-token-consumption.png) The lower Cost charts explain where the token total came from: - **Tokens by Model** shows the share of selected-range tokens by model. This is the fastest way to spot whether traffic is concentrated on a more expensive or more capable model than expected. - **Tokens by Agent** shows the share of selected-range tokens by agent. Use it to find the agents that are driving organization spend and decide where prompt, retrieval, workflow, or model tuning should happen first. - **Token Consumption by Model** shows model usage over time. The stacked bars make model migrations, fallback behavior, and one-day spikes visible; the tooltip exposes the exact token count per model for a selected date. If an Azure AI Foundry model router deployment is used, Siesta AI analytics should be read together with Azure Monitor. Siesta AI shows which agent, team, user, or model connection is consuming tokens; Azure Monitor is the source of truth for the router's underlying model distribution. ![Cost tokens by model and agent](/img/analytics/cost-tokens-by-model-agent.png) ![Cost token consumption by model](/img/analytics/cost-token-consumption-by-model.png) Typical questions: - Which period has the highest AI cost? - Did a newly deployed agent or workflow increase usage? - Should model connections receive stricter token limits? - Which model is responsible for most token consumption? - Which agent is responsible for a usage spike? ## Limits Use **Limits** to monitor and configure preventive token guardrails for LLM/model connections. Cost analytics shows historical usage; Limits shows how current daily and weekly usage compares with configured budgets. The provider selector at the top of the tab chooses the model provider or model connection whose limits you are reviewing, such as OpenAI. The top cards summarize the current limit state: - **Daily org usage**: organization token usage today compared with the configured organization daily limit. - **Weekly org usage**: organization token usage this week compared with the configured organization weekly limit. - **Closest daily limit**: the nearest daily limit to being exhausted across organization, team, or user scopes. - **Closest weekly limit**: the nearest weekly limit to being exhausted across organization, team, or user scopes. Each card shows the percentage used, a progress bar, the consumed tokens, and the configured limit. Status labels such as **Safe** indicate whether the current usage is still within the expected budget. The **Configured limits** table shows the active default budgets for organization, team, and user scopes. Use **Manage limits** to open the editable connection-level limit settings. ![Analytics limits overview](/img/analytics/limits-overview.png) The **Limit utilization** table compares actual usage with configured daily and weekly limits for individual users or teams. Switch between **Users** and **Teams** to find who is closest to a budget threshold. Each row shows the consumed token count, configured limit, percentage used, and a progress bar for both daily and weekly windows. Use this view before changing limits: if usage is concentrated in one team, adjust the team override; if the whole organization is approaching the same threshold, change the organization default. ![Analytics limit utilization](/img/analytics/limits-utilization.png) The LLM token limit view is scoped to a specific model connection, for example **Siesta AI LLM - Default**. Limits are configured in millions of tokens (`M`) and can be defined at multiple levels: - **User defaults**: the default daily and weekly budget for users on the selected connection. - **Team defaults**: the default daily and weekly budget for teams on the selected connection. - **Organization defaults**: the workspace-level daily and weekly budget for the selected connection. - **User overrides**: per-user rows where admins can set a custom daily or weekly budget and disable a specific override. - **Team overrides**: per-team rows for team-specific budgets. Save changes after editing defaults or override rows. When a configured budget is exceeded, Siesta AI should stop the model request with a controlled token-limit error instead of allowing unlimited spend. ![LLM token limits](/img/analytics/llm-token-limits.png) Limits are most useful after Cost analytics identifies a high-volume model, agent, or team. Set the broad organization default first, then add user or team overrides only where the real usage pattern justifies a different budget. ## Data Use **Data** to monitor data-source and collection activity. This is useful when agents rely on uploaded files, synced sources, or knowledge collections. The Data screenshot summarizes the current data inventory: total storage, number of data collections, source types, and files. The donut charts break storage down by collection and source connection, and show document counts by file type. This helps admins verify whether the expected data sources are present and whether one collection or connection dominates storage usage. Use this tab together with [Data Collections](#doc-data-collections) when a collection exists but answer quality is low. Analytics tells you whether the data footprint looks healthy; the collection detail tells you whether the expected documents, chunks, and sync runs are actually present. ![Data analytics](/img/analytics/data.png) Typical questions: - Are data collections being used and updated? - Are new sources being added as expected? - Does low agent quality correlate with missing or stale data? ## Workflows Use **Workflows** to monitor workflow usage and outcomes. This view is useful after publishing a workflow to a pilot team or after making a workflow available more broadly. The Workflows tab summarizes automation activity for the selected date range. The KPI cards show: - **Workflow Executions**: total workflow runs in the range. - **Operations**: total executed workflow operations, which can be higher than executions because one workflow run may contain multiple steps. - **Operation Categories**: number of operation categories represented in the range. - **Active Periods**: number of time buckets where workflow activity occurred. Use **Executions Over Time** to see workflow runs grouped by the selected time range. This chart is the fastest way to spot rollout effects, schedule spikes, quiet periods, or a sudden drop in automation activity. Use **Operations by Workflow** to understand which workflow or operation type is responsible for most automation volume. The donut chart shows share, count, and percentage for categories such as assistant-triggered runs, scheduled workflows, webhook workflows, recording transcription flows, and tool functions. ![Workflow analytics overview](/img/analytics/workflow-analytics-overview.png) This tab is especially useful after releasing a new workflow to production or after changing triggers, conditions, or external connections. Compare expected operational volume with the real run pattern before assuming a workflow is healthy. Typical questions: - Which workflows are being run most often? - Are workflow runs completing successfully? - Did a workflow change affect usage or failure patterns? ## Recordings Use **Recordings** to review recording activity and processing trends. This helps teams understand whether recordings are being captured, processed, and reused as expected. The Recordings screenshot shows the total number of recordings, peak recording volume, and active recording periods. The time-series chart groups created recordings by week for the selected range, making it easier to spot adoption spikes, quiet periods, or irregular recording behavior. If recordings are used as a source for follow-up chat, analytics, or operational review, use this tab to confirm that uploads and processing continue at the expected pace after a rollout. ![Recording analytics](/img/analytics/recordings.png) Typical questions: - Are recordings being created regularly? - Are there periods with unusual recording activity? - Does recording usage support the intended team workflow? ## Chart Interpretation Below the KPIs, analytics views use charts to show trends over time. For quick diagnostics: - Sharp drop = check the availability of agents, connected channels, or recent changes in prompts or workflows. - Growth = verify whether capacity (rate limits, resources) is keeping up. ## Feedback and Follow-up When analytics points to quality or adoption problems, follow the signal into the related operational page: - Open **Conversations** to inspect the conversation that created the signal. - Open **Agents** to adjust instructions, tools, prompts, or model settings. - Open **Data** to check whether the agent has the right data collection. - Open **Workflows** when the signal may come from automation volume or failed orchestration behavior. - Open **Recordings** when the issue is tied to transcript availability or uneven recording intake. - Open **Logs** to inspect audit events or tool executions. ## Tips for Working with Data - Monitor **daily changes** in KPIs to quickly identify fluctuations. - If the number of messages is increasing without a rise in conversations, check the quality of responses (feedback) and possibly adjust the instructions. - With zero data sources, verify that agents have the correct datasets and access assigned. --- # Users Use **Users** to manage existing accounts and invite new people into your organization. Administrators can create users directly, send email invitations, import multiple invitations from CSV, review pending invitations, revoke invitations that should no longer be used, and assign broad platform roles. The main table shows user names, emails, and assigned roles. Use search to find a person, open a user for details, or use the actions at the top of the table for invitation workflows. ## User Detail Open a user from the list to review and maintain one specific account. Use the detail page to check: - account identity and contact information, - assigned role, - team membership, - account status, - available administrative actions. Use user detail when troubleshooting access. If a user cannot see an agent, workflow, data collection, or admin area, check the user's role first, then team membership, and then the access settings of the target resource. ## Creating a New User {#creating-a-new-user} Use **Create User** when the account should be created immediately by an administrator. The form asks for: - **First Name** - **Last Name** - **Email** - **Phone Number (optional)** - **Password** Confirm with **Submit**, or close the dialog with **Cancel**. ![Creating User](/img/users/user-create.png) ## Inviting Users {#inviting-users} Use **Invite User** when the person should receive an email invitation and finish the account setup themselves. The invitation form asks for: - **Email** - **First Name** - **Last Name** - **Role** After the invitation is sent, the recipient receives an email with a link to join Siesta AI. The link takes them to the Siesta AI app, where they can finish account setup with a password-based signup flow or through configured SSO. Invitations expire after 7 days. If an invitation already exists for the same email: - an active pending invitation is resent, - an expired or revoked invitation is refreshed with a new token and expiration, - an email that already belongs to an existing user is rejected. Admins cannot invite another user as **Owner** when their own role is only **Administrator**. ## Domain-Based Onboarding {#domain-based-onboarding} For organizations that want users to join without a manual invitation for every person, the Siesta AI team can enable domain-based onboarding. When domain-based onboarding is active, Siesta AI recognizes approved company email domains. If a new user signs in with Google or Microsoft using one of those domains, Siesta AI can automatically associate the account with the correct organization. Use domain-based onboarding when: - the organization has a controlled company email domain, - users should be able to join through Google or Microsoft SSO, - admins want to reduce manual invitation work for larger teams. Contact the Siesta AI team to configure approved domains and confirm the expected onboarding behavior before rolling it out. ## Microsoft Entra Synchronization {#microsoft-entra-synchronization} Use **Microsoft Entra Sync** when organization groups and membership should be managed from Microsoft Entra ID instead of maintained manually in Siesta AI. Configure Microsoft SSO first. Then open **Organization → Security → User Management** and use **Sync Microsoft Entra Groups**. After synchronization, review the imported users, their roles, and their team membership before granting access to production resources. See [Organization Security](#doc-organization-security) for the tenant-wide SSO and synchronization controls. ## Pending Invitations and Revoking Access {#pending-invitations-and-revoking-access} Use **Pending Invites** to review invitations that have not been accepted yet. The list includes the invitee email, name, role, status, creation time, and expiration. You can revoke a pending invitation when: - the invite was sent to the wrong person, - the person should no longer join the organization, - the role or access plan changed before the invite was accepted. Revoking changes the invitation status to **Revoked**. Only pending invitations can be revoked; accepted, expired, or already revoked invitations cannot be revoked again. ## Bulk Invitation from CSV {#bulk-invitation-from-csv} Use **Import CSV** when you need to invite several users at once. The CSV file must use these headers: ```csv email,firstName,lastName allen.bowman95@demo.local,Allen,Bowman shannon.harper100@example.com,Shannon,Harper lisa.jackson320@demo.local,Lisa,Jackson victor.martinez169@demo.local,Victor,Martinez thomas.blackwell821@example.com,Thomas,Blackwell ``` ![Bulk invitation CSV example](/img/users/csv_import_users_example.svg) CSV import creates invitations with the default **User** role. Use the single **Invite User** flow when you need to choose a different role during invitation. Before importing: - keep the file as `.csv` or `text/csv`, - include the exact headers `email`, `firstName`, and `lastName`, - make sure every row has a valid email address, - remove duplicate emails, - keep the file under 1 MB. After import, each row is processed separately. The result can show: - **Created**: a new invitation was created and emailed, - **Resent**: an existing active pending invitation was emailed again, - **Refreshed**: an expired or revoked invitation was renewed, - **Ignored**: a duplicate email was skipped, - **Failed**: the row had missing names, an invalid email, an existing user, or another validation problem. ## User Roles {#user-roles} In the role assignment dialog, the following options are available: - **Owner** - **Administrator** - **User** ![Role Selection](/img/users/user-roles.png) Roles define broad platform permissions. Teams define resource access boundaries. Use both together: roles answer "what can this user do?", while teams answer "which shared resources can this user access?". --- # Teams ## What Teams Are For The Teams tab is used to manage user teams within the organization in Siesta AI. Teams allow for logical grouping of users and managing their access to AI agents and other application features. Each team: - has its own name and description, - contains specific users, - determines which agents team members have access to (agent assignment is in preparation). ## Teams Table On the main screen of the Teams tab, a list of all created teams is displayed in the form of a table. Displayed columns: - **Name** – team name - **Description** – brief description of the team's purpose - **Agents** – specification of which agents the team has access to (currently only "All") - **Users** – list or shortcuts of team members - **Actions** – additional team management options At the top of the page, the following is available: - team search, - **Add Team** button. ![Team Overview](/img/teams/teams-overview.png) ## Creating a New Team Clicking on **Add Team** opens a form to create a new team. **Form Fields** - **Name** – required field for entering the team name (e.g., Team Fist Alpha). - **Description** – optional field for a brief description of the team's purpose. - **Users** – search field for adding users to the team. **Actions** - **Submit** – creates the team and saves its settings ![Creating a Team](/img/teams/team-create.png) ## Team Detail Open a specific team from the teams table to review and maintain its details. Displayed information: - team name, - description, - list of users who are team members. From the team detail, it is possible to: - edit the team name and description, - add or remove users. - review which people belong to the team before granting access to shared agents, workflows, or tools. ![Team Detail](/img/teams/team-detail.png) ## Access to Agents Each team can be used as an access boundary for AI agents and shared workspaces. Keep teams aligned with real departments or project groups so permissions stay easy to review. When a resource is shared with a team, every member of that team may receive access according to the resource's permission settings. Before sharing production agents or workflows, open the team detail and verify that the member list is correct. ## Troubleshooting Team Access If a user cannot access a shared resource: 1. Open the user detail and confirm the user is in the expected team. 2. Open the team detail and confirm the member list is current. 3. Open the agent, workflow, or connection and confirm it is shared with that team. 4. Check the user's role if the resource requires admin or edit permissions. ## Typical Use of Teams The Teams tab is primarily intended for: - dividing users by roles or projects, - managing access to AI agents, - easier management of a larger number of users, - ensuring a clear organizational structure. ## Summary Teams in Siesta AI provide a fundamental mechanism for organizing users and controlling access to AI functions. Properly configured teams simplify application management and enhance both security and clarity of work. --- # Audit log The **Audit log** page is part of **Logs**. Open **Logs** and choose the audit log view to monitor important actions performed within the Siesta AI application. The audit log provides a history of changes and system events that is useful for traceability, security, auditing, and incident resolution. Each record in the audit log corresponds to a specific action performed by a user or the system. The related **Tool Executions** view in Logs focuses specifically on actions that agents performed through connected tools. Use Audit log for administrative and system changes, and Tool Executions for agent/tool activity. ## Overview of Records The audit log view displays a list of events in a table. Displayed columns: - **Date** – exact date and time of the action performed - **User** – identification of the user who performed the action - **Entity** – type of object on which the action was performed (e.g., Conversation, Message, User, Team, DataSource, ApiKey) - **Action Type** – type of operation performed, e.g., **Created** or **Updated** - **Detail** – eye icon to open the details of the record The audit log is paginated to handle very large amounts of records. ![Overview of the audit log](/img/audit-log/audit-log-overview.png) ## Filtering Records The audit log allows filtering of events to quickly find relevant records. Available filters: - **Date Range (Select Date Range)** – limit records to a specific period - **User (User)** – actions performed by a specific user - **Action Type (Action Type)** – filtering by type of operation (e.g., only Created or Updated) - **Reset Filters** – clear all filters Filters can be combined for more precise results. ## Detail of Audit Record After opening a specific record, detailed information about the action is displayed. Details include: - **Record ID** – unique identifier of the audit event - **Entity** – type of object affected by the change - **Date** – time of the action performed - **User** – identity of the user who performed the action - **Correlation ID** – identifier that allows tracking related actions across the system ### Changes Displays specific changes that were made, such as: - the name of the property that was changed, - original value, - new value after the change. This section allows for precise tracking of what changed and how. ![Detail of the audit record](/img/audit-log/audit-log-detail.png) ## Typical Uses of the Audit Log The audit log is primarily intended for: - security and compliance purposes, - tracing the history of changes, - analyzing user behavior, - resolving incidents and errors, - internal and external audits. ## Summary The audit log in Siesta AI provides a transparent and detailed overview of important actions in the system. With filters and record details, it allows for quick identification of when, by whom, and how a specific change was made. --- # Webhooks The Webhooks tab is used to manage webhooks that allow Siesta AI to connect with external systems and applications. A webhook provides a unique URL address to which an external service can send HTTP requests, thereby triggering or influencing the behavior of the system. You can find webhooks in the left application menu under **Webhooks**. Each webhook: - has its own name, - can be associated with a specific API key, - can be active or inactive, - has a unique URL address. Webhooks are often used as triggers for [Workflows](#doc-workflow) that can be initiated from external systems. The current dev model supports both patterns: - **webhook + API key** for explicit server-to-server authentication, - **webhook without selected API key** when the workspace uses another controlled integration pattern. If an API key is selected, knowing the webhook URL alone is not enough; the caller should also use the associated API key. ## Overview of Webhooks On the main screen of the Webhooks tab, a list of all created webhooks is displayed in a table. Displayed columns: - **Name** – the name of the webhook entered by the user - **URL** – automatically generated URL address of the webhook - **Status** – current status of the webhook (Active / Inactive) - **Actions** – additional management options for the webhook (e.g., edit) At the top of the page, you can find: - webhook search, - the **Add Webhook** button. ![Overview of Webhooks](/img/webhooks/webhooks-overview.png) ## Creating a New Webhook Clicking on **Add Webhook** opens a dialog for creating a new webhook. **Form Fields** - **Name** – a required field for entering the name of the webhook (e.g., Webhook) - **Active** – a toggle that allows you to activate the webhook upon creation or leave it inactive - **API Key** – optional selection of the API key that will authorize the webhook (e.g., API key for my python script) **Actions** - **Cancel** – closes the dialog without creating the webhook - **Create** – creates a new webhook and generates its URL ![Creating a Webhook](/img/webhooks/webhook-create.png) ## Webhook Details Open a specific webhook from the table to review its details. Displayed information: - name of the webhook, - status (active / inactive), - URL of the webhook – a unique address that can be copied with one click, - API key relationship – the selected API key that authorizes the caller. - if no API key is selected, the detail reflects that the webhook currently relies on the URL/token flow alone. From the webhook detail, you can: - edit the webhook settings, - change its active status, - use the webhook URL in external applications or in [Workflows](#doc-workflow). ![Webhook Details](/img/webhooks/webhook-detail.png) ## Webhook Status The status of the webhook determines whether it is ready to receive requests: - **Active** – the webhook is on and available - **Inactive** – the webhook is off and requests are not processed The status is visible both in the overview of webhooks and in the webhook detail. ## Troubleshooting If an external system cannot trigger a webhook: 1. Open the webhook detail and confirm that the webhook is **Active**. 2. Copy the URL again from the detail page to avoid using an outdated address. 3. If the webhook uses an API key, confirm that the selected API key is still valid and that the caller is using the intended server-side authentication flow. 4. Check whether the external system sends the expected HTTP method and payload. 5. If the webhook starts a workflow, open the workflow and inspect the trigger and first node. 6. Use Logs and Tool Executions to confirm whether a downstream action failed after the webhook was received. If you rotate or delete the API key associated with a webhook, update the external system immediately. If the webhook intentionally has no API key, review the surrounding integration controls before exposing it outside a trusted server-to-server context. ## Typical Use Cases for Webhooks Webhooks are primarily used for: - integrating Siesta AI with external applications, - triggering automated processes, - connecting custom scripts (e.g., Python), - transferring data between systems in real-time. ## Summary Webhooks in Siesta AI provide a simple and secure way to connect the platform with external systems. With clear management, linkage to API keys, and the ability to activate or deactivate, webhooks can be easily monitored and managed. If you use a webhook as a trigger, we recommend linking its use to [Workflows](#doc-workflow). --- # Help The Help tab serves as a central hub for support and information within the Siesta AI application. Users can find direct access to documentation, API guides, system status information, a bug reporting form, and contact options for the Siesta AI team. The help center acts as a central portal for all user support and documentation. It contains links to the official user documentation as well as detailed reference materials for the API, a collection of blog posts, and the current service status. Additionally, it provides quick access to a live chat interface for contacting the support team and the option to schedule calls or video conferences with specialists. All resources are grouped so that users have one place for self-study and immediate resolution of inquiries. ![Help Overview](/img/help/help-overview.png) ## Available Items ### Documentation Provides access to comprehensive guides and official documentation for the Siesta AI platform. Upon clicking, the user is redirected to the documentation portal, where they can find user manuals, detailed feature descriptions, and recommended practices for working with the system. ### SiestaAI Status Used to check the current status and availability of Siesta AI services. The link leads to a public status page where the overall system status, availability of individual services (API, application, web), and their operational history are displayed. ![Siesta AI Service Status](/img/help/siesta-status.png) ### Blog Contains the latest news, product updates, and announcements regarding the development of the Siesta AI platform. Upon opening, the user is redirected to the official Siesta AI blog. ### API Documentation Intended for developers and technical users who integrate Siesta AI using the API. The link leads to the API documentation with an overview of endpoints, authentication descriptions, and integration guides. ### Schedule a Call with a Representative Allows users to book a demo or consultation with the Siesta AI team. Upon clicking, a booking page opens for arranging a call with a sales or technical representative. ### Report a Bug Used to report bugs, technical issues, or unexpected behavior of the application. The link opens a bug report form where users can enter the bug title, detailed problem description, steps to reproduce, priority, deadline, and attach files. ![Bug Report Form](/img/help/bug-report.png) ### Talk to AI Support A feature in development that will allow direct communication with an AI agent for immediate support in the future. It is not yet available in the current version of the application. ## Typical Use The Help tab is primarily used for quick access to information, verifying service availability, resolving technical issues, working with the API, and contacting support or sales teams. ## Summary The Help section in Siesta AI functions as a central point for support and orientation within the system. It allows users to quickly access the right source of information without needing to leave the application. --- # Chrome Extension The Siesta AI Chrome Extension keeps your agents beside the page you are working on. It runs in the browser's native side panel, so the current tab remains visible while you chat, attach page context or files, review tool activity, or talk to a realtime voice agent. ![Siesta AI Chrome Extension overview](/img/chrome-extension/chrome-extension-marquee.png) ## What You Can Do The current extension supports: - text chat with accessible Siesta AI agents; - realtime voice conversations for agents that support realtime; - automatic selection of your last-used, account-default, or favorite agent; - searchable agent switching without leaving the panel; - editable starter prompts configured on the selected agent; - streaming Markdown responses with copy, stream-stop, retry, and new-chat controls; - visible tool-call status while an agent works; - restoration of the most recently active conversation after the panel closes; - page, text-selection, image, screenshot, and file attachments. Use the extension for page-adjacent work such as research, document review, drafting, comparison, and follow-up questions. Use the main web app for administration, agent configuration, data and connection management, workflows, analytics, and organization-wide settings. ## Open the Side Panel Open Siesta AI in either of these ways: - select the Siesta AI icon in the browser toolbar; - press `Ctrl+Shift+Y` on Windows/Linux or `Command+Shift+Y` on macOS. The shortcut can be changed in `chrome://extensions/shortcuts` or the equivalent Edge settings page. The extension requires Chrome or Edge 116 or later because it uses the browser's native Side Panel API. ## Sign In The extension uses the normal Siesta AI web sign-in: 1. Select **Sign in** in the side panel. 2. Complete email/password, Google, or Microsoft sign-in in the Siesta AI web app. 3. Return to the panel after the authenticated session is detected. The extension does not ask for or store your password. If the Siesta AI session expires or the API rejects it, the stored session token is cleared and the panel returns to the sign-in screen. ![Siesta AI Chrome Extension sign-in screen](/img/chrome-extension/chrome-extension-login.png) ## Choose an Agent When the panel opens, it chooses an agent in this order: 1. the agent you last selected in the extension; 2. your account's default agent; 3. a favorite agent; 4. the first available agent alphabetically. Select the active agent name or press `Command+K` / `Ctrl+K` to open the searchable agent switcher. Favorites are marked with a star. If the selected agent has configured conversation prompts, they appear on the empty-chat screen. Selecting a prompt fills the composer so you can review or edit it before sending. ![Siesta AI Chrome Extension agent picker](/img/chrome-extension/chrome-extension-agents.png) ## Chat and Continue Work Text chat supports: - live response streaming with a typewriter-style reveal; - Markdown, tables, lists, code, and links that open in a normal browser tab; - **Stop** to stop the current response stream; - **Copy** on a finished response; - **Retry** after a failed response; - **New chat** to clear the current conversation; - tool icons with success, failure, pending, or approval-pending status. The extension remembers the most recently active conversation and restores it when the panel is reopened with the same agent. Message history is fetched again from Siesta AI; message contents are not copied into extension storage. The extension currently restores one most-recent conversation rather than providing a full conversation browser. ![Siesta AI Chrome Extension chat view](/img/chrome-extension/chrome-extension-chat.png) ## Attach Context and Files Select **+** beside the composer to access these attachment options: | Option | What happens | | --- | --- | | **Attach this page** | Reads the active page's main text, title, and URL and attaches them as `page-context.txt`. | | **Upload a file** | Uploads one or more files to Siesta AI and adds them to the next message. | | **Take a screenshot** | Captures the visible area of the active tab and attaches it as a PNG. | You can also: - drag files anywhere onto the side panel; - paste an image from the clipboard into the composer; - send an attachment without accompanying text; - remove an attachment before sending. Each manually attached file or image can be up to 20 MB. The send button waits until active uploads finish. Failed uploads remain visible as error chips so you can remove them and attach the file again. ### Attach From the Page Menu Right-click supported page content to use the extension without manually copying it: - **Attach this page to Siesta** captures readable page text; - **Attach this text to Siesta** captures the current selection; - **Attach image to Siesta** downloads and uploads the selected image. The side panel opens and shows the captured item as a removable attachment. Type the question you want to ask, or send the attachment by itself. Page and selection text is limited to 20,000 characters before upload. The attachment includes the page title and URL so the agent can identify its source. Captured page content is sent as a file attachment rather than inserted invisibly into your prompt. Browser-protected pages such as `chrome://` pages, the Chrome Web Store, and some built-in PDF views may block text extraction. The extension shows a notice and leaves the normal composer available when that happens. ## Talk to Realtime Voice Agents When an agent supports realtime, the extension replaces the text composer with a voice-call view. 1. Select **Start voice chat**. 2. Allow microphone access when Chrome or Edge requests it. 3. Speak naturally and follow the live transcript in the panel. During a call you can: - mute and unmute the microphone; - hear the agent's audio response; - interrupt the agent by speaking; - review the live user and assistant transcript; - end the call and start again. A voice call never starts automatically because browser microphone access requires a user action. If the side panel cannot display the permission prompt, select **Enable microphone…** to grant access from a normal extension tab; the panel retries after permission is granted. ## Keyboard Shortcuts | Shortcut | Action | | --- | --- | | `Ctrl+Shift+Y` / `Command+Shift+Y` | Open the side panel | | `Ctrl+K` / `Command+K` | Open or close the agent switcher | | `/` | Focus the message composer | | `Enter` | Send | | `Shift+Enter` | Insert a new line | | `Esc` | Close the agent switcher, attachment menu, or user menu | ## Privacy and Browser Permissions The extension only extracts page text after an explicit action: **Attach this page**, **Attach this text**, or the corresponding right-click command. It does not install a persistent content reader across every website. The browser may show permissions for: - the side panel and local extension storage; - context-menu commands; - temporary access to the active tab and script execution for explicit page capture; - access to webpages so **Take a screenshot** works even after the persistent side panel has moved between tabs; - Siesta AI API and web-app access for chat and sign-in. Attached page text, selections, screenshots, images, and files are uploaded to Siesta AI when you attach them. Confirm that the selected agent and your organization's policies permit the content before sending it. Avoid attaching secrets or sensitive personal data unless the use case and access controls are approved. ## Chrome Extension, Web Plugin, or Desktop App? | Surface | Use it for | | --- | --- | | **Chrome Extension** | Agent chat, page context, files, screenshots, and voice beside the active browser tab | | **[Web Plugin](#doc-developers-web-plugin)** | Embedding a configured Siesta AI agent into a website you develop | | **[Desktop App](#doc-desktop-apps-windows)** | Native desktop access, local capture, recordings, and desktop-specific workflows | | **Siesta AI web app** | Full platform usage, configuration, administration, workflows, data, and analytics | ## Related Areas - [Chat](#doc-chat) - [Agents > Interfaces](#doc-agents-interfaces) - [Windows App](#doc-desktop-apps-windows) - [macOS App](#doc-desktop-apps-macos) - [Web Plugin](#doc-developers-web-plugin) --- # MacOS App The Siesta AI macOS App is a native workspace for capture, recordings, Wisps, tasks, and trusted local-agent execution. This reference describes the behavior implemented in the macOS client at commit `0d80340`. ## What the App Can Do ### Screen Capture Open **Capture** to record one display with system audio and an optional microphone. 1. Select a display and check the preview. 2. Turn system audio and microphone capture on or off independently. 3. If microphone capture is enabled, choose the input device. 4. Start capture. Upload progress is shown while the recording is running. 5. Use **Stop and Upload** to finalize the recording, or **Cancel** to discard the active capture. **Open Recordings Web** opens the Recordings area in the Siesta AI web application. ![Display and audio-source selection in the macOS Capture workspace](/img/desktop-apps/macos/capture.jpg) ### Audio Recording The **Recorder** workspace shows a timer, live waveform, and recording state. Use **Pause** and **Resume** without ending the recording. After stopping, enter the recording name and upload it. The app shows upload progress and failure state, allows another upload attempt after an error, supports **Discard**, and provides **Open Recording** when upload succeeds. ![Timer, waveform, and pause controls in the macOS audio recorder](/img/desktop-apps/macos/audio-recording.png) ### Recordings **Recordings** lists uploaded audio and screen recordings with creator, duration, and transcription status. The detail view shows metadata and the transcript when available. A recording can be opened in the web application or permanently deleted after confirmation. ### Wisps and Dictation Wisps are quick notes stored locally on the Mac. Type a note directly or capture it by voice. History supports copy, individual deletion, and **Clear all**. Two transcription engines are available: - **On-device (Apple)** uses Apple Speech locally and can work offline. Choose the dictation language when this engine is active. - **Organization** streams audio to the Siesta backend and uses the organization's configured transcription provider. The global Wisp shortcut supports **Toggle** and **Push to Talk** modes. ![Local notes and Wisp history in the macOS app](/img/desktop-apps/macos/wisps.jpg) ### Tasks and Local Agents Filter **Tasks** by workspace, state, or search text. The task UI supports movement between **Todo**, **In Progress**, **Review**, and **Done**. Before local execution, select the agent and use **Choose and Trust Project**. Siesta AI restricts the local agent to that trusted project and streams execution output back into the task workspace. Supported execution paths are: - **OpenCode** through ACP. - **GitHub Copilot** through ACP when the installed CLI exposes the ACP preview and is signed in. - **Antigravity** through the bundled local Python bridge. Running a Todo task moves it to **In Progress** and successful completion moves it to **Done**. You can cancel the active run, revoke trust for one project, or revoke all trusted projects in Settings. ![Task filters, local-agent selection, and trusted-project control in the macOS app](/img/desktop-apps/macos/tasks.jpg) ## What You Can Configure Open **Settings** to configure: - **General:** Light, Dark, or system theme; English, Czech, German, Spanish, French, or Italian application language; Wisp transcription engine; and Wisp dictation language. - **Audio Devices:** input and output devices, with a status refresh. - **Screen Capture:** capture shortcut, **Instant capture on shortcut**, Wisp shortcut, and Toggle or Push to Talk mode. - **Permissions:** current Microphone, Speech Recognition, Screen Recording, and Accessibility status, plus buttons to request missing access. - **Local Agents:** executable paths and working directories for OpenCode, Antigravity, and Copilot; Antigravity API key; agent-status refresh; and trusted-project revocation. Application-language changes apply after restart. The Antigravity API key is stored in the macOS Keychain. ![Anonymized macOS Settings with language, audio, shortcuts, and permission status](/img/desktop-apps/macos/settings.png) ## Required System Access The macOS app requires **macOS 15 or later**. Features may need: - **Microphone** for audio recording, microphone capture, and voice Wisps. - **Speech Recognition** for the on-device Apple Speech engine. - **Screen Recording** for display and system-audio capture. - **Accessibility** for reliable global shortcut handling and cross-application input. After granting Screen Recording access, quit and reopen Siesta AI if macOS still returns no shareable displays or reports that the current build does not have access. The Capture page provides shortcuts to System Settings and app restart. ## Availability and Current Limits - **Quick Actions** is displayed as **Coming Soon**. Selected-text transformations are not currently a general workflow. - Chat and realtime voice implementations exist, but the current main sidebar does not expose them. They should be documented as build- or activation-dependent, not universally available navigation items. - Local-agent execution requires an installed and ready agent, a valid working directory, and explicit project trust. ## Feature Comparison | Feature | Windows | macOS | | --- | --- | --- | | Screen and system-audio capture | Available | Available | | Audio recording and upload | Available | Available | | Recording list, detail, transcript, and delete | Available | Available | | Wisps | Push-to-talk, clipboard, local history | Typed and voice notes, Toggle or Push to Talk, local history | | OpenCode task execution | Local execution | ACP execution in a trusted project | | Antigravity task execution | Bundled Python bridge | Bundled Python bridge in a trusted project | | GitHub Copilot | Installation/sign-in detection only | ACP execution when the CLI exposes ACP and is signed in | | Quick Actions | Coming Soon | Coming Soon | | Chat and realtime voice | Hidden from navigation | Build- or activation-dependent; not in the main sidebar | ## Download - [Download for Mac](https://apps.apple.com/us/app/siesta-ai-app/id6757466852) ## Related Areas - [Windows App](#doc-desktop-apps-windows) - [Recordings](#doc-recordings) - [Tasks](#doc-tasks) - [Chrome Extension](#doc-chrome-extension) --- # Windows App The Siesta AI Windows App keeps capture, dictation, recordings, and selected local-agent workflows available from a native Windows workspace. This reference describes the behavior implemented in the Windows client at commit `259f371`. ## What the App Can Do ### Screen Capture Open **Screen** to record a display with optional microphone and system audio. 1. Turn the microphone on or off and select the input device. 2. Turn **System audio** on or off independently. 3. Choose a monitor and check its preview. 4. Start the recording. The app uploads video chunks while capture is in progress. 5. Stop the recording to finalize it in Siesta AI. After finalization, you can open the saved recording, create and copy a share link, revoke an existing link, or start another capture. ![Display, microphone, and system-audio selection in the Windows app](/img/desktop-apps/windows/screen-recording.png) ### Audio Recording Open **Audio** for a focused microphone recording. Select a microphone, then use **Start**, **Pause**, **Resume**, and **Stop**. After stopping, you can rename the recording before upload. The upload card shows progress and status. A failed upload can be attempted again; a local recording can be discarded; a completed upload can be opened in the Siesta AI web application. ![Audio recording controls in the Windows app](/img/desktop-apps/windows/audio-recording.png) ### Recordings **Recordings** lists recent audio and screen recordings. Open an item to review its name, creator, timestamps, duration, transcription status, and transcript when available. You can also open the recording in the web application or delete it after confirmation. ### Wisps and Dictation Wisps provide short voice-to-text capture from the app or through the global push-to-talk shortcut. When transcription completes, the text is copied to the clipboard so it can be pasted into the application that already has focus. Recent Wisps are stored locally. From the history you can copy an item again, delete one item, or clear the entire history. ![Local Wisp history in the Windows app](/img/desktop-apps/windows/wisps.png) ### Tasks and Local Agents The **Tasks** workspace can filter by workspace, task state, and search text. A **Todo** task can be started with an installed local agent; the client then shows local execution as **Running**, **Queued**, or **Stopped**. Current execution support differs by agent: - **OpenCode** can execute task prompts locally. - **Antigravity** can execute through the bundled Python bridge when configured. - **GitHub Copilot** is checked for installation and sign-in status, but Windows task execution is not implemented for it in this build. Use **Settings → Local Agents** to inspect whether each CLI is not installed, installed, or authenticated. Configure the working directory for OpenCode, Antigravity, and Copilot, and provide the Antigravity API key only in the app—not in documentation or task prompts. ## What You Can Configure Open **Settings** to configure: - **App theme:** Light, Dark, or the Windows system setting. - **Application language:** English, Czech, German, Spanish, French, or Italian. Restart the app to apply a language change. - **Audio devices:** the input microphone and output device. - **Global Capture Shortcut:** click the shortcut field and press the new key combination. - **Instant Capture on Shortcut:** start capture immediately instead of opening capture configuration. - **Local agents:** working directories for OpenCode, Antigravity, and GitHub Copilot; the Antigravity API key; and installation/authentication status. ![Windows settings for theme, language, audio, shortcuts, and Local Agents](/img/desktop-apps/windows/settings.png) ## Required System Access Windows may request microphone or capture access when a workflow first uses it. Grant only the permissions needed for the user's role. Global shortcuts must be registered successfully, and local-agent execution needs access to the configured working directory and the corresponding installed CLI. ## Availability and Current Limits - **Quick Actions** is visible in navigation but its page is marked **Coming Soon**. Selected-text rewrite, summarize, translate, or similar actions are not currently available. - **Chat** and **Stream** have implementation code but are hidden from the Windows navigation in this build. Do not treat them as standard Windows workflows. - GitHub Copilot detection and authentication checks are available, but task execution through Copilot is not. - Closing the main window hides Siesta AI and keeps it in the system tray. Use **Quit** from the tray menu to stop the application completely. ## Feature Comparison | Feature | Windows | macOS | | --- | --- | --- | | Screen and system-audio capture | Available | Available | | Audio recording and upload | Available | Available | | Recording list, detail, transcript, and delete | Available | Available | | Wisps | Push-to-talk, clipboard, local history | Typed and voice notes, Toggle or Push to Talk, local history | | OpenCode task execution | Local execution | ACP execution in a trusted project | | Antigravity task execution | Bundled Python bridge | Bundled Python bridge in a trusted project | | GitHub Copilot | Installation/sign-in detection only | ACP execution when the CLI exposes ACP and is signed in | | Quick Actions | Coming Soon | Coming Soon | | Chat and realtime voice | Hidden from navigation | Build- or activation-dependent; not in the main sidebar | ## Download - [Download and platform information](https://siesta.ai/desktop-app) ## Related Areas - [macOS App](#doc-desktop-apps-macos) - [Recordings](#doc-recordings) - [Tasks](#doc-tasks) - [Chrome Extension](#doc-chrome-extension) --- # Mobile App
The Siesta AI Mobile App brings your agents and conversations to iOS and Android. Use it to ask questions, continue work away from your desk, dictate a message, attach a file, or capture an audio recording for upload to Siesta AI. The mobile app uses the same account, agents, and server-side conversation history as the Siesta AI web app. It is a focused mobile work surface rather than an administration or configuration interface. ## Download the App | Platform | Download | | --- | --- | | iOS | [Download from the App Store](https://apps.apple.com/us/app/siesta-ai-app/id6757466852) | | Android | [Download from Google Play](https://play.google.com/store/apps/details?id=com.siestaai.app) | Sign in with an existing Siesta AI account. The app supports: - email and password; - Google sign-in; - Microsoft sign-in. Google and Microsoft sign-in open the provider's authorization flow and return you to the app after authentication. If the session expires or the server rejects it, the app clears the session and asks you to sign in again.
Siesta AI Mobile App new-chat screen
## Navigate the Mobile Workspace Open the navigation drawer to access the main mobile workflows: - **New Chat** opens an empty conversation and loads the agents available to your account. - **New Recording** opens the standalone audio recorder. - **Recent conversations** lets you return to server-side conversation history. More conversations load as you move through the list. - **Profile** shows your name, email, and profile image or initials, and provides the log-out action. The current conversation is highlighted in the drawer. Selecting another conversation loads its messages and associated agent. ## Start a Chat and Choose an Agent
On a new chat, the app loads the agents available to your account. Select the agent name before sending the first message if you want to use a different agent. After the conversation starts, the agent remains associated with that conversation. You can also select an agent first and create a conversation directly from the agent list. Public agents are shown first, followed by the remaining agents alphabetically.
Agent selection in the Siesta AI Mobile App
## Chat and Continue Conversations The chat surface supports: - starting a new conversation or reopening an existing one; - progressively streamed assistant responses; - Markdown formatting for headings, lists, links, tables, and code; - visible response and reasoning progress while the agent is working; - automatic conversation titles returned by Siesta AI; - recovery of the completed server response if a live stream is interrupted. Messages and conversation history are loaded from Siesta AI. When a response finishes, the recent-conversations list refreshes so the latest title and activity are available in the drawer. ## Attach Files After a conversation has been created, select the attachment button to choose a file from the device. The app uploads the file to that conversation and displays it above the composer as a removable pending attachment. You can remove an attachment before sending. When you send the next message, its pending attachments are submitted with the prompt. If sending fails, the app restores them so you can try again. An empty new chat does not yet have a server-side conversation. Send the first message, or create a conversation by selecting an agent, before attaching a file. ## Dictate a Message
Select the microphone in the chat composer to dictate instead of typing. The app uses the native speech-recognition service on Android or iOS: 1. Allow microphone and speech-recognition access when prompted. 2. Speak while the recording indicator and waveform are active. 3. Use the send action to stop recording, convert the speech to text, and send it to the current agent. 4. Use the stop or cancel action to discard the dictated message. If the device does not detect speech, the app keeps the conversation unchanged and asks you to try again.
Voice dictation in the Siesta AI Mobile App
## Capture and Upload an Audio Recording
The standalone recorder is intended for longer notes, meetings, calls, or ideas that should enter the Siesta AI recordings workflow. 1. Open **New Recording** and select the red record button. 2. Pause when you want to review the elapsed time and captured waveform. 3. Resume recording, discard it, or submit it for upload. 4. Follow the upload percentage. You can cancel the upload and return to the paused recording if needed. Paused and resumed segments are combined before upload. The app sends the audio, its duration, and a generated recording name to Siesta AI. Continue in [Recordings](#doc-recordings) to review the uploaded item and the outputs made available by your configured recording workflow. Recording can continue while the app is in the background. Android shows a foreground recording notification while the microphone is active; iOS uses the operating system's background-audio capability.
Standalone audio recording in the Siesta AI Mobile App
## Permissions and Local Data The mobile app requests only the device capabilities needed for the action you start: - microphone access for dictation and standalone recordings; - speech-recognition access for voice-to-text messages; - file-picker access when you choose an attachment; - network access for sign-in, agents, conversations, uploads, and streamed responses. The authentication token is kept in the operating system's secure storage. Chat history is fetched from Siesta AI rather than maintained as a persistent local conversation database. Standalone recordings use temporary local audio files while recording and uploading; those files are removed after a successful upload or when the recording is discarded. Follow your organization's data-handling rules before attaching files or recording meetings and calls. Obtain any consent required for recording other people. ## Mobile App or Another Siesta AI Surface? | Surface | Use it for | | --- | --- | | **Mobile App** | Agent chat, existing conversations, file attachments, dictation, and audio capture while away from your desk | | **[Desktop App](#doc-desktop-apps-windows)** | Desktop-native capture, global shortcuts, screen recording, tasks, and local workflows | | **[Chrome Extension](#doc-chrome-extension)** | Agent chat and page context beside the active browser tab | | **Siesta AI web app** | Agent configuration, administration, data, connections, workflows, analytics, and organization settings | An agent's tools, knowledge, permissions, and behavior are configured on the server. The mobile app uses that configuration; it does not replace the web app's setup and governance surfaces. ## Related Areas - [Chat](#doc-chat) - [Agents](#doc-agents) - [Conversations](#doc-conversations) - [Recordings](#doc-recordings) - [Windows App](#doc-desktop-apps-windows) - [macOS App](#doc-desktop-apps-macos) - [Chrome Extension](#doc-chrome-extension) --- # Admin Guide import NavCardGrid from '@site/src/components/NavCardGrid'; import {Building2, Route, Database, ShieldCheck, Server, LineChart} from 'lucide-react'; # Admin Guide Plan, launch, and govern Siesta AI for an organization: identity, teams, access, connections, tools, agents, workflows, monitoring, and audit evidence. Use this guide as an operating manual for running Siesta AI inside an organization. It is written for owners and admins who need to make access, identity, connection, tool, agent, workflow, and audit decisions before teams start using production assistants. The important rule is simple: configure the tenant before inviting broad usage. Siesta AI can keep resources private, share them with selected teams, allow organization-wide use, require write permissions, disable connection types, force tool functions into confirmation mode, and record operational changes in audit logs. Admin work is the process of choosing those defaults deliberately. ## Browse by Outcome ## What Admins Actually Own | Area | Admin decision | Failure if skipped | | --- | --- | --- | | [Organization](#doc-organization) | Plan, API keys, SSO, security switches, public features, recordings, and Entra sync | Users join the wrong way, public features are enabled without review, or keys remain unowned | | [Teams](#doc-teams) & [users](#doc-users) | Who belongs to each access boundary and who can administer it | Agents and connections get shared too broadly | | [Connections](#doc-connections) | Which providers are enabled, who owns credentials, and which functions need confirmation | Agents can read or write through the wrong external account | | [Data](#doc-data-collections) | Which systems are authoritative, what is ingested, who can use collections, and how sources are tested | Stale, confidential, or irrelevant content becomes agent context | | [Access policies](#doc-agents-configuration) | Private, team, organization, use, and edit/write permissions | Users cannot find resources, or too many users can change them | | [Agents](#doc-agents) & [workflows](#doc-workflow) | Production behavior, data, tools, prompts, approvals, and rollback path | Workflows change records or agents answer from the wrong context | | [Monitoring](/analytics) | Tool Executions, Audit Log, conversations, feedback, usage, and token limits | Incidents have no clear owner or evidence trail | ## Backend Rules To Plan Around - Access-controlled resources are effectively private unless an access mode or policy shares them. - Creators can access their own resources; Owner/Admin mode can review organization resources where the role allows it. - Team access distinguishes **use** from **write/edit**. Give edit rights only to people who can safely change prompts, tools, workflow logic, or access. - Connection type governance can disable a provider for the whole organization. - Function governance uses the strictest effective setting: enabled, enabled with confirmation, or disabled. - REST and MCP tools can expose custom functions. Treat their schemas, headers, and write behavior as production contracts. - Token limits are managed per model connection at organization, team, and user level. - Tool executions record function status and approval state. Audit logs record configuration changes with entity, user, timestamp, correlation ID, and changed properties. ## Recommended Setup Order 1. [Configure Organization](#doc-admin-guide-plan-organization-setup): General, Api Keys, Settings, and Security. SSO and Entra synchronization are under Security. 2. **Choose an onboarding method**: manual invitations, Microsoft Entra synchronization, SSO, approved domains, or a combination. 3. [Create pilot teams and assign users](#doc-admin-guide-create-teams-and-assign-users) who need the same agents, data, and tools. 4. [Add and govern the required connections](#doc-admin-guide-configure-shared-and-private-connections), including function confirmations and token limits. 5. [Create and govern data collections](#doc-admin-guide-govern-data-collections-and-sources), verify documents/chunks, and define collection access. 6. [Prepare agents for the pilot team](#doc-admin-guide-prepare-agents-and-workflows-for-teams) with explicit prompts, data, Shared Tools, Private Tools, access settings, and Platform Tools. 7. [Publish workflows after safe testing](#doc-admin-guide-prepare-agents-and-workflows-for-teams) of read and write actions on non-production records. 8. [Monitor Tool Executions, Audit Log, conversations, feedback, and usage](#doc-admin-guide-monitor-usage-audit-logs-and-risk) after rollout. ## Common Admin Problems | Problem | Check first | Usually fixed by | | --- | --- | --- | | A user cannot see an agent or workflow | Team membership, access mode, organization access, and team policy | Add the user to the right team or grant team **Can Use** access | | An agent cannot call a tool | Connection sharing, organization connection policy, function access mode, and private connection ownership | Share the connection, enable the provider, or assign the user's private connection | | A write action waits for approval | Function access is set to confirmation | Approve the execution, or intentionally lower the function access if the action is safe | | A shared model connection burns too many tokens | Connection token limits and agent/workflow usage | Set org/team/user limits and split high-volume automations into a reviewed connection | | SSO users land in the wrong tenant | SSO config, domain linking, invitation state, and Entra group sync | Fix SSO metadata/domain ownership before inviting more users | | A workflow changed the wrong record | Arguments recorded in Tool Executions, workflow node parameters, previous node output, and approval status | Pause sharing, tighten parameters, require approval, and retest | | Public chat or sharing is unavailable | Organization Security feature flags | Enable the feature intentionally, then review privacy and retention settings | ## Rollout Phases Start with one pilot team, one or two approved connections, and one production-quality agent. Do not start with every integration, every department, and organization-wide access. After the pilot, expand by team and reuse the same review loop: access, tools, approvals, test data, Tool Executions, audit evidence, and owner sign-off. Move advanced work into a second phase: REST/MCP tool design, external API automation, workflow webhooks, realtime agents, detailed token economics, evaluation loops, and connection-specific governance. ## Admin Readiness Checklist - **Identity**: SSO, manual invitations, Entra sync, and approved domains have a clear owner. - **Teams**: every production team has a business owner and a defined access boundary. - **Connections**: credentials are named, scoped, and owned; unused keys are deleted. - **Data**: each production collection has an owner, approved selectors, tested chunks, an access policy, and a sync/retirement plan. - **Function approvals**: write, delete, publish, permission, and customer-data actions require confirmation unless explicitly approved. - **Agents**: every production agent has a purpose, prompt, model connection, data sources, tools, access policy, and test conversation. - **Workflows**: write-capable workflows are tested on safe records and have a rollback path. - **Monitoring**: admins know where to review Tool Executions, Audit Log, conversations, feedback, usage, and token limits. ## Detailed Operating Guides - [Govern Data Collections and Sources](#doc-admin-guide-govern-data-collections-and-sources) - [Configure Shared and Private Connections](#doc-admin-guide-configure-shared-and-private-connections) - [Prepare Agents and Workflows](#doc-admin-guide-prepare-agents-and-workflows-for-teams) - [Security and Governance](/security-and-governance) - [AI Go-Live Checklist](#doc-security-and-governance-ai-go-live-checklist) - [Deployment and Operations](/deployment-and-operations) --- # Plan Your Organization Setup Set the tenant identity and plan in [Organization General](#doc-organization-general), then review feature availability and reusable content in [Organization Settings](#doc-organization-settings) before broad onboarding. The wider [Organization](#doc-organization) setup also decides how people join, which public features are allowed, how [API keys](#doc-organization-api-keys) and [webhooks](#doc-webhooks) are controlled, whether recordings are available, and which identity provider owns user lifecycle. ## Decisions Before Inviting Users - Who is the organization owner and who can approve security or access changes. - Whether users join by manual invitation, SSO, Microsoft Entra synchronization, approved domains, or a mixed rollout. - Which teams need separate access boundaries for agents, workflows, connections, data, and Memory. - Which connection types should be allowed tenant-wide and which should be disabled until reviewed. - Whether public chat, public sharing, webhooks, API keys, and recordings are allowed. - Which model connections need token limits by organization, team, or user. - Where admins will review incidents: Tool Executions, Audit Log, conversation history, workflow history, and connected-system logs. ## Organization Tabs To Review | Tab | What to decide | Admin note | | --- | --- | --- | | General | Plan, subscription, organization identity, and token consumption | Confirm the tenant name and billing owner before production rollout | | Api Keys | Named keys for external integrations | Keys should map to a real system and owner; delete keys after tests | | Settings | Default agent, module availability, apps, extensions, and content imports | Enable only the surfaces approved for the organization | | Security | SSO, Entra team sync, sharing, integration policy, AI safety, and retention | Test sign-in before syncing users and treat public sharing as an explicit approval | ## Identity Setup Pattern For a small pilot, manual invitations are usually enough. For a managed organization, use SSO and Entra synchronization so user lifecycle follows the identity provider. For multi-domain organizations, document which email domains are allowed before enabling domain-based association. Use this rollout order: 1. Configure SSO metadata and test one admin sign-in. 2. Create a pilot team manually. 3. Invite or sync a small group. 4. Verify their team membership, role, and visible agents. 5. Expand synchronization or invitations only after the pilot users land in the correct organization. ## Security Switches Organization security controls can block features even when an agent or page is configured. If a user reports that public chat, webhooks, API keys, or recordings are unavailable, check organization policy before debugging the agent. | Feature | Use it when | Keep disabled when | | --- | --- | --- | | Public Chat | An approved agent should be reachable outside the internal app | Prompts, data, privacy link, or public access are not reviewed | | Webhooks | External systems should trigger Siesta AI workflows | There is no API key owner or replay/failure handling plan | | API Keys | Backend systems or developer integrations need server-side access | The integration is still exploratory or credentials would be copied into clients | | Recordings | Meeting or voice workflows require stored recordings | Retention, sharing, or consent requirements are unclear | ## Token Budget Planning Token limits are configured on model connections. Use them when a shared model connection powers high-volume agents, workflows, research, or automation. Start with organization-level defaults, then add team or user limits for groups that need a different budget or should be temporarily disabled. ## Common Mistakes - Inviting a full department before SSO and team boundaries are tested. - Leaving test API keys or webhooks active after a pilot. - Enabling public chat before the agent prompt, privacy link, uploads, and feedback settings are reviewed. - Sharing model connections without token limits for high-volume workflows. - Syncing Entra groups before confirming group ownership and membership. - Treating Organization Security as a troubleshooting afterthought instead of a launch gate. After the tenant defaults are agreed, [create the pilot teams and assign their users](#doc-admin-guide-create-teams-and-assign-users). --- # Create Teams and Assign Users [Teams](#doc-teams) are the main access boundary for shared work. Use [Users](#doc-users) with [roles](#doc-roles) to decide who belongs in the tenant and who can administer it, then use teams to scope agents, workflows, connections, Data, Memory, recordings, and task workspaces. Do not model teams only after the org chart; model them after operational access. ## Design Teams Around Risk Good teams are small enough that every member can safely use the same production resources. Examples: - `Support - Production`: can use the support agent, support data, Jira write actions with confirmation, and customer support workflows. - `Sales Ops - CRM`: can use HubSpot and reporting agents, but not finance data. - `Finance - Reporting`: can use finance data collections and read-only reporting workflows. - `Client A - Delivery`: can access client-specific agents, data, and workflows. - `AI Admins`: can edit production agents and review tool execution incidents. Avoid a single shared team for everyone unless every person should see the same agents and tools. ## Create A Team 1. Open **Teams**. 2. Click **Add Team**. 3. Enter a clear **Name** and optional **Description**. 4. Add users who need the same access boundary. 5. Submit, then use the team when sharing agents, workflows, connections, Memory, and data. Use names that explain ownership and purpose. `Support - Production` is better than `Team 1`. ## User Onboarding Flow Choose the onboarding method that fits how the organization manages identities. Keep detailed invitation, CSV, and account validation work in **Users**; use this page to connect identity setup to team access. | Method | Use when | Detailed instructions | | --- | --- | --- | | **Create User** | An administrator should create an active account immediately. | [Creating a new user](#doc-users) | | **Invite User** | The user should complete registration from an email invitation. | [Inviting users](#doc-users) | | **Import CSV** | Several users should receive invitations in one batch. | [Bulk invitation from CSV](#doc-users) | | **Approved Domain / SSO** | People with an approved company domain should join through configured Google or Microsoft SSO. | [Domain-based onboarding](#doc-users) | | **Microsoft Entra Sync** | Organization groups and their membership are managed from Microsoft Entra ID. | [Microsoft Entra synchronization](#doc-users) | Use this order for a controlled rollout: 1. **Choose the onboarding method.** Decide whether the account will be created, invited, imported, or provisioned through the organization's identity flow. 2. **Create or invite the user.** In **Users**, select **Create User**, **Invite User**, or **Import CSV**, or run the configured domain/Entra flow. ![Create User form with identity, contact, and password fields](/img/users/user-create-en.png) 3. **Assign the least-privileged role.** Start with **User** unless the person needs tenant-wide administration. Use **Administrator** or **Owner** only for the responsibilities described in [Roles](#roles). ![Assign Role dialog with Owner, Admin, and User options](/img/users/user-roles-en.png) 4. **Add the user to a team.** Open **Teams**, create or edit the correct access boundary, and add the user. Team membership is what connects the account to team-scoped agents, workflows, data, and other shared resources. ![Team creation form with a user selected for membership](/img/teams/team-create.png) 5. **Verify resource visibility.** Ask the user to sign in and confirm that the expected agents and other resources are visible, and that unrelated team resources are not. 6. **Review onboarding completion.** Check **Pending Invites** for unaccepted invitations, then confirm that the user has completed registration and appears in the intended team. > **Invite → Role → Team → Verify access** > > Creating an account does not by itself grant access to team-scoped agents or data. The role controls broad platform capabilities; team membership and resource access policies control which shared work the user can reach. :::info User administration reference The Users reference above covers invitation behavior, CSV import, approved domains, and pending invitations. ::: ## Roles Use roles for product administration, not day-to-day agent access. Agent, workflow, connection, and data access should normally be controlled through teams and access policies. | Role | Use for | Avoid using for | | --- | --- | --- | | Owner | Organization ownership, security decisions, admin-mode review | Normal power users | | Administrator | Operational administration, rollout, support, troubleshooting | Users who only need one team of agents | | User | Standard product usage | Managing tenant-wide settings | If custom role permissions are used, review them against actual tasks: inviting users, managing roles, creating agents, reviewing feedback, managing connections, and viewing audit data. ## Offboarding Checklist When a user leaves a team or organization: - Remove the user from teams they no longer need. - Reassign ownership of production agents, workflows, connections, and API keys. - Delete or rotate credentials tied to that user's external accounts. - Review private connections assigned to agents. - Check Tool Executions for pending approvals owned by the user. - Confirm SSO or Entra sync will not re-add the user. ## Troubleshooting Access If a user cannot see an agent, workflow, connection, or Memory collection: 1. Confirm the user is in the correct organization. 2. Confirm the user has the expected role. 3. Confirm the team membership. 4. Open the resource and check whether it is private, organization-wide, or shared to teams. 5. Check whether the team has **Can Use** or **Can Edit/Write** access. 6. Ask the user to refresh and remove filters before assuming the resource is missing. Once the pilot membership is correct, [define the access policies and visibility rules](#doc-admin-guide-define-access-policies-and-visibility-rules) for its shared resources. --- # Configure Shared and Private Connections [Connections](#doc-connections) are the trust boundary between Siesta AI and external systems. A connection can be a model provider, OAuth account, API key, [REST endpoint](#doc-connections-rest-api), MCP server, storage system, CRM, ticketing system, calendar, email account, or search/scraping provider. ## Connection Review Flow 1. Open **Connections** and check whether the integration already exists. 2. Add the provider or custom REST/MCP connection. 3. Name the connection with owner, system, environment, and purpose. 4. Confirm credentials are scoped to the minimum useful permission. 5. Review whether the connection is shared, private, or system-managed. 6. Review organization connection governance: provider enabled/disabled and function-level access. 7. Configure token limits for model connections where volume matters. 8. Test one read action and one write action before assigning it to a production agent or workflow. ## Shared vs Private | Type | Use when | Admin risk | | --- | --- | --- | | Shared connection | A team should use the same service account, CRM account, Jira project, Slack app, model provider, storage account, REST API, or MCP server | One credential may affect many users and agents | | Private connection | The action should happen under the current user's mailbox, calendar, Drive, or personal OAuth grant | Agent behavior depends on each user's authorization | | System-managed Connection | A built-in Platform Tool needs a Siesta-managed backend Connection | Admins must understand which agent has that Platform Tool enabled | Do not connect a personal account as a shared production connection unless the external system has no service-account option and the business owner accepts the operational risk. ## Function Governance Organization connection governance can disable a connection type or force specific functions into confirmation mode. The effective function access uses the strictest setting between organization policy and connection-level configuration. Use this baseline: | Function behavior | Default posture | | --- | --- | | Search, list, read, summarize | Enable when the agent audience is allowed to see the data | | Draft, preview, validate | Enable when the user can review before acting | | Create, update, send, post, move | Require confirmation unless the business process explicitly allows direct execution | | Delete, publish, permission changes, financial/customer updates | Require confirmation and narrow team access | | Unknown REST/MCP function | Require confirmation until tested and documented | For REST tools, confirm path parameters, query parameters, body fields, and static headers. For MCP tools, confirm server URL, custom headers, function names, schemas, and ownership. ## Token Limits For Model Connections Model connections can have organization, team, and user token limits. Use these when a shared model connection powers high-volume agents or workflows. A team or user can also be disabled on a connection when temporary containment is needed. For Azure AI Foundry model router connections, review the Azure deployment type, routing mode, and model subset before sharing the connection. The deployment type answers data-residency questions, the routing mode controls the cost-quality posture, and the subset defines which underlying models are allowed. Practical examples: - Set organization limits for general model usage. - Set team limits for research-heavy or automation-heavy teams. - Set user limits for pilots, contractors, or unusually high-volume accounts. - Disable a user or team on a model connection during an incident instead of deleting the connection. ## Credential Rotation Rotate credentials when: - the owner changes, - a test integration becomes production, - a provider reports suspicious activity, - a shared workflow is retired, - a contractor or temporary admin leaves, - a key was copied into a prompt, browser, client app, or ticket. After rotation, test the connection and review Tool Executions for failures. ## Production Acceptance Checklist - The connection has a business owner. - The credential scope is documented. - The provider is allowed in organization governance. - Write functions have confirmation where needed. - Model token limits are set where needed. - The connection is shared only with the right teams. - A test agent or workflow has produced a successful entry in Tool Executions. - Failure behavior is understood before the connection is used by a team. After the credential and sharing boundary is accepted, [set up the tools, APIs, and MCP access](#doc-admin-guide-set-up-tools-apis-and-mcp-access) that the connection exposes. --- # Govern Data Collections and Sources Administrators use [Data](#doc-data-collections) to govern the boundary between external systems, stored credentials, indexed content, collection access, and the agents that use that content. A source working technically is not enough: it must also have a clear owner, approved scope, refresh policy, and retirement path. ## The Data Guide 1. [Configure data upload limits](#doc-data-collections-upload-limits) to establish sensible defaults and per-user exceptions before ingestion begins. 2. [Configure enabled connections](#doc-organization-security) to control which integrations are approved for your organization. 3. [Choose the best data source for your use case](#doc-data-choose-a-source) before storing or synchronizing business content. 4. [Design a data collection architecture for your teams](#doc-teams) so ownership and access match how your organization operates. 5. [Create and populate your first data collection](#doc-data-collections) using the approved scope and access model. 6. [Monitor data-storage utilization](/analytics#data) to track consumption and address capacity risks early. Use these pages as the implementation checklist; use this Admin Guide to define identity ownership, least privilege, collection access, review, monitoring, and retirement. For every source, keep these objects separate: - **Connection**: authentication and provider identity. - **Data source**: the folder, path, blob selector, share, project, space, or URL being ingested. - **Collection**: the access-controlled business grouping. - **Agent assignment**: which production behaviors can retrieve from the collection. ## Admin Design Checklist Before creating a production source, decide: - Who owns the upstream content? - Which service or user identity will authenticate? - Which exact folders/projects/spaces/paths are in scope? - Who may use the resulting collection? - Who may edit, move, synchronize, or delete its sources? - How quickly must upstream changes appear? - How will you test retrieval quality and missing-answer behavior? - What happens when the credential owner leaves or the source is retired? --- # Set Up Tools, APIs, and MCP Access [Tools](#doc-tools) let [agents](#doc-agents) and [workflows](#doc-workflow) read data, create records, send messages, call APIs, run system capabilities, or reach MCP servers. Use the [REST API](#doc-developers-rest-api-getting-started) when a customer application, internal portal, or automation backend needs server-side access to Siesta AI. Admins do not need to design every schema, but they do need to decide which tools can run, who can use them, and which actions require confirmation. ## Tool Setup Flow 1. Create or select the connection. 2. Review available functions, parameters, and credential fields. 3. Classify each function as read, draft, write, delete, publish, or administrative. 4. Apply organization or connection-level function access: enabled, enabled with confirmation, or disabled. 5. Share the connection only with the teams that need it. 6. Assign the tool to the agent, skill, prompt, or workflow. 7. Test with safe data. 8. Confirm the result in Tool Executions and in the target system. ## REST API Tools REST tools are production contracts. Before allowing one in a shared agent: - Confirm the base URL and environment. - Confirm authentication lives in the connection, not in prompts. - Confirm every function has a method, path template, parameter location, and purpose. - Use static parameters only for values that should never be user-controlled. - Require confirmation for POST, PUT, PATCH, DELETE, and any operation that changes state. - Test error responses so users get useful failure messages. If a REST tool points at an internal system, document the owning team and escalation path. ## MCP Tools MCP servers can expose broad capability through a single connection. Treat them like privileged tools: - Know who owns the server. - Review custom headers and secret handling. - List the tool groups and functions the server exposes. - Require confirmation for write-capable tools until the functions are proven safe. - Keep MCP access limited to the teams that need it. ## Platform Tools Platform Tools are built-in Siesta AI capabilities assigned to agents. Review them before publishing an agent template or sharing an agent broadly. | Platform Tool | Use when | Admin risk | | --- | --- | --- | | Task Management | The agent should create Siesta tasks | Low-quality task creation or duplicate tasks | | Grounding with Google Search | The agent must verify current public information | External source quality and citation review | | Web scraper | The agent should read a specific page URL | Scraping policy, sensitive URLs, or stale page context | | Code interpreter | The agent should analyze files or produce outputs | Data exposure, generated files, and user trust in calculations | | Platform Tools | The agent should manage Siesta platform objects | Agent, Memory, template, or platform configuration changes | | Orchestration | The agent should route work to sub-agents | Cost, call volume, and unclear ownership | | JavaScript executor | The agent should run scripts or process structured files | High autonomy and logic errors | Use advanced Platform Tools only for admin or power-user agents until they have a tested operating pattern. ## API Keys And Webhooks Use **Organization > Api Keys** for server-side integrations. API keys should never be embedded in browser code, public pages, screenshots, prompts, or client apps. Use **Webhooks** when an external system should trigger a Siesta AI workflow. Each webhook should have: - a name that identifies the source system, - an active/inactive state, - an assigned API key, - a workflow owner, - a sample payload, - a failure and replay plan. Treat webhook callers as server-side integrations. Do not rely on the webhook URL alone as the trust boundary; pair it with the assigned API key and rotate that key when ownership or environment changes. Keep webhooks inactive until the calling system is ready. ## Approval Rules Use confirmation for functions that send messages, create or update external records, modify permissions, publish content, delete data, move files, trigger production processes, or touch financial/customer data. Do not rely only on prompt wording for safety. Function-level access is the enforceable control; prompt instructions are supporting guidance. ## Release Checklist - Credentials are stored in the connection. - The connection is not shared more broadly than needed. - High-impact functions require confirmation. - REST/MCP schemas are tested with real parameters. - Failed calls return actionable errors. - Tool Executions show arguments, status, result, execution time where available, and approval state. - A business owner knows how to verify the outcome in the target system. Attach only accepted tools when you [prepare production agents and workflows for teams](#doc-admin-guide-prepare-agents-and-workflows-for-teams). --- # Define Access Policies and Visibility Rules Access policies decide who can see, use, and edit resources. Use [Users](#doc-users) and [Roles](#doc-roles) to assign tenant-level responsibilities, then apply resource access through [agent configuration](#doc-agents-configuration), [teams](#doc-teams), and each resource's sharing settings. The practical model is: keep work private while building, share to specific teams for rollout, and use organization-wide access only for approved general resources. ## How Access Works Plan around these rules: - If an access-controlled resource has no sharing mode, treat it as private. - The creator can access the resource they created. - Owner/Admin mode can review organization resources where the user's role allows it. - Organization access can allow use or write access for everyone in the tenant. - Team policies can allow **Can Use** or **Can Edit/Write** for selected teams. - External provider permissions still apply. Siesta access does not give a user access to Gmail, Drive, Jira, HubSpot, or another provider if the provider rejects the action. ## Where To Configure Access | Resource | Where to review | What to decide | | --- | --- | --- | | Users | Users and Roles | Who can administer the tenant, invite users, and manage roles | | Teams | Teams | Which people share the same operating boundary | | Agents | Agents > Access | Private, shared, organization-wide, and team edit rights | | Connections | Connections and Organization connection governance | Who can use credentials and which functions run | | Workflows | Workflows > Access / Sharing | Which teams can run or edit the workflow | | Data and Memory | Data, Memory collections, and collection access | Which agents and teams can retrieve the content | | Conversations and recordings | Organization Security and sharing settings | Whether public sharing is allowed | ## Use vs Edit/Write Use access lets someone run a resource. Edit/write access lets someone change behavior, prompts, tools, workflow nodes, sharing, or data linkage. Treat edit/write access as an operational responsibility, not a convenience. Use this default: - Give **Can Use** to users who should run the agent or workflow. - Give **Can Edit/Write** only to owners who can approve behavioral changes. - Keep draft agents private until prompts, tools, and data are reviewed. - Share pilots to one team before organization-wide release. - Recheck access after every credential rotation, team restructure, or workflow change. ## Admin Mode Admins may use an Admin switch in the application header. With normal mode, the product applies the admin's ordinary user visibility. With Admin mode, elevated organization visibility is used where the role permits it. Use Admin mode to troubleshoot: - whether a resource exists, - whether a user is missing team access, - whether an agent is private, - whether a workflow is shared incorrectly, - whether conversations, tool executions, or data collections need review. Admin mode does not bypass external provider permissions, private connection ownership, disabled functions, confirmation requirements, or organization security policy. ## Troubleshooting Missing Resources When a user says "I cannot see it": 1. Confirm the organization in the app header. 2. Confirm the user exists and has the expected role. 3. Confirm team membership. 4. Open the resource in Admin mode and check the access policy. 5. Confirm the resource is not still private to the creator. 6. Confirm organization access or team access grants **Can Use**. 7. If the user needs to edit, confirm **Can Edit/Write** explicitly. ## Troubleshooting Tool Access When an agent cannot use a connection: 1. Confirm the connection is assigned to the agent as shared or private. 2. For private tools, confirm the current user owns the required private connection. 3. Confirm the organization has not disabled the connection type. 4. Confirm the function is not disabled by organization governance. 5. Confirm the user or team can use the connection. 6. Confirm the external provider credential is still valid. 7. Open Tool Executions to inspect status, arguments, result, and approval state. ## Public Access Public chat, public conversation sharing, public recording sharing, API keys, webhooks, and recordings can be blocked by organization policy. If a page is configured correctly but public behavior fails, check **Organization > Security** before editing the agent. For public agents, review: - public chat enabled at organization level, - public chat enabled on the agent, - privacy link, - feedback and file-upload settings, - allowed tools, - prompt boundaries, - retention and sharing settings, - whether the widget or public page should use a production agent. ## Policy Examples - Company help agent: organization **Can Use**, AI Admins **Can Edit**. - Support ticket agent: Support **Can Use**, Support Leads **Can Edit**, Jira write functions require confirmation. - Finance reporting agent: Finance **Can Use**, Finance Admins **Can Edit**, no organization-wide access. - Website widget agent: public chat enabled, narrow prompt, reviewed privacy link, limited tools, monitored feedback. - Experimental workflow: private to creator until read and write Tool Executions are reviewed. Apply these rules while you [configure shared and private connections](#doc-admin-guide-configure-shared-and-private-connections) and before you publish agents or workflows. --- # Prepare Agents and Workflows for Teams Production [agents](#doc-agents) should use reviewed [configuration](#doc-agents-configuration) and [workflows](#doc-workflow) to solve specific jobs with deliberate Data, [tools](#doc-tools), prompts, access, and monitoring. Avoid publishing generic assistants that can see too much and do not have an owner. ## Production Agent Checklist Before sharing an agent with a team, review: - **Name and description**: users can identify the job it performs. - **Owner**: one person or team owns changes and incidents. - **Model connection**: the model/provider is approved for the workload. - **Prompt**: role, boundaries, output style, escalation, and refusal behavior are explicit. - **Data**: data collections, Memory, files, and connected sources are intentional. - **Shared tools**: service-account tools are approved for the agent audience. - **Private tools**: user-owned tools are required only when user context matters. - **Platform Tools**: built-in advanced capabilities are enabled only when the job needs them. - **Access**: private for build, team-shared for pilot, organization-wide only after approval. - **Monitoring**: conversations, feedback, Tool Executions, analytics, and history have an owner. ## Agent Configuration Problems | Symptom | Likely cause | Admin action | | --- | --- | --- | | Agent says it has no data | Data collection, Memory, or connection is not attached or not shared | Attach the source and test retrieval | | Agent cannot call a tool | Connection is missing, private connection belongs to another user, or function is disabled | Review assigned tools and connection governance | | Agent asks for approval too often | Write functions are correctly in confirmation mode, or too many operations are modeled as writes | Keep confirmations for risky actions; refine tool design for safe reads | | Agent gives inconsistent answers | Prompt is too broad, data source is stale, or model setting is unsuitable | Tighten the prompt, refresh data, and test with known cases | | Users can edit production behavior | Team has edit/write access instead of use access | Restrict edit access to owners | ## Workflow Preparation Use workflows for repeated processes with predictable steps. A workflow should have known inputs, clear node dependencies, safe error behavior, and a rollback path for write actions. Before publishing: 1. Name the workflow by business process. 2. Define required inputs and expected output. 3. Use read nodes before write nodes whenever possible. 4. Keep write nodes behind confirmation when impact is high. 5. Test on non-production records. 6. Review Tool Executions for each connection action. 7. Review workflow History after every major edit. 8. Share with one pilot team before expanding access. ## Workflow Examples | Workflow | Recommended controls | | --- | --- | | Support request -> Jira issue -> Slack notification | Jira create and Slack post require confirmation during pilot | | HubSpot deal lookup -> meeting prep -> calendar draft | CRM reads can be direct; calendar updates need user context or confirmation | | Webhook incident intake -> classify -> task creation | Webhook has a named API key, sample payload, and failure replay plan | | Data refresh -> summary -> report file | Use safe test folders and inspect generated files before team rollout | ## If A Workflow Changed The Wrong Record 1. Pause or narrow workflow sharing. 2. Open Tool Executions and find the write action. 3. Capture function name, arguments, result, approval status, user, and timestamp. 4. Check the preceding node output that supplied the record ID. 5. Confirm whether the connection had too-broad permissions. 6. Add confirmation, stricter parameters, or a validation step. 7. Retest on safe records. 8. Re-enable access only after the owner signs off. ## Templates Use [templates](#doc-templates) only after the agent has a proven configuration. A template can copy useful prompts, tools, Data assumptions, and Platform Tools into new agents, so a bad template spreads problems quickly. Before publishing a template: - remove test credentials and draft prompts, - confirm access defaults, - check Platform Tools, - document intended audience, - create one agent from the template and test it end to end. When the pilot is live, [monitor usage, audit evidence, and risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk) before expanding access. --- # Monitor Usage, Audit Logs, and Risk After launch, admins need an evidence trail for what users ran, what tools changed, which configuration changed, and whether agents are helping or creating risk. Use Tool Executions, [Audit Log](#doc-audit-log), [conversations](#doc-conversations), feedback, and [analytics](/analytics) as separate signals alongside workflow history and token usage. ## What To Monitor | Signal | Use it for | | --- | --- | | Tool Executions | Tool calls, status, arguments, results, approvals, failures, and execution time | | Audit Log | Configuration and access changes with user, entity, timestamp, correlation ID, and changed fields | | Conversations | Real user behavior, prompt gaps, incorrect answers, and sensitive-data exposure | | Feedback | Negative ratings, user corrections, and improvement candidates | | Agent Analytics | Usage, tokens, active users, performance, and adoption trends | | Workflow History | Changes to workflow logic and run behavior | | Token limits | Budget control for shared model connections by organization, team, or user | ## Tool Executions Use **Tool Executions** whenever an agent or workflow uses a Connection function, REST tool, MCP tool, Platform Tool, or sub-agent-like action. Review these fields during troubleshooting: - agent and conversation, - action/function, - status: **Pending**, **Success**, **Failed**, or **PendingApproval**, - input arguments, - result and error message, - whether approval was required, - who approved or rejected, - resolved time, - execution time where available. If a user says "the agent did the wrong thing", start here before editing prompts. Tool Executions show what was actually sent to the tool. ## Audit Log Use **Audit Log** for configuration and access changes. Audit entries include the changed entity, change type, user, organization, timestamp, correlation ID, and changed properties. Pair Siesta audit data with logs from the connected external system when investigating record changes. Audit review is especially important after: - SSO or organization security changes, - team membership changes, - access-policy changes, - connection credential changes, - agent prompt/tool/data changes, - workflow edits, - API key or webhook changes. ## Incident Playbooks ### A Tool Failed 1. Open Tool Executions and find the failed action. 2. Check arguments, result, error message, and connection. 3. Verify the external credential still works. 4. Check whether the organization disabled the provider or function. 5. Retest with safe input. 6. If the failure is user-specific, check private connection ownership. ### A Write Action Needs Approval 1. Confirm the function is intentionally in confirmation mode. 2. Review the arguments and target record before approving. 3. If approvals are too noisy, split safe read/draft functions from write functions. 4. Do not remove confirmation from customer, financial, delete, publish, or permission-changing actions without owner approval. ### Token Usage Spiked 1. Identify the model connection. 2. Check usage by agent, workflow, team, and user. 3. Review recent workflow changes and automated runs. 4. Add or tighten org/team/user token limits. 5. Pause high-volume workflows if needed. 6. Review whether the agent is using unnecessary long context, files, or repeated tool calls. ### A Public Agent Answered Poorly 1. Check the conversation and feedback. 2. Confirm the public agent has the right prompt and allowed tools. 3. Review uploaded files, public page context, and data collections. 4. Check whether public chat settings allow feedback, uploads, and privacy behavior as intended. 5. Patch the prompt or data source, then retest through the public/widget path. ## Operating Rhythm For the first week after launch, review Tool Executions and feedback daily. After stabilization, review weekly for production teams and after every major change. Use a simple monthly review: - remove stale users and teams, - rotate or delete unused API keys, - disable unused webhooks, - review shared connections and function confirmations, - check token limits against usage, - review high-risk agents and workflows, - confirm public features are still intended. For the detailed investigation flow, continue with [Review Tool Executions](/tool-executions). Feed the results into [Deployment Reporting and Monthly Operations Review](#doc-admin-guide-adoption-and-rollout-deployment-reporting-and-monthly-operations-review). --- # Review Tool Executions The **Tool Executions** page is part of **Logs**. Open **Logs** and choose **Tool Executions** to review actions that [agents](#doc-agents) performed through connected [tools](#doc-tools). This view helps identify which agent ran which action, which conversation triggered the action, and whether it completed, failed, or is waiting for approval. The related [**Audit Log**](#doc-audit-log) view in Logs focuses on administrative and system changes. Use Tool Executions when you need to inspect agent/tool activity, tool inputs, tool results, or approval decisions. This is an administrator and agent-manager workflow. Give access only to people responsible for approvals, troubleshooting, operations, or audit evidence. ## Table Overview The table contains these columns: - **Agent** - the agent that triggered the action. - **Conversation** - link to the conversation that created the tool execution. - **Action** - function and tool name. - **Status** - current execution or approval status. - **Resolved at** - time when the action was resolved. - **Resolved by** - user who approved or rejected the action. Above the table, search and pagination help users work with larger numbers of records. Where the released integration reports it, the execution detail can also expose execution-time information so admins can distinguish a quick failure from a slow or timing-sensitive tool call. ## Execution Statuses A tool execution can have these statuses: - **Pending** - the action was created and is waiting to run or complete. - **Success** - the action completed successfully. - **Failed** - the action ended with an error. - **PendingApproval** - the action requires human approval before it can continue. The approval status can be: - **Approved**, - **Rejected**, - **Pending**, - **Approval not required**. ## Approval Model Approvals are used when a connected function should not run automatically. This is most important for functions that can change business data, send messages, create records, update external systems, or trigger downstream workflows. Function access is controlled through connection governance: - **Disabled** - the function is not available to agents or workflows. - **Enabled** - the function can run without an approval step. - **EnabledWithConfirmation** - the function can be proposed by an agent, but it must be approved before execution. When a tool execution is waiting for approval, the table shows the action, conversation, agent, status, and resolution fields. Approving the action allows the tool call to continue. Rejecting the action prevents the tool call from being executed. Both decisions remain traceable through the resolved time and the user who approved or rejected the action. Use approval requirements for data-modifying functions, high-impact workflow steps, or integrations where a human needs to verify the proposed arguments before the action runs. ## Execution Detail The execution detail can be opened from the table. The detail shows: - arguments passed to the tool, - call result, - execution time where available, - whether approval is required, - approval status. If arguments or results are not available, the detail shows an empty state. ## When to Check This Section - When an agent performed an unexpected action. - When a user is waiting for a tool result and the action remains **Pending**. - When a tool failed and you need to inspect the input arguments. - When the organization uses tool approvals and needs to check who approved or rejected an action. ## Debugging Recipe 1. Open the related conversation and identify the exact tool action. 2. Inspect the submitted arguments, result, execution status, and approval status. 3. Confirm that the selected Connection and connected account have the required upstream permission. 4. Compare the attempted action with the agent's assigned tools and function governance. 5. Retry only after correcting the permission, input, Connection, or provider problem. ## What Users Should Send an Admin Ask users to provide the agent name, conversation title, tool action, approximate execution time, status, error message, and the external record or workspace that should have been used. They must not send access tokens, API keys, passwords, or full secret-bearing screenshots. ## Related Governance - Use [Connections](#doc-connections) to configure available integrations, function access, and confirmation requirements. - Use **Audit Log** to review administrative changes that affected tools, access, or governance. - Use [Organization](#doc-organization) to review tenant-wide security settings that influence public access and safety behavior. --- # Organizational AI Readiness ![Readiness dimensions for an organizational AI rollout](/img/guides/ai-readiness.svg) AI readiness is not a single technology score. An organization is ready for a specific initiative when it can name the outcome, provide appropriate evidence, assign accountable owners, manage the risks, and support the people who will use the result. In Siesta AI, record the tenant owner and plan in [Organization General](#doc-organization-general), then make delivery ownership explicit across [teams](#doc-teams), [Data](#doc-data-collections), and production [agents](#doc-agents). ## Review Five Dimensions | Dimension | Evidence to collect | Warning sign | | --- | --- | --- | | Business value | Decision, delay, cost, quality, or risk the initiative should improve | The goal is simply “use AI” | | Data | Approved sources, owners, quality checks, and access boundaries | The team assumes every file can be indexed | | Delivery | Business owner, admin owner, pilot users, and available testing time | Ownership ends after configuration | | Risk | Error impact, approval needs, privacy constraints, and rollback path | A fluent answer is treated as proof | | Adoption | Target users, workflow fit, training, and feedback channel | Success is measured only by launch | ## Readiness Questions Before approving discovery, answer these questions: 1. What decision or workflow should improve? 2. Who is accountable for the business outcome? 3. Which sources are authoritative, and who owns them? 4. What could happen if the output is incomplete or wrong? 5. Which actions must require confirmation? 6. Who will test realistic cases before rollout? 7. Which measurable signal will support a continue, adjust, or stop decision? ## Classify the Starting Point - **Ready for discovery**: the problem and owner are clear, but feasibility still needs evidence. - **Ready for a pilot**: data, access, risk, and success criteria are defined for a limited group. - **Ready for rollout**: pilot evidence is accepted, controls are configured, support is owned, and a rollback path exists. - **Not ready**: the initiative lacks a real owner, approved sources, a testable outcome, or a safe operating boundary. Do not use an average score to hide a critical gap. Missing ownership or uncontrolled access should stop the initiative even when other dimensions look strong. ## Record the Decision Capture the scope, owner, evidence, known constraints, risk level, next review date, and the decision: proceed, narrow, investigate, or stop. Before shaping opportunities, align stakeholders with [Setting Realistic AI Expectations](#doc-admin-guide-adoption-and-rollout-setting-realistic-ai-expectations). --- # Setting Realistic AI Expectations Large language models are effective at working with language and patterns, but fluency is not the same as correctness. Set expectations around the task, evidence, and impact rather than around a broad promise that “AI understands the business.” Translate the agreed boundary into production [Agent Prompts](#doc-agents-prompts), apply it through [agents](#doc-agents) and [workflows](#doc-workflow), then use Feedback to check whether real outputs meet it. ## Use AI Where the Work Fits AI is usually a strong assistant for summarizing, drafting, classifying, translating, extracting structured fields, comparing documents, brainstorming alternatives, and answering questions over approved sources. Use [Choose Tasks AI Can Do Well](#doc-user-guide-ai-working-practices-choose-tasks-ai-can-do-well) and [Recognize Tasks AI Should Not Own](#doc-user-guide-ai-working-practices-recognize-tasks-ai-should-not-own) when communicating these boundaries to pilot users. Reliability decreases when work depends on: - exact calculations without a calculation tool, - current facts without a live connection, - pixel-perfect measurements from technical images, - complete recall outside the supplied context, - deterministic wording across repeated runs, - legal, medical, financial, or safety judgments without expert review. ## Define an Operating Boundary For every production agent or workflow, document: | Boundary | Example decision | | --- | --- | | Allowed | Draft a response from approved support articles | | Allowed with review | Compare contract clauses and flag possible differences | | Tool required | Calculate totals using a controlled calculation function | | Human decision | Approve a contract, payment, hiring decision, or safety action | | Prohibited | Invent missing evidence or bypass an access restriction | ## Communicate Uncertainty Prompts and workflow instructions should require the system to separate sourced facts, interpretations, assumptions, and open questions. When evidence is missing, the correct response is to identify the gap—not to complete the story. For consequential work, require citations or source links and make the reviewer confirm that the cited material actually supports the conclusion. See [AI Safety & Quality](#doc-security-and-governance-ai-safety) for evaluation and release controls. ## Set a Better Success Measure Avoid promising a universal accuracy or time-saving percentage. Measure the deployed workflow instead: - reviewer acceptance rate, - correction rate and severity, - time to a verified outcome, - coverage of required evidence, - failed or rejected tool actions, - user adoption in the target process. An initiative succeeds when it improves a defined outcome inside an acceptable risk boundary. A visually convincing response is not, by itself, a successful result. With that boundary agreed, continue to [Finding AI Initiative Candidates](#doc-admin-guide-adoption-and-rollout-finding-ai-initiative-candidates). --- # Finding AI Initiative Candidates Start with work that already has an owner and a recognizable outcome. Capture candidate work in [Tasks](#doc-tasks), but reserve [Workflows](#doc-workflow) for a process whose repeated steps and controls are already understood. Avoid beginning with a model, agent type, or integration and then searching for a problem that justifies it. For user-level examples, compare [Choose Tasks AI Can Do Well](#doc-user-guide-ai-working-practices-choose-tasks-ai-can-do-well). ## Look for Repeatable Friction Good candidate areas often include: - repeated reading, comparison, extraction, or classification, - fragmented knowledge that slows a decision, - recurring drafts that follow a known structure, - high-volume requests that require the same first-pass analysis, - workflows where people repeatedly copy context between systems, - review queues where evidence can be prepared before human approval. ## Write a Candidate Brief Use one page and record: | Field | What to capture | | --- | --- | | Problem | Observable delay, error, cost, or risk | | Users | People who perform or review the work | | Outcome | Decision or deliverable the work must support | | Inputs | Required documents, records, events, and systems | | Output | Expected structure and where it goes next | | Actions | Read and write operations the system may perform | | Controls | Access, approvals, verification, and retention requirements | | Owner | Business owner and delivery owner | | Evidence | Baseline and pilot success measures | ## Check the Fit A strong candidate is language-heavy, has approved inputs, produces a reviewable output, and can begin with a limited pilot. A weak candidate has an undefined owner, depends on unavailable data, requires perfect autonomous judgment, or creates irreversible impact without a human checkpoint. ## Narrow the First Version Prefer one department, one approved [Data collection](#doc-data-collections), one output format, and one decision point. Remove external write actions until the read-only result is useful. Add [tools](#doc-tools) and automation only after the team can explain how failures will be detected and handled. The output of this exercise is not approval to build. It is a candidate ready for [Prioritizing AI Initiatives](#doc-admin-guide-adoption-and-rollout-prioritizing-ai-initiatives) and a feasibility review. --- # Prioritizing AI Initiatives Organizations should run fewer initiatives than they can imagine. Keep candidate ownership and status visible in [Tasks](#doc-tasks), and use [Analytics](/analytics) as evidence only after a pilot has produced real usage. Every active initiative consumes business ownership, user attention, IT and security cooperation, testing capacity, and change-management effort. ![Four stages for selecting and governing AI initiatives](/img/guides/initiatives.svg) ## Score With Evidence Use a simple 1–5 score, but require a short evidence note for every value. | Criterion | Question | High-priority signal | | --- | --- | --- | | Business value | Will it improve an important outcome? | Clear, measurable impact | | User demand | Do target users actively need it? | Named users and workflow pull | | Feasibility | Are [Data](#doc-data-collections), access, [connections](#doc-connections), and owners available? | Realistic first version | | Adoption | Will it fit the way people work? | Clear users, training, and support | | Strategic fit | Does it support an agreed priority? | Sponsor and roadmap alignment | | Complexity | Is the expected value proportionate to effort? | Small bounded pilot | | Risk | Are consequences and controls understood? | Manageable, reviewable impact | Do not let a high total compensate for an unacceptable risk, missing owner, or unavailable data. Treat these as gates. ## Choose a Portfolio Maintain three states: - **Active**: funded, owned, and within current delivery capacity. - **Next**: sufficiently defined but waiting for capacity or a dependency. - **Explore**: useful idea that needs discovery before it can be ranked. Limit active work until each initiative has time for realistic testing and feedback. Starting ten pilots and finishing none provides less evidence than completing two well-governed pilots. ## Make the Decision Visible For each candidate, record the score, evidence, blocking gates, decision owner, status, and next review date. Revisit prioritization when business conditions, source availability, policy, or delivery capacity changes. Approved candidates move into the [Initiative Lifecycle and Governance](#doc-admin-guide-adoption-and-rollout-initiative-lifecycle-and-governance). --- # Initiative Lifecycle and Governance ![Seven-stage lifecycle for a governed AI initiative](/img/guides/initiative-lifecycle.svg) An initiative should produce evidence and a decision at every stage. Progress is not measured by how much [agent](#doc-agents) or [workflow](#doc-workflow) configuration exists; it is measured by whether the team can justify continuing. ## Seven Stages | Stage | Minimum output | Decision | | --- | --- | --- | | Identify | Problem, users, expected value, initial owner | Is discovery worthwhile? | | Discover | Feasibility, scope, success criteria, risks, dependencies | Is a pilot safe and useful? | | Pilot | Limited setup, realistic cases, user feedback | Continue, adjust, pause, or stop? | | Configure | Prompts, data, tools, access, approvals, and documentation | Is the operating boundary complete? | | Test | Acceptance evidence, issues, fixes, and go/no-go recommendation | Is rollout justified? | | Roll out | Onboarding, support, monitoring, and feedback loop | Is adoption healthy? | | Optimize | Usage and quality review, updated roadmap | Improve, expand, hold, or retire? | ## Assign Governance Roles - **Business owner** owns the outcome and prioritization. - **Admin or delivery owner** owns configuration and coordination. - **Data and system owners** approve sources and integrations. - **Security reviewer** approves access, controls, and residual risk. - **Pilot users** test real scenarios and report usability gaps. - **Release approver** makes the go-live decision. One person may hold more than one role in a small pilot, but the responsibilities must remain explicit. ## Keep a Decision Record At each gate, record the evidence reviewed, open risks, accepted limitations, decision, approver, and next review date. Link the record to relevant agent versions, workflow versions, evaluation results, tool executions, and configuration changes captured in the [Audit Log](#doc-audit-log). Use [AI Go-Live Checklist](#doc-security-and-governance-ai-go-live-checklist) before production rollout. When the initiative enters delivery, continue to [Enterprise Kick-off](#doc-admin-guide-adoption-and-rollout-enterprise-kick-off); after launch, use [Deployment Reporting and Monthly Operations Review](#doc-admin-guide-adoption-and-rollout-deployment-reporting-and-monthly-operations-review). --- # Enterprise Kick-off ![Five decisions for an executable enterprise kick-off](/img/guides/kickoff.svg) A kick-off is complete when the delivery team can start safely—not when introductions are finished. Confirm the tenant identity and plan in [Organization General](#doc-organization-general), then use the meeting to turn the approved initiative into named work, owners, dependencies, and decisions for the relevant [teams](#doc-teams), [agents](#doc-agents), and [workflows](#doc-workflow). ## Required Participants Include the business sponsor, customer project owner, platform admin, infrastructure or IT owner, security representative, data owners for the first use case, delivery lead, and at least one pilot-user representative. ## Agenda 1. Confirm the business outcome and first-phase boundaries. 2. Agree on vocabulary for initiatives, configuration, product issues, infrastructure changes, and custom work. 3. Name accountable owners and escalation contacts. 4. Review the [organization setup](#doc-admin-guide-plan-organization-setup), deployment model, identity, network, Data, and tool dependencies. 5. Select the first pilot and define its exit criteria. 6. Establish the working channel, meeting cadence, decision log, and reporting format. 7. Record immediate actions, owners, and due dates. ## Decisions to Capture | Decision | Expected result | | --- | --- | | Scope | In-scope outcome, users, systems, and explicit exclusions | | Ownership | Business, admin, security, data, and delivery owners | | Environment | Deployment model and responsibility boundaries | | Access | Identity setup, required accounts, source approvals, and credential process | | Pilot | Target users, scenarios, success measures, and stop conditions | | Cadence | Working channel, weekly review, technical sessions, and escalation path | ## Exit Criteria Do not close the kick-off until unresolved access and security questions have owners and dates. The output should include a confirmed roadmap, responsibility matrix, first pilot brief, dependency list, meeting schedule, and decision log. Continue with [Rollout Roles and Delivery Cadence](#doc-admin-guide-adoption-and-rollout-rollout-roles-and-delivery-cadence) and the appropriate [Deployment Model](#doc-deployment-and-operations-deployment-models). --- # Rollout Roles and Delivery Cadence ![Phased enterprise rollout delivery cadence](/img/guides/rollout.svg) Enterprise rollout crosses product configuration, infrastructure, identity, security, [Data](#doc-data-collections), training, and change management. A shared cadence keeps [teams](#doc-teams), [agents](#doc-agents), and source ownership coordinated and makes blockers visible early. ## Responsibility Model | Workstream | Primary owner | Required collaborators | | --- | --- | --- | | Business outcome | Business sponsor | Pilot users, delivery lead | | Deployment | Infrastructure owner | Platform engineering, security | | Identity and policy | Admin owner | Identity team, security | | Sources and integrations | Data or system owner | Admin, integration owner | | Agent and workflow setup | Delivery owner | Business owner, pilot users | | Testing and acceptance | Business owner | Pilot users, admin, security | | Onboarding and adoption | Change owner | Team managers, support | | Operations | Admin owner | Security, support, business owner | ## Operating Cadence - **Working channel** for day-to-day questions, actions, and evidence links. - **Weekly delivery review** for status, blockers, decisions, initiative progress, and upcoming changes. - **Technical deep dive** only when a design or incident needs the relevant specialists. - **Monthly operations review** for outcomes, adoption, quality, incidents, risks, and next priorities, supported by [Analytics](/analytics). Every meeting should end with decisions, actions, owners, and due dates. Store notes where participants can review the same record. ## Escalate Explicitly Define paths for missing access, security exceptions, delayed data ownership, product defects, failed deployments, and scope changes. A blocker without an owner and requested decision is only a status update. ## Transition to Operations Handover requires named support ownership, monitoring access, known-issue records, rollback instructions, source and credential ownership, incident contacts, and the first scheduled operations review. See [Rollout and Handover](#doc-deployment-and-operations-rollout-and-handover) for the technical handover checklist, then continue to [Deployment Reporting and Monthly Operations Review](#doc-admin-guide-adoption-and-rollout-deployment-reporting-and-monthly-operations-review). --- # Deployment Reporting and Monthly Operations Review ![Synthetic operational review showing delivery, adoption, risk, and decisions](/img/guides/operations-report.svg) Use reporting to make decisions, not to produce activity summaries. During rollout, track completion and acceptance. After go-live, combine [analytics](/analytics), [Audit Log](#doc-audit-log), and feedback with business evidence to review outcomes, quality, operational health, risk, and ownership. ## Rollout Report Include: - executive status and target go-live, - completed, in-progress, blocked, and deferred deliverables, - identity, access, data-source, agent, workflow, and training status, - pilot evidence and unresolved acceptance issues, - milestones, blockers, owners, and next decisions, - handover readiness and remaining operational dependencies. Avoid fixed package claims or generic completion percentages. Report the actual agreed scope and explain how each status was verified. ## Monthly Operations Review ![Synthetic KPI review with targets, actuals, status, and actions](/img/guides/kpi-report.svg) Prepare a short review covering: | Section | Required evidence | | --- | --- | | Outcomes | Target, actual, trend, and interpretation | | Adoption | Intended users, active use, workflow fit, and training gaps | | Quality | Acceptance, corrections, feedback, and evaluation failures | | Operations | Tool failures, approvals, incidents, latency, and availability | | Risk | New, changed, accepted, and overdue risks | | Improvements | Prompt, data, tool, workflow, or policy changes and their effect | | Decisions | Decision needed, options, recommendation, owner, and deadline | ![Synthetic analytics view separating usage, quality, operations, and value](/img/guides/analytics-report.svg) ## Reporting Rules - Use numbers where a reliable measure exists; otherwise state what is not measured. - Separate delivered work from accepted outcomes. - Give every blocker and risk an owner and next action. - Link significant claims to audit logs, tool executions, evaluation results, incident records, or approved business data. - Carry open actions into the next review until they are closed or explicitly cancelled. The final section should contain the decisions required from the review group. If no decision or action follows from a section, shorten it. Use [Monitor Usage, Audit Logs, and Risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk) to turn those decisions into the next operating cycle. --- # Security and Governance Enterprise AI security covers more than authentication and content filtering. It also defines which data an agent can retrieve, which tools it can execute, when a person must approve an action, which model and region process a request, and what evidence remains after an incident. Use this section to design those controls before production launch and to review them as the deployment changes. ## Start Here | If you need to | Read | | --- | --- | | Identify AI-specific attack paths | [AI Threat Model](#doc-security-and-governance-ai-threat-model) | | Protect agents from malicious instructions | [Prompt Injection](#doc-security-and-governance-prompt-injection) | | Control external actions | [Tool Governance](#doc-security-and-governance-tool-governance) and [Human Approval](#doc-security-and-governance-human-approval) | | Restrict company knowledge | [Data Access and RAG](#doc-security-and-governance-data-access-and-rag) | | Prepare evidence and response procedures | [Auditability](#doc-security-and-governance-auditability) and [Incident Response](#doc-security-and-governance-incident-response) | | Select approved models and processing locations | [Model Governance](#doc-security-and-governance-model-governance) and [Model Deployment and Data Residency](#doc-security-and-governance-model-deployment-and-data-residency) | | Review an EU deployment | [EU AI Act Readiness](#doc-security-and-governance-eu-ai-act-readiness) | | Approve a production launch | [AI Go-Live Checklist](#doc-security-and-governance-ai-go-live-checklist) | ## Product Controls and Operating Controls Siesta AI provides product controls such as roles, teams, sharing policies, connection governance, function confirmation, Prompt Shield, content safety, token limits, Tool Executions, and Audit Log. Those controls still need an operating model: named owners, data classification, approval rules, incident procedures, review cadence, and evidence retention. For product configuration, also use: - [Organization Security](#doc-organization-security) - [Define Access Policies](#doc-admin-guide-define-access-policies-and-visibility-rules) - [Configure Connections](#doc-admin-guide-configure-shared-and-private-connections) - [Monitor Usage, Audit Logs, and Risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk) --- # AI Threat Model Traditional applications execute predefined code paths. AI agents also interpret natural language, retrieve untrusted content, select tools, and generate actions. The security boundary therefore includes every source that can influence the model and every system the model can affect. ## Attack Surface Review these surfaces for every production agent: | Surface | Typical risk | Primary control | | --- | --- | --- | | User prompt | Instruction override, data extraction, unsafe request | Input policy, Prompt Shield, scoped permissions | | Retrieved document or website | Indirect prompt injection, poisoned knowledge | Treat content as data, source review, output constraints | | System prompt and skills | Excessive authority or unclear boundaries | Controlled editing, version review, least privilege | | Memory and data collections | Unauthorized or stale context | Ownership, classification, access filters, review cadence | | Model output | Hallucination, harmful or biased result | Evaluation, grounding, human review, content safety | | Tool response | Malicious instructions or unexpected data | Validate tool output, isolate it from instructions | | Tool execution | External communication, deletion, spend, privilege change | Function-level policy and human approval | | Model provider | Processing location, retention, availability, model change | Approved model inventory and deployment review | ## Minimum Threat-Modelling Questions For each agent or workflow, document: 1. Who can invoke it and whether anonymous access is possible. 2. Which datasets, memory collections, files, and page context it can read. 3. Which tool functions it can call and which functions modify external state. 4. What a malicious user or malicious document could cause it to disclose or change. 5. Which actions require human approval and who can approve them. 6. Which events are logged and how an investigator can correlate them. 7. Which model deployment processes prompts and where processing may occur. 8. What happens when a provider, credential, index, or approval flow fails. ## Review Trigger Repeat the threat model when access, tools, datasets, prompts, models, public interfaces, or workflow logic changes. A previously low-risk assistant can become high risk as soon as it receives a write-capable connection or sensitive data source. See [Prompt Injection](#doc-security-and-governance-prompt-injection), [Tool Governance](#doc-security-and-governance-tool-governance), and [Layered Security Architecture](#doc-security-and-governance-layered-security-architecture). --- # Prompt Injection Prompt injection attempts to make an AI system ignore its intended instructions, reveal protected information, or take an unauthorized action. It is an AI-native risk and must be handled separately from ordinary input validation. ## Direct and Indirect Attacks **Direct prompt injection** is supplied by the user. Examples include requests to reveal system instructions, disregard policies, or use a tool outside the task. **Indirect prompt injection** is embedded in content the agent reads, such as an email, webpage, document, ticket, tool response, or retrieved knowledge chunk. This is especially important for agents because the malicious content may try to trigger a real external action. ## Defense in Depth No single filter reliably removes the risk. Combine controls: - Treat retrieved content and tool output as untrusted data, not as instructions. - Give each agent only the datasets and functions needed for its purpose. - Separate read, draft, send, update, delete, publish, and spend operations. - Require confirmation for actions with external, financial, legal, permission, or destructive impact. - Keep credentials and secrets outside prompts, memory, uploaded files, and tool results. - Validate high-impact arguments such as recipients, amounts, record IDs, and target environments. - Log the prompt context, selected function, sanitized arguments, approval, and result. - Test with malicious instructions in user prompts, documents, emails, webpages, and tool responses. ## Siesta AI Configuration Enable Prompt Shield from [Organization Security](#doc-organization-security), but do not treat it as an authorization system. Authorization still comes from roles, sharing, data access, connection ownership, function policy, and approval requirements. For a public agent, also remove private sources and unnecessary tools, disable file upload when it is not required, and verify that page-context injection cannot expose authenticated page data. ## Test Cases Before launch, verify that the agent refuses or safely contains attempts to: 1. reveal its system prompt or hidden configuration, 2. follow instructions embedded in a retrieved file, 3. send data to a new recipient supplied by untrusted content, 4. bypass an approval step, 5. access a dataset outside the user's permissions, 6. use a disabled tool function. External reference: [OWASP LLM01: Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/). --- # Tool Governance An agent with tools is an execution identity, not only a chatbot. Treat every exposed function like an API permission and govern functions individually. ## Classify Functions by Effect | Function type | Examples | Recommended default | | --- | --- | --- | | Read | Search documents, list tickets, read calendar availability | Enabled when access is correctly scoped | | Draft | Draft email, prepare report, propose ticket | Enabled or confirmation for sensitive content | | Create | Create ticket, task, event, or internal record | Confirmation unless narrowly bounded and reversible | | Update | Change CRM record, campaign, permission, or workflow | Confirmation | | Send or publish | Send email, post message, publish content | Confirmation | | Delete or destructive | Delete record, revoke access, overwrite production data | Disabled or exceptional approval | | Financial or privileged | Change budget, purchase, deploy, change access | Explicit approval and additional provider controls | ## Least-Privilege Design - Enable only approved connection types at organization level. - Prefer a narrow service account over a shared administrator credential. - Share production connections with the smallest relevant team. - Give the agent only the functions used by its documented workflow. - Keep read and write functions separate so safe retrieval does not imply write access. - Use provider-side scopes and policies as an additional boundary. - Review tool assignments whenever the agent prompt, owner, or purpose changes. ## Organization Overrides Organization-level connection governance can disable a connection type or force a function policy. Use it to prevent individual connection owners from making sensitive functions fully automatic. Examples of organization-wide rules: - sending email always requires confirmation, - deleting external records is disabled, - reading approved analytics data is enabled, - changing advertising spend requires confirmation, - production deployment functions are limited to an operations team. Review actual actions in [Tool Executions](/tool-executions) and configuration changes in [Audit Log](#doc-audit-log). --- # Data Access and RAG Retrieval-augmented generation creates a security boundary around which sources can be searched, whose permissions apply, and what evidence identifies the source of an answer. ## Classify Before Connecting Use a small, enforceable classification model, for example: | Class | Examples | AI access policy | | --- | --- | --- | | Public | Published website and public documentation | May be used by public agents after content review | | Internal | Procedures and general company knowledge | Authenticated users and approved teams | | Confidential | Customer, finance, legal, HR, or commercial data | Named teams, explicit owner, no public agent access | | Restricted | Credentials, highly regulated records, privileged security data | Do not ingest unless the approved use case requires it and controls are documented | ## Required Controls For each data collection: 1. Assign a business owner and a technical owner. 2. Record its classification, purpose, source system, and expected users. 3. Connect only sources required by the agent's purpose. 4. Preserve source identity and useful metadata for traceability. 5. Enforce organization, team, user, and collection access consistently. 6. Separate public knowledge from internal and customer-specific knowledge. 7. Define refresh, deletion, and access-review procedures. 8. Test that an unauthorized user cannot retrieve or infer restricted content. ## Retrieved Content Is Untrusted A document can contain malicious instructions even when the user is allowed to read it. The agent should use retrieved text as evidence, not as a new authority. Pair retrieval permissions with the controls in [Prompt Injection](#doc-security-and-governance-prompt-injection). For product setup and operational checks, see [Govern Data Collections and Sources](#doc-admin-guide-govern-data-collections-and-sources) and [Data Collections](#doc-data-collections). --- # Human Approval Human approval is a control for actions with meaningful impact. It should be based on action sensitivity, not applied indiscriminately to every AI interaction. ## Default Approval Matrix | Action | Default | Reviewer should verify | | --- | --- | --- | | Search or read permitted data | Automatic | Access scope and source | | Create an internal draft | Automatic or confirmation | Sensitive content and intended audience | | Create an internal ticket or task | Confirmation for broad agents | Project, owner, priority, duplicates | | Send or publish externally | Confirmation | Recipient, content, attachments, classification | | Update a business record | Confirmation | Target ID, changed fields, downstream effects | | Export data | Confirmation | Purpose, destination, minimum necessary data | | Change permissions, budgets, production, or legal state | Confirmation plus provider-side authorization | Identity, scope, rollback, owner approval | | Delete or perform an irreversible action | Disabled or exceptional approval | Necessity, backup, exact target, recovery path | ## Effective Approval Requests An approver needs enough context to make a real decision. Show: - the action and target system, - the exact recipient, record, environment, or resource, - the arguments that matter, - a concise reason for the action, - the expected effect and whether it is reversible, - which agent, conversation, workflow, and connection requested it. Do not hide a batch of materially different changes behind one generic confirmation. ## Review and Tuning If approvals become noisy, separate read, draft, and write functions or narrow the workflow. Do not remove confirmation from high-impact actions only to reduce friction. Review approvals and outcomes in [Tool Executions](/tool-executions). --- # AI Auditability An AI audit trail should explain who initiated an interaction, which configuration and data influenced it, which action was proposed or executed, and who approved the action. ## Evidence Model | Event category | Evidence to retain | | --- | --- | | User interaction | User, organization, agent, conversation, timestamp, request and response metadata | | Agent configuration | Agent version or change record, model connection, tools, skills, memory, data collections | | Retrieval | Collection and source identifiers, relevant retrieval metadata, authorization context | | Tool execution | Function, sanitized arguments, result, status, duration, connection, target system | | Approval | Request, approver, decision, timestamp, reason when available | | Administrative change | Actor, entity, changed properties, timestamp, correlation ID | | Provider operations | Deployment, region or data zone, quota, service logs, request correlation where available | Avoid writing credentials, access tokens, complete secret values, or unnecessary sensitive payloads into logs. ## Use the Right Evidence Source - **Tool Executions** explains what an agent attempted through a tool and whether it succeeded. - **Audit Log** explains platform configuration and access changes. - **Conversation and feedback** provide user context and quality evidence. - **Workflow history** provides changes to repeatable automation. - **External provider logs** confirm what occurred in the target system. - **Azure or model-provider monitoring** provides deployment, quota, latency, and provider-side evidence. Use correlation identifiers and timestamps to join these sources during an investigation. Define retention based on legal, security, support, and privacy requirements rather than keeping every payload indefinitely. See [Audit Log](#doc-audit-log), [Tool Executions](/tool-executions), and [Incident Response](#doc-security-and-governance-incident-response). --- # AI Incident Response AI incidents can involve unauthorized tool actions, sensitive-data exposure, malicious retrieved content, unsafe output, unexpected model behavior, or loss of audit evidence. Use a playbook that preserves evidence before configuration is changed. ## First Response 1. Record the time, reporter, affected organization, agent, workflow, and external system. 2. Preserve the conversation, Tool Execution, Audit Log entry, correlation IDs, and provider logs. 3. Stop further impact by disabling the affected function, connection, workflow, public interface, or agent. 4. Revoke or rotate credentials if exposure or credential misuse is possible. 5. Identify affected data, users, recipients, records, and environments. 6. Assign an incident owner and communication owner. ## Investigation Questions - Was the initiating identity authorized? - Did a user prompt, retrieved document, webpage, email, or tool response contain malicious instructions? - Which prompt, skill, memory, dataset, model, and tool configuration were active? - Did a human approve the action, and what context did the approval show? - What did the external provider record as the final action? - Can the change be reversed, and has the same configuration affected other executions? ## Recovery Containment is not the final fix. Correct the narrowest failed control, then retest: - reduce data or tool scope, - change the function policy, - improve argument validation or approval context, - remove or reprocess poisoned content, - update the prompt or skill boundary, - add a regression test, - restore or correct external records, - document the decision and residual risk. After recovery, review similar agents, connections, and workflows for the same condition. Follow applicable contractual, regulatory, privacy, and customer notification procedures. See [Monitor Usage, Audit Logs, and Risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk) for common operational playbooks. --- # Layered Security Architecture Secure AI deployments use multiple independent controls. A content filter cannot replace authorization, and an approval dialog cannot correct an agent that can retrieve the wrong data. ## Control Layers | Layer | Controls | Main question | | --- | --- | --- | | Identity | SSO, roles, teams, lifecycle, conditional access | Who is the user or service? | | Sharing and authorization | Private/shared entities, team access, use/edit permissions | What can the identity see or manage? | | Agent | Prompt, model, memory, skills, tools, interface | What is the agent designed to do? | | Data | Collections, source permissions, classification, retention | Which knowledge can influence the answer? | | Tool | Connections, provider scopes, function policy, validation | Which systems can the agent affect? | | Approval | Risk-based confirmation and approver context | Which actions need a person? | | Model | Approved providers, deployments, regions, evaluations | Where and how is inference performed? | | Safety | Prompt Shield, content safety, quality tests | Which harmful or unreliable behavior is reduced? | | Operations | Logs, monitoring, limits, response, recovery | Can the organization detect and contain failure? | ## Design Principle Enforce the important decision at more than one layer. For example, a production email agent can use a team-scoped service account, expose only read and draft functions by default, require confirmation for send, and log the final provider result. If one control is misconfigured, another still limits impact. ## Review Order When troubleshooting unexpected access or action, review the layers in this order: 1. identity and team membership, 2. entity sharing and permissions, 3. agent data and tool assignments, 4. connection and function policy, 5. approval and execution history, 6. external provider permissions and logs. For infrastructure layers, continue with [Reference Architecture](#doc-deployment-and-operations-reference-architecture) and [Network Security](#doc-deployment-and-operations-network-security). --- # AI Safety and Quality A system can be secure and still produce inaccurate, biased, opaque, or unsuitable results. AI safety combines technical protection with quality evaluation and human oversight. ## Safety Areas | Area | Practical control | | --- | --- | | Transparency | Tell users when they interact with AI and when content is AI-generated where required | | Accuracy | Ground important answers in approved sources and show source context where possible | | Reliability | Test representative, boundary, adversarial, and failure cases before launch | | Human oversight | Require review for high-impact outputs and decisions | | Fairness | Review use cases involving employment, access, scoring, or people-related decisions | | Content safety | Configure categories and thresholds for the intended audience | | Privacy | Minimize personal data in prompts, context, logs, and evaluation datasets | | Continuous improvement | Use feedback, analytics, incident findings, and controlled configuration changes | ## Evaluation Set Create a versioned test set for every production agent. Include: - expected everyday questions, - questions that should be refused or escalated, - ambiguous and incomplete requests, - stale or conflicting sources, - attempts to retrieve inaccessible data, - direct and indirect prompt injection, - tool failures and approval rejection, - harmful-content boundaries relevant to the audience. Record the agent configuration, model deployment, date, expected behavior, actual result, reviewer, and release decision. Re-run the set after changing prompts, models, tools, data, memory, safety settings, or public exposure. Product filters are configured in [Organization Security](#doc-organization-security). They complement, but do not replace, use-case evaluation. --- # Model Governance Do not select the most capable model by default. Maintain an approved portfolio that matches models and deployments to use-case sensitivity, quality, cost, latency, throughput, availability, and processing-location requirements. ## Model Register For each approved model connection, record: | Field | Why it matters | | --- | --- | | Provider and model family | Contract, capability, support, and risk ownership | | Deployment name and type | Runtime configuration and processing boundary | | Region or data zone | Residency and operational review | | Approved use cases | Prevents accidental use in unsuitable scenarios | | Preview or production status | Preview terms and behavior may differ | | Input/output modalities | Defines data types the model can receive and produce | | Evaluation result | Shows quality and safety evidence for the intended use | | Quota, limits, and cost owner | Supports capacity and budget control | | Retirement or review date | Prevents unmanaged model drift and end-of-life risk | ## Portfolio Pattern Use high-capability reasoning models for complex planning and analysis, smaller efficient models for high-volume extraction or classification, embedding models for retrieval, and specialized audio or image models only where required. Separate highly regulated or deterministic workloads from general assistants. If a model router is used, approve the routing mode and allowed model subset. The router does not remove the need to review every possible underlying model and the deployment's processing location. ## Change Control Re-evaluate a production agent when the provider changes a model version, a preview becomes generally available, a model is retired, routing membership changes, or deployment type changes. Preserve the previous evaluation result and rollback decision. See [Azure AI Foundry](/connections/azure-ai-foundry) and [Model Deployment and Data Residency](#doc-security-and-governance-model-deployment-and-data-residency). --- # Model Deployment and Data Residency The Azure model deployment type determines where inference may be processed and also affects capacity, latency, availability, and cost. The location of the Azure resource alone does not answer the inference-processing question. ## Processing Boundaries | Deployment family | Inference processing | Typical consideration | | --- | --- | --- | | Global | May use Azure's global infrastructure | Broad model availability and quota; not suitable when processing must stay in one zone or region | | Data Zone | Stays within the Microsoft-defined data zone, such as the EU | Zone boundary with broader routing than a single region | | Regional or geography-based | Uses the selected regional/geographic boundary where supported | Stricter location requirement; availability and quota may be narrower | | Provisioned variants | Reserved capacity within the selected processing scope | Predictable throughput and lower latency variance | Not every model supports every deployment type or region. Verify availability during design and again before production rollout. ## Review Checklist - Record the exact deployment type, not only the resource region. - Separate data stored at rest from prompts and responses processed for inference. - Review stateful features, batch processing, fine-tuning, stored completions, and preview features separately. - Confirm the model router's complete allowed model subset. - Document provider abuse-monitoring and content-safety behavior that applies to the subscription. - Recheck the design when changing model, deployment type, region, or provider feature. For EU requirements, use an EU Data Zone or regional deployment only where the required model supports it, and validate the current Microsoft documentation and customer policy. Global deployments may process prompts and responses outside the EU even when the Azure resource itself is located in Europe. Official references: - [Microsoft Foundry deployment types](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/deployment-types) - [Data, privacy, and security for Foundry Models](https://learn.microsoft.com/en-us/azure/foundry/responsible-ai/openai/data-privacy) --- # EU AI Act Readiness The EU AI Act uses a risk-based framework and assigns different responsibilities to providers, deployers, importers, distributors, and other actors. Classification depends on the actual use case and role, not on the product name or model alone. :::caution Legal review This page is an operational starting point, not legal advice. The implementation timeline and supporting rules continue to evolve. Confirm the current position with legal counsel and the official EU sources before relying on a classification or deadline. ::: ## Use-Case Review For every production use case, record: 1. Intended purpose, users, affected people, and business process. 2. Whether Siesta AI, the customer, or another party is acting as provider or deployer for the use case. 3. Whether the use falls into a prohibited, high-risk, transparency, or minimal-risk area. 4. Which model, data, tools, decisions, and human oversight are involved. 5. Which records demonstrate risk management, testing, logging, instructions, and monitoring. 6. Who owns ongoing review and serious-incident escalation. ## Operational Evidence High-impact use cases commonly need stronger evidence around: - risk assessment and mitigation, - data quality and governance, - technical and user documentation, - logging and traceability, - human oversight, - accuracy, robustness, and cybersecurity, - post-deployment monitoring and incident handling. Transparency duties may also require users to know they are interacting with AI or that content was generated or manipulated by AI. Implement disclosure in the actual interface and workflow, not only in a policy document. ## Official Sources - [European Commission AI Act overview](https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai) - [Regulation (EU) 2024/1689 on EUR-Lex](https://eur-lex.europa.eu/eli/reg/2024/1689/oj) - [European Commission AI Act Service Desk](https://ai-act-service-desk.ec.europa.eu/) --- # AI Go-Live Checklist Use this checklist before moving an agent or workflow into production. Record an owner and evidence link for every applicable item. ## Governance - [ ] Business owner, technical owner, and support owner are assigned. - [ ] Purpose, users, prohibited uses, and success criteria are documented. - [ ] The use case has an approved risk classification. - [ ] Legal, privacy, security, and employee or customer review is complete where required. ## Data and Access - [ ] Data sources have owners and classifications. - [ ] Public, internal, confidential, and restricted sources are separated. - [ ] Roles, teams, sharing, and collection access were tested with non-admin users. - [ ] Retention, deletion, refresh, and offboarding procedures are defined. ## Models, Agents, and Tools - [ ] Provider, model, deployment type, processing location, and preview status are documented. - [ ] Prompt, skills, memory, tools, and interfaces are reviewed and versioned. - [ ] Each tool function has an explicit automatic, confirmation, or disabled policy. - [ ] Provider credentials follow least privilege and have a rotation owner. - [ ] Public agents have no unnecessary private data, file upload, or write-capable tools. ## Testing and Operations - [ ] Quality, safety, authorization, prompt-injection, tool, and failure tests passed. - [ ] Approval requests show the exact action and target. - [ ] Tool Executions, Audit Log, provider logs, and correlation are available. - [ ] Token, cost, quota, and rate limits are configured. - [ ] Incident containment, credential rotation, rollback, and escalation were rehearsed. - [ ] User training, support route, review cadence, and release owner are defined. The checklist is evidence of review, not proof that a system is risk-free. Reapprove the use case after a material change to audience, data, tools, model, autonomy, or business impact. --- # Deployment and Operations This section describes the customer-safe deployment and operating model for Siesta AI. It covers architecture, identity, networking, secrets, monitoring, infrastructure as code, rollout, and handover without exposing production resource names, credentials, private addresses, or customer-specific topology. ## Choose a Path | Goal | Read | | --- | --- | | Select SaaS or a customer-controlled environment | [Deployment Models](#doc-deployment-and-operations-deployment-models) | | Prepare and validate a customer-controlled Azure environment | [Azure Deployment Guide](#doc-deployment-and-operations-azure-deployment) | | Understand the platform service boundaries | [Reference Architecture](#doc-deployment-and-operations-reference-architecture) and [Runtime Services](#doc-deployment-and-operations-runtime-services) | | Review network and service authentication | [Network Security](#doc-deployment-and-operations-network-security) and [Identity and Access](#doc-deployment-and-operations-identity-and-access) | | Prepare configuration and credentials | [Secrets and Configuration](#doc-deployment-and-operations-secrets-and-configuration) | | Plan logs, alerts, and external access | [Observability](#doc-deployment-and-operations-observability) and [Firewall and Egress](#doc-deployment-and-operations-firewall-and-egress) | | Review repeatable provisioning | [Infrastructure as Code](#doc-deployment-and-operations-infrastructure-as-code) | | Run a customer implementation | [Deployment Lifecycle](#doc-deployment-and-operations-deployment-lifecycle) and [Rollout and Handover](#doc-deployment-and-operations-rollout-and-handover) | | Review third-party components | [Open-Source Licenses](#doc-deployment-and-operations-open-source-licenses) | ## Documentation Boundaries Public documentation explains architecture and required controls. Customer handover documentation may additionally contain approved resource inventories, endpoints, owners, operational thresholds, and environment-specific runbooks. Exact network ranges, secret names, firewall destinations, internal identifiers, and recovery targets belong in access-controlled customer or engineering documentation. --- # Deployment Models Siesta AI can be operated as a managed SaaS service or deployed into a customer-controlled Azure environment. The functional platform can remain consistent while ownership of infrastructure, identity, networking, monitoring, and change approval differs. ## Responsibility Comparison | Area | Managed SaaS | Customer-controlled Azure | | --- | --- | --- | | Azure subscription and resource lifecycle | Managed by Siesta AI | Customer-owned with agreed delivery responsibilities | | Platform updates | Managed release process | Coordinated release and maintenance process | | Network integration | Standard managed boundary | Customer VNet, DNS, firewall, and ingress integration | | Identity | Customer SSO connected to managed service | Customer SSO plus Azure workload identities and RBAC | | Secrets | Managed secure stores | Customer-approved Key Vault or secret store with named owners | | Monitoring | Managed service monitoring | Shared or customer-owned monitoring and escalation | | Backup and recovery | Managed service policy | Customer-specific RTO, RPO, retention, and recovery tests | | Cost management | Included in service model | Azure budgets, sizing, quota, and cost ownership agreed with customer | ## Selection Questions Choose the deployment model after answering: - Must runtime or data resources reside in the customer's Azure tenant? - Are private endpoints, custom DNS, fixed egress, or customer SIEM integration required? - Who can approve production changes and emergency access? - Which team owns provider quota, model deployments, backups, and incident escalation? - What availability, RTO, RPO, maintenance window, and evidence requirements apply? - Which contractual or regulatory controls require customer ownership? Document the final responsibility matrix before provisioning begins. Avoid assumptions such as "customer-hosted means customer-operated" unless the operating agreement assigns that work explicitly. --- # Azure Deployment Guide This guide prepares a customer-controlled Azure environment for Siesta AI. The platform remains a managed product with coordinated releases and support, while the customer owns the Azure subscription, policy boundary, networking decisions, and agreed operational responsibilities. Use this guide with the [Deployment Models](#doc-deployment-and-operations-deployment-models), [Reference Architecture](#doc-deployment-and-operations-reference-architecture), and the customer-specific implementation package supplied for the engagement. Do not copy example identifiers into production. ## Deployment Outcome A completed deployment has: - an approved Azure tenant, subscription, region, and billing owner, - named customer and Siesta AI deployment contacts, - an isolated resource and policy boundary, - approved identity, network, DNS, egress, and private-connectivity decisions, - secrets stored in an approved secret store, - infrastructure provisioned from reviewed Infrastructure as Code, - working sign-in, application, retrieval, tool, model, and monitoring paths, - documented acceptance evidence, support access, upgrade process, and handover owners. ## 1. Confirm the Operating Model Before provisioning, agree who owns each activity. | Area | Customer responsibility | Siesta AI responsibility | | --- | --- | --- | | Azure boundary | Tenant, subscription, billing, policy, region approval | Required capabilities and deployment guidance | | Infrastructure | Approve and provide the target boundary | Supply and operate the approved IaC and application release process | | Identity | Entra ID, groups, SSO approval, privileged-access policy | Application roles and workload-identity requirements | | Networking | VNet integration, DNS, firewall, private endpoints, egress approval | Document required service flows and validate application connectivity | | Secrets | Approve store, access policy, rotation owners | Use the agreed secret references and avoid secrets in source control | | Monitoring | SIEM integration, customer alerts, escalation contacts | Product health signals, deployment diagnostics, and support runbooks | | Updates | Change windows and customer approval gates | Versioned releases, deployment instructions, validation, and rollback guidance | Customer-controlled does not automatically mean customer-operated. Record the actual deployment, monitoring, support, backup, and incident responsibilities in the implementation agreement. ## 2. Prepare the Azure Boundary A dedicated Azure subscription is the recommended default for production. It gives the clearest cost, policy, access, and lifecycle boundary. If the customer uses a shared subscription, use dedicated resource groups and confirm that inherited policy cannot block required services or grant unintended access. Prepare: 1. Azure tenant and subscription IDs. 2. Subscription display name and billing owner. 3. Primary region and approved paired or recovery region, if required. 4. Mandatory resource tags such as owner, environment, cost center, data classification, and service. 5. Azure Policy assignments and exemptions that affect the deployment. 6. Resource-provider registration and quotas for compute, networking, storage, search, databases, AI/model services, monitoring, and secrets. 7. Naming rules that do not expose customer-sensitive data. Do not start until region availability and model quota have been validated. Resource location and model deployment type are separate data-residency decisions; see [Model Deployment and Data Residency](#doc-security-and-governance-model-deployment-and-data-residency). ## 3. Establish Identity and Access Use Microsoft Entra ID groups instead of assigning production access to individual users wherever possible. Define: - a customer deployment approver group, - a least-privileged deployment identity for the approved IaC pipeline, - workload identities or managed identities for runtime services, - read-only operations and security-review groups, - time-bound privileged or break-glass access with auditable approval, - support access, its expiry, and the procedure for enabling and removing it. Avoid long-lived owner credentials and secrets in local configuration. Separate deployment authority from routine monitoring. See [Identity and Access](#doc-deployment-and-operations-identity-and-access). ## 4. Approve Networking and DNS Decide whether ingress and managed-service traffic use public endpoints with restrictions, private endpoints, or a hybrid pattern. Document every required flow before applying deny-by-default controls. Review: - VNet and subnet ownership, address space, delegation, and peering, - private DNS zones and resolution from customer networks, - ingress, TLS certificates, WAF or reverse-proxy ownership, - fixed or controlled egress and required external destinations, - private endpoints for data, search, secret, registry, database, and model services where supported, - connectivity to customer systems and identity providers, - diagnostic routing to Azure Monitor, Log Analytics, or the customer SIEM. Do not infer that successful resource deployment proves runtime connectivity. Test DNS, TLS, identity, and application calls separately. See [Network Security](#doc-deployment-and-operations-network-security) and [Firewall and Egress](#doc-deployment-and-operations-firewall-and-egress). ## 5. Prepare Secrets and Configuration Use the customer-approved Azure Key Vault or equivalent secret store. The deployment package should receive secret references, not secret values committed to a repository or pasted into tickets. Before deployment, identify owners and rotation procedures for application credentials, model/provider credentials, storage access, external integrations, signing keys, and certificates. Confirm that runtime identities can read only the secrets they need and that deployment identities cannot silently broaden runtime access. ## 6. Review and Run Infrastructure as Code Siesta AI supplies the customer-specific, versioned Bicep or Terraform package agreed for the engagement. Treat that package as the deployment contract. 1. Verify the package version, checksum or release reference, and target environment. 2. Review parameter files without adding secrets. 3. Run the platform-native validation and preview operation, such as Bicep validation/what-if or a Terraform plan. 4. Review resource types, regions, role assignments, network changes, policy exceptions, and destructive operations. 5. Obtain the required customer approval. 6. Execute through the approved deployment identity and pipeline. 7. Store the deployment output and approval evidence in the controlled implementation record. Do not manually rename, replace, or modify managed resources after deployment. Feed required changes back into the IaC package so the next release remains repeatable. See [Infrastructure as Code](#doc-deployment-and-operations-infrastructure-as-code). ## 7. Configure the Platform After infrastructure provisioning: 1. Configure application URLs, identity settings, and approved redirect URIs. 2. Connect model deployments and verify their region, deployment type, quota, and content-safety settings. 3. Configure storage, search, databases, queues, and background processing through managed identity or approved secret references. 4. Enable monitoring, audit, backup, and retention settings. 5. Create the initial Siesta AI Owner/Admin identities through the approved process. 6. Add only the pilot Connections, Data sources, agents, and workflows required for acceptance. ## 8. Validate the Deployment Acceptance must cover behavior, not only successful provisioning. | Test | Expected evidence | | --- | --- | | Identity | Approved users can sign in; unauthorized users cannot | | Application health | Frontend, API, background processing, and scheduled work are healthy | | Retrieval | A controlled document can be ingested, indexed, retrieved, and cited | | Models | Approved model deployment responds and usage appears in monitoring | | Tools | A read action succeeds and a protected write action requires approval | | Networking | Required private/public paths work; unapproved paths remain blocked | | Secrets | Runtime reads required secrets without exposing them in logs or configuration output | | Observability | Logs, metrics, alerts, audit records, and escalation routing are visible | | Recovery | Backup/restore or the agreed recovery check is recorded | Record failures, owners, and retest evidence. Do not attach production users or data until critical acceptance items are closed. ## 9. Handover and Ongoing Operations The handover package should contain the approved architecture, resource inventory, owners, support contacts, monitoring links, alert thresholds, backup and recovery targets, credential-rotation schedule, deployment version, change process, and rollback procedure. Keep customer-specific endpoints and identifiers in the access-controlled handover record, not public documentation. Upgrades follow the same controlled path: versioned release, reviewed IaC preview, approved change window, deployment, smoke tests, and rollback decision. Emergency access must be time-bound and reviewed after use. --- # Reference Architecture The Siesta AI reference architecture separates user-facing application services, API and workflow services, retrieval services, tool integrations, managed data services, AI services, security stores, and operations telemetry. ![Sanitized Azure reference architecture showing edge protection, application services, private networking, data, AI, identity, secrets, messaging, storage, and monitoring](/img/guides/azure-reference-architecture.svg) The diagram is intentionally logical. It does not expose customer resource names, private addresses, quantities, sizing, or environment-specific topology. ## Logical Flow ```text Users and clients | Ingress, TLS, WAF, and identity | Frontend and API services |--------------------------| Agent and workflow runtime Tool and connector services | | Retrieval API and workers Approved external systems | Search, storage, and databases | Approved model deployments Cross-cutting: Key Vault, managed identity, private networking, monitoring, audit evidence, backup, and policy controls ``` ## Service Boundaries - **Frontend** presents authenticated and approved public interfaces. - **Platform API** handles platform logic, agent configuration, workflows, and authorization. - **Retrieval services** ingest, chunk, index, and retrieve approved knowledge. - **Tool services** isolate integrations and external function execution. - **Background and function workloads** handle asynchronous processing and scheduled work. - **Managed data services** store application records, files, indexes, and job state. - **Model deployments** provide chat, reasoning, embedding, audio, or other approved inference. - **Operations services** collect logs, metrics, traces, health, and security signals. Customer deployments can change naming, region, sizing, network integration, and service ownership while preserving these logical boundaries. For control layers, see [Layered Security Architecture](#doc-security-and-governance-layered-security-architecture). --- # Runtime Services Siesta AI uses independently deployable services so that public ingress, platform APIs, retrieval workloads, external tools, and background processing can be secured and scaled separately. ## Workload Groups | Workload | Purpose | Operational focus | | --- | --- | --- | | Frontend | User and embedded interfaces | TLS, origin policy, health, user-facing availability | | Platform API | Authentication, entities, agents, workflows, business logic | Authorization, database health, latency, audit correlation | | Retrieval API | Query-time retrieval and search operations | Private access, search latency, model and index dependencies | | Retrieval worker | Ingestion, extraction, chunking, embeddings, indexing | Queue depth, retries, poison items, throughput, quota | | Tool service | Governed calls to external systems | Credential scope, approval, provider failures, egress | | Function and scheduled workloads | Event-driven and background processing | Identity, idempotency, retries, timeout, dead-letter handling | ## Production Requirements Every workload should have: - a dedicated runtime identity where practical, - explicit inbound and outbound network paths, - minimum and maximum scale appropriate to the workload, - startup and health probes, - bounded retries and timeouts, - structured logs, metrics, traces, and correlation IDs, - documented dependencies and failure behavior, - a rollback or recovery path. Avoid embedding secrets directly into runtime environment values. Reference a secret store or fetch secrets through the workload identity. Separate static configuration from secret-classified values as described in [Secrets and Configuration](#doc-deployment-and-operations-secrets-and-configuration). --- # Network Security Customer-controlled deployments should use private connectivity for data, search, secret, registry, and other managed services wherever the target Azure services and customer architecture support it. ## Reference Pattern - Route public application traffic through an approved ingress layer with TLS and web-application protection. - Keep application and function workloads in delegated subnets appropriate to their Azure service. - Place private endpoints in a dedicated subnet where the customer standard requires it. - Use private DNS zones and documented DNS links for private endpoint resolution. - Disable public network access for sensitive managed services after private connectivity is verified. - Apply deny-by-default network rules with explicit, reviewed service and destination allowances. - Separate ingress, application, private endpoint, and management paths. - Monitor denied traffic and failed DNS resolution during rollout. ## Validation Before go-live, test from every required runtime and administrative path: 1. ingress reaches only the intended frontend or API endpoint, 2. private names resolve to private addresses, 3. workloads can reach required managed services, 4. unauthorized public paths are blocked, 5. required provider and integration egress succeeds, 6. blocked egress produces useful operational evidence, 7. deployment and emergency-access paths still work as designed. Do not publish actual subnet ranges, internal hostnames, private endpoint identifiers, or customer firewall rules in public documentation. Maintain those values in the controlled deployment record. --- # Identity and Access Separate human identity, application identity, and external-connection identity. Each has a different lifecycle and should be reviewed independently. ## Human Identity - Use the customer's approved SSO provider and tenant. - Map roles and teams to job responsibilities, not individual exceptions. - Restrict owner and administrator roles. - Define onboarding, role-change, and offboarding procedures. - Use Admin Mode only for intentional support, governance, or investigation. - Record who can approve security, access, production, and emergency changes. ## Workload Identity Use managed identities for service-to-service access where supported. Assign separate identities to workload groups so one compromised service does not inherit unrelated permissions. Grant the smallest required Azure roles at the narrowest practical scope. Prefer identity-based access to storage, registries, databases, monitoring, and secret stores over static access keys. ## External Connection Identity Connections to email, CRM, collaboration, advertising, or other business systems should use: - a dedicated service account where shared production access is required, - the minimum provider scopes, - team-scoped sharing, - function-level confirmation for write actions, - a named credential owner and rotation procedure, - provider-side logs and revocation capability. Review application registrations, managed identities, service accounts, role assignments, dormant users, and privileged groups at an agreed cadence and after every ownership change. See [Create Teams and Assign Users](#doc-admin-guide-create-teams-and-assign-users) and [Define Access Policies](#doc-admin-guide-define-access-policies-and-visibility-rules). --- # Secrets and Configuration Separate secret-classified values from ordinary environment configuration and assign an owner to both. Documentation should describe purpose and ownership without containing real secret values. ## Classification | Type | Examples | Handling | | --- | --- | --- | | Secret | API key, OAuth client secret, signing key, password | Approved secret store, restricted access, rotation | | Connection string | Database or provider connection containing credentials | Treat as a secret even when generated by infrastructure | | Sensitive identifier | Tenant, subscription, internal endpoint, account identifier | Controlled documentation and environment-specific validation | | Configuration | Feature flag, model deployment name, sender address, timeout | Versioned configuration with review and validation | ## Mandatory Controls - Never place real secrets in documentation, tickets, chat, email, screenshots, source control, or deployment reports. - Store production secrets in Azure Key Vault or the customer-approved secret manager. - Prefer managed identity over credentials where supported. - Separate environments and prevent test credentials from reaching production. - Give every credential an owner, purpose, allowed consumers, creation date, and rotation or expiry rule. - Rotate credentials after suspected exposure, owner departure, provider policy change, or agreed maximum age. - Validate customer-specific endpoints, tenants, senders, and model deployments before go-live. - Log secret access events without logging secret values. ## Handover Inventory The customer-safe inventory should list the configuration category, purpose, owning service, source of value, sensitivity class, owner, rotation method, and validation status. It should not expose repository paths, local build paths, raw deployment output, or the secret-store value itself. Include credential rotation and emergency revocation in [Incident Response](#doc-security-and-governance-incident-response). --- # Observability Production monitoring should show user-facing health, service dependencies, AI and retrieval behavior, tool execution, background processing, security events, and cost or quota pressure. ## Signals | Signal | Examples | | --- | --- | | Availability | Ingress and API health, synthetic checks, successful authentication | | Performance | Request latency, model latency, retrieval latency, tool duration | | Reliability | Error rate, timeouts, retries, queue depth, failed ingestion, dead letters | | Capacity | CPU, memory, replicas, database load, search and model quota | | AI operations | Tokens, model deployment, safety blocks, evaluation failures | | Security | Failed access, policy changes, unusual tool use, secret-store access | | Business operations | Tool success, approval backlog, workflow completion, active users | ## Correlation Propagate a correlation identifier through ingress, API, workflow, retrieval, tool execution, and external provider calls where possible. Keep timestamps synchronized and record the environment, service, deployment version, agent, conversation, workflow, and tool execution identifiers needed for investigation. ## Alert Design Every alert needs an owner, severity, actionable threshold, notification route, runbook, and escalation path. Start with failures that affect users or data, then add capacity and anomaly alerts. Avoid alerts that cannot lead to a clear action. Define dashboards and alerts for: - availability and elevated error rate, - database, storage, search, and secret-store failures, - ingestion backlog and repeated processing errors, - model throttling and quota exhaustion, - failed or unusually long tool executions, - approval queues that stop business workflows, - unexpected token or cost growth, - backup and recovery-job failures. Pair infrastructure telemetry with [AI Auditability](#doc-security-and-governance-auditability). --- # Firewall and Egress Restrictive outbound networking requires an explicit inventory of destinations the platform, deployment pipeline, model provider, identity provider, and enabled integrations must reach. ## Build the Allowlist by Category Maintain customer-specific destinations for: - Azure identity and token endpoints, - container and package registries used by the approved build process, - Azure control-plane and service endpoints required by the architecture, - model inference, embeddings, safety, and document-processing services, - customer-approved collaboration and business integrations, - email, webhook, and notification destinations, - monitoring, status, certificate, and time dependencies, - software update and vulnerability metadata sources where required. Do not enable every potential integration destination. Add optional destinations only when the corresponding product capability is approved and enabled. ## Inventory Fields For each rule, record destination or service tag, protocol and port, source workload, purpose, owner, priority, environment, approval date, and validation evidence. Prefer Azure service tags or private endpoints where they meet the design; use exact host rules when required by customer policy. ## Change Procedure 1. A feature owner requests the destination and explains the data flow. 2. Security reviews classification, processing location, authentication, and necessity. 3. Operations applies the narrowest rule in a non-production environment. 4. The team tests success and verifies that unrelated traffic remains blocked. 5. The rule, evidence, owner, and removal condition are recorded. 6. Unused rules are removed during periodic review. The complete production allowlist is customer-controlled information and should not be published in public documentation. --- # Infrastructure as Code Customer-controlled Azure environments should be provisioned through reviewed, versioned infrastructure as code. A modular design makes security policy, naming, diagnostics, private networking, and environment differences repeatable. ## Module Domains A reference implementation commonly separates: - identity and role assignments, - virtual network, subnets, DNS, and network security, - monitoring and diagnostics, - container registry and application runtime, - storage, databases, and search, - Key Vault and keys, - model and document-processing services, - function and background workloads, - private endpoints, - alerting, backup, and production protection. ## Dependency Order Deploy foundation resources first, then managed data and platform services, compute workloads, private connectivity, and finally secret references and environment-specific configuration. Use module outputs rather than copying resource identifiers between files. ## Safe Pipeline - Pin and review infrastructure module changes. - Validate syntax, policy, and a preview or what-if result before apply. - Separate plan and production approval. - Use workload identity or a narrowly scoped pipeline identity. - Keep secret values out of templates and pipeline logs. - Detect configuration drift. - Retain deployment evidence and the exact commit or artifact version. - Require an explicit rollback, forward-fix, or recovery plan for risky changes. - Apply production deletion protection where supported and operationally appropriate. ## Parameters Parameterize environment, region, customer code, SKU, capacity, redundancy, network integration, identity groups, domains, and feature-specific resources. Do not use production defaults that silently deploy an insecure or oversized environment. Detailed module names, resource identifiers, network ranges, and production parameter files belong in the controlled engineering repository, not public documentation. --- # Deployment Lifecycle Use a staged lifecycle so architecture, identity, infrastructure, application release, security review, and operational ownership are validated separately. ## Phases | Phase | Required outcome | | --- | --- | | 1. Scope and specifications | Approved use cases, deployment model, responsibility matrix, regions, sizing assumptions, security and recovery requirements | | 2. Access and identity | Customer tenant access, groups, app registrations, workload identities, pipeline identity, approvers | | 3. Infrastructure | Reviewed infrastructure-as-code deployment, networking, data services, secrets stores, monitoring foundations | | 4. Delivery pipeline | Build, scan, artifact, approval, deployment, rollback, and environment promotion are tested | | 5. Application deployment | Versioned services, configuration references, domains, health checks, database changes, background workloads | | 6. Security and operations review | Public access, private endpoints, RBAC, secret handling, logs, alerts, backups, recovery, cost and quota reviewed | | 7. Documentation and handover | Inventory, owners, runbooks, support, known risks, training, acceptance evidence | ## Production Acceptance Do not mark a phase complete only because Azure resources exist. Acceptance should include a functional test, security evidence, named owner, known issues, and the next recovery or operational action. At minimum, test authentication, authorization, ingestion, retrieval, model inference, one approved tool flow, approval, audit correlation, monitoring, backup evidence, and rollback or recovery. Record exceptions with an owner and due date. Use [AI Go-Live Checklist](#doc-security-and-governance-ai-go-live-checklist) for the agent and governance layer. --- # Rollout and Handover A technical deployment is not complete until administrators and users can operate it, support routes are known, and ownership is accepted. ## Rollout Workstreams | Workstream | Handover evidence | | --- | --- | | Identity and access | Identity provider, provisioning method, groups, roles, owners, access test | | Data and integrations | Approved sources, connections, owners, sync behavior, failure handling | | Agents and workflows | Purpose, audience, data, tools, model, tests, release owner | | Administration | Organization settings, security policies, limits, audit and support procedures | | Training | Admin and user sessions, materials, attendance, follow-up owner | | Operations | Inventory, dashboards, alerts, backups, runbooks, maintenance and incident contacts | | Support | Support channel, severity model, response expectations, status and escalation links | ## Phased Adoption Start with administrators and a small pilot team. Validate access, answer quality, tool approvals, data synchronization, usage, support volume, and unexpected behavior. Expand only after pilot findings have owners and the production configuration is stable. ## Handover Package Provide an access-controlled package containing: - deployment and responsibility summary, - customer-safe resource and service inventory, - identity, network, secret, and integration ownership, - agent, workflow, model, and data inventory, - monitoring, backup, recovery, incident, and maintenance runbooks, - open risks, accepted exceptions, and planned improvements, - training record and support routes, - acceptance decision and date. Do not copy customer names, contacts, prices, credentials, or production identifiers into public documentation. Use placeholders in reusable templates and store completed reports in the approved customer workspace. --- # Open-Source Licenses Maintain a repeatable inventory of third-party packages used by the application, platform API, tool services, retrieval services, build tooling, and deployed images. ## Inventory Fields For each component, capture: - product area and deployable artifact, - package manager, - package name and resolved version, - direct or transitive scope, - detected license and source of license metadata, - copyright or notice requirement, - review status and owner, - vulnerability or end-of-life evidence where tracked separately. ## Review Workflow 1. Generate inventories from lock files and resolved build outputs, not only manifest files. 2. Normalize license identifiers where possible. 3. Investigate unknown, missing, custom, copyleft, source-available, or conflicting metadata. 4. Review direct dependencies and packages included in distributed artifacts with legal or procurement owners. 5. Produce required notices and attribution. 6. Record approved exceptions and replacement plans. 7. Regenerate the inventory for releases and compare it with the previously approved baseline. Package count alone does not establish compliance. The distribution model, linking, modification, hosted-service use, model or dataset terms, and customer contract can affect the review. ## Customer-Safe Output A customer-facing inventory may include product area, package, version, license, and scope. Exclude local paths, private repository names, raw engineering logs, credentials, and unrelated build metadata. Treat unknown license metadata as an item to resolve, not as an acceptable license category. Obtain legal review when obligations or compatibility are unclear. --- # User Guide import NavCardGrid from '@site/src/components/NavCardGrid'; import {MessageSquare, Bot, ListChecks, Database, Workflow, History, Target, PenLine, RefreshCw, Layers} from 'lucide-react'; # User Guide Use Siesta AI to finish real work: ask an agent, attach files, create tasks, run workflows, review tool actions, and keep useful context available for the next conversation. Read the [Product Introduction](#doc-intro) for the platform model, then use this guide to choose the practical surface for the work. ## Learn to Work With AI ## Start With The Smallest Surface ## A Practical Order Of Work 1. **Pick the right place.** Open Chat for a single request, choose an agent for role-specific work, create a task for follow-up, use sources for trusted knowledge, or run a workflow for repeatable operations. 2. **Make the request inspectable.** Give the source, expected output, constraints, and whether the agent may use tools. Ask for a preview before any external write action. 3. **Check the trace.** If a tool was used, inspect the conversation and Tool Executions. Look at the action, approval state, arguments, result, and failure message before retrying. ## Use This Guide When - You need a good first prompt for Chat or an Agent. - You are not sure whether to use sources, saved context, tasks, or workflows. - A connection expired, a tool is missing, or an external action failed. - You need to explain to an admin exactly what went wrong. ## Good First Requests ```text Use the Support FAQ data collection and draft a customer reply. Keep it under 120 words and do not send it. ``` ```text Create a task from this conversation for the Operations agent. Set the status to In review and include acceptance criteria. ``` ```text Review the failed tool execution and tell me which connection, permission, or input needs attention. ``` ## Feature Map | Need | Practical guide | Product Specification | Check | | --- | --- | --- | --- | | Draft, summarize, compare, analyze | [Ask in Chat Effectively](#doc-user-guide-use-chat-effectively) | [Chat](#doc-chat) | Did you provide source, format, and audience? | | Role-specific answer or action | [Choose and Use Agents](#doc-user-guide-work-with-agents) | [Agents](#doc-agents-overview) | Does the agent have the right data, tools, and access? | | Follow-up work | [Use Tasks to Track Work](#doc-user-guide-use-tasks-to-track-work) | [Tasks](#doc-tasks) | Is the status clear: Todo, In progress, In review, or Done? | | Company files and synced sources | [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) | [Data](#doc-data-collections) | Is the source processed and attached to the right agent? | | Durable internal knowledge | [Save Reusable Context](#doc-user-guide-manage-memory-and-context) | [Memory](#doc-memory) | Is the knowledge maintained and scoped to the right team? | | Repeatable process | [Repeat Work With Workflows](#doc-user-guide-create-useful-workflows) | [Workflows](#doc-workflow) | Are inputs, approvals, and failure checks clear? | | External system action | [Use Connections Safely](#doc-user-guide-use-connections-safely) | [Tools](#doc-tools) | Did the action succeed, fail, or wait for approval? | ## Detailed Operating Guides - [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) - [Use Connections Safely](#doc-user-guide-use-connections-safely) - [Choose and Use Agents](#doc-user-guide-work-with-agents) --- # Get Started with Siesta AI The [Product Introduction](#doc-intro) explains how Siesta AI fits together. After [signing in](/login), choose the work surface you need: [Chat](#doc-chat), [Agents](#doc-agents-overview), [Tasks](#doc-tasks), Data, Workflows, Library, Tool Executions, Conversations, Recordings, or Memory. Start with the surface that already matches the job instead of trying to configure everything first.

First rule If you only need one answer, use Chat. If the work should follow a defined role or use approved tools, choose an Agent. If someone needs to review or continue the work, create a Task.

## First Checks - Confirm you are in the right organization or team. - Open **Profile** if your personal details, locale, or account context look wrong. - Open **Connections** if the agent needs Gmail, Calendar, Drive, Slack, Jira, HubSpot, Microsoft, or another external service. - Check whether the work should use an existing Agent before creating a new thread from scratch. ## The 10 Minute Setup Path
1

Start a clean chat

Ask a simple request and confirm the agent understands your role, source material, and desired output format.

2

Try one attached file

Attach a PDF, spreadsheet, image, or note and ask the agent to summarize, extract action items, or compare it with your instructions.

3

Use the right agent

Open Agents when you need a prepared role with its own prompts, data, tools, analytics, conversations, feedback, and history.

4

Track follow-up

Create a Task when the result needs ownership, review, or a status change before it is finished.

## What You Do Not Need On Day One You do not need to understand model connections, token limits, retrieval tuning, workflow internals, or every approval rule before using Siesta AI. Use the default agent setup, make the request clear, and inspect the result before anything is sent or changed externally. Continue with [Ask in Chat Effectively](#doc-user-guide-use-chat-effectively) for a first request or [Choose and Use Agents](#doc-user-guide-work-with-agents) when the work needs a prepared role and approved capabilities. ## When To Ask An Admin Ask an admin when a needed agent is missing, a shared connection expired, a tool is unavailable, a workflow is blocked by permissions, or a data collection is not visible to the right team. Admins can follow [Configure Shared and Private Connections](#doc-admin-guide-configure-shared-and-private-connections) or [Govern Data Collections and Sources](#doc-admin-guide-govern-data-collections-and-sources) to resolve those shared setup issues. --- # Choose Tasks AI Can Do Well ![AI readiness dimensions for choosing a useful task](/img/guides/ai-readiness.svg) AI is most useful when the task is based on language or recognizable patterns, the relevant context can be supplied, and a person can review the result before it creates material impact. Start a bounded trial in [Chat](#doc-chat), and use [Tasks](#doc-tasks) when the result needs ownership, status, or review beyond the conversation. ## Strong Task Patterns - Summarize a document, conversation, or collection of records. - Draft content for a known audience, tone, and purpose. - Compare versions, requirements, policies, or proposals. - Extract named fields into a table or structured format. - Classify messages, feedback, requests, or documents. - Translate or adapt content while preserving required terminology. - Brainstorm alternatives and organize them against criteria. - Answer questions using approved sources attached to an [agent](#doc-agents-overview). ## Use the Human-Colleague Test Ask: could a capable colleague complete the task by reading the provided material and producing a reviewable output? If yes, AI can often assist. If the colleague would need missing system access, exact calculations, physical measurements, or professional authority, supply the right tool or keep that part human-owned. ## Start With a Bounded Request Include: 1. the outcome you need, 2. the material the agent may use, 3. the specific task, 4. the required output structure, 5. the facts it must not invent, 6. what you will review next. For repeatable work, save the improved request in the [Library](#doc-templates) and record which source or agent it expects. Next, learn where human or tool ownership must remain explicit in [Recognize Tasks AI Should Not Own](#doc-user-guide-ai-working-practices-recognize-tasks-ai-should-not-own). --- # Recognize Tasks AI Should Not Own AI can assist with consequential work, but it should not become the unreviewed decision maker simply because its response sounds confident. Use approved [Tools](#doc-tools) for exact calculations or live actions, and ground claims in governed [Data](#doc-data-collections) when the answer depends on authoritative evidence. Keep the final consequential decision with the named human owner. Start with [Choose Tasks AI Can Do Well](#doc-user-guide-ai-working-practices-choose-tasks-ai-can-do-well) if you have not yet separated the reviewable AI contribution from the wider business decision. ## Keep These Boundaries Clear | Task characteristic | Safer approach | | --- | --- | | Exact arithmetic or financial totals | Use an approved calculation or business-system tool and verify inputs | | Current inventory, price, policy, or status | Retrieve it from an authoritative live system | | Precise measurements from diagrams or images | Use specialist CAD, measurement, or computer-vision software | | Legal, medical, financial, employment, or safety decision | Use qualified human review and approved procedures | | Irreversible external action | Require preview, confirmation, and a rollback or recovery path | | Missing or conflicting evidence | Mark the answer as unknown and request the required source | | Access or permission change | Keep the change with an authorized admin and audit it | ## Warning Signs in a Request Pause when the request asks the agent to guarantee correctness, decide without evidence, bypass approval, infer sensitive facts, expose data outside its access boundary, or “just make something up” to complete a report. ## Turn an Unsafe Task Into a Safe Assist Change “approve this proposal” into “extract the approval criteria, map the supplied evidence, identify gaps, and prepare questions for the approver.” Change “send the customer a final commitment” into “draft a response using confirmed facts and mark every unconfirmed date.” The useful boundary is often **prepare, compare, and flag**—followed by a named human decision. Review external actions in [Tool Executions](/tool-executions) before assuming they succeeded, and follow [Use Connections Safely](#doc-user-guide-use-connections-safely) for preview and approval practices. Once ownership and approvals are clear, continue with [Write Better AI Prompts](#doc-user-guide-ai-working-practices-write-better-ai-prompts). --- # Write Better AI Prompts ![Five-part prompting framework for decision-ready business output](/img/guides/prompting.svg) Almost any AI tool can answer a short request. The harder problem is getting a result that another person can review, reuse, and reproduce. Teams solve that problem by using one shared prompt structure instead of relying on clever wording. In Siesta AI, reusable agent-level instructions and their versions are documented in [Agent Prompts](#doc-agents-prompts). For a one-off request, apply the same structure in [Chat](#doc-chat). ## Use Five Explicit Parts Build business prompts from five parts: | Part | What to specify | Why it matters | | --- | --- | --- | | **Role** | The relevant expertise and responsibility | Sets the perspective and expected level of judgment | | **Context** | Goal, audience, background, sources, and known limitations | Replaces the questions a capable colleague would ask first | | **Task** | The exact action and the steps needed | Turns a broad topic into an executable request | | **Format** | Output type, fields, order, and length | Makes the result easier to verify and reuse | | **Constraints** | Source boundaries, prohibited actions, policy rules, and treatment of unknowns | Reduces unsupported assumptions and unsafe output | Most weak results come from requirements that were never stated. “Draft an email” may secretly mean “keep it under 150 words, acknowledge the issue without accepting liability, ask for two missing details, and propose a next step.” Put those requirements in the prompt. ## Copy-Ready Template ```text ROLE Act as [relevant role and seniority]. CONTEXT We need to [business goal]. The audience is [audience]. Use this background and these approved sources: [context and sources]. TASK Produce [specific outcome]. Follow these steps: [step 1], [step 2], [step 3]. FORMAT Return [memo, email, table, JSON, or another structure]. Include [required sections or fields]. Keep it within [length]. CONSTRAINTS Use only [approved data]. Do not [restricted behavior]. If information is missing, mark it Unknown and list what is needed. Separate verified facts, assumptions, and recommendations. ``` Keep the instructions separate from pasted source material. Clearly label sections such as `INSTRUCTIONS` and `DATA` so that teammates can review the request and the agent is less likely to confuse external content with directions. ## Treat Format as Quality Control Format is not decoration. A competitor review in a table with `Claim`, `Evidence`, `Source`, and `Confidence` columns is easier to check than an unstructured paragraph. A fixed schema also reduces cleanup when the output will become a CRM record, ticket, report, or workflow input. Use the same output shape across a team so reviewers can spot missing evidence and compare results consistently. ## Upgrade Weak Requests | Work | Weak request | Better direction | | --- | --- | --- | | Research | “Give me insights on this competitor.” | Ask for verified facts, clearly labelled inferences, open questions, evidence, sources, and confidence based on that evidence. | | Writing | “Write a memo about the change.” | Name the audience, what is changing, why it matters, required actions, deadline, length, and missing details the agent must not invent. | | Analysis | “Analyze this proposal.” | Ask for ranked risks, mitigations, approval criteria, and open questions that depend on internal policy or tooling. | | Planning | “Create a project plan.” | Supply team size and timeline, then request milestones, owners, dependencies, risks, and explicit scope trade-offs. | | Customer communication | “Reply to this angry customer.” | Set tone and length, require acknowledgement and next steps, and prohibit speculation, unconfirmed timelines, or risky commitments. | ## Review Before Reuse Before accepting a prompt as a team template, check that it: - defines what a high-quality result looks like; - includes the data needed to complete the task; - distinguishes evidence from assumptions; - states what the agent should do when facts are missing; - prevents sensitive data from being pasted into an unapproved agent or connection; - requires human review before consequential decisions or external actions. Avoid vague requests for “insights,” hidden goals, and prompts rebuilt from scratch every time. Start with a small shared library for research, writing, analysis, planning, and customer communication. Improve those templates from real reviewed outputs. ## Safe Use With External Content Webpages, email, retrieved documents, and tool responses can contain misleading or malicious instructions. Treat them as untrusted data, keep them separate from the prompt instructions, limit tools and sources to the approved scope, and require confirmation for high-impact actions. Next, use [The Five-Part Business Prompt](#doc-user-guide-ai-working-practices-five-part-business-prompt) for a deeper walkthrough of each field. The framework is based on Siesta AI's article [How to Write AI Prompts for Business: A Simple Framework for Teams](https://siesta.ai/blog/1693/how-to-write-ai-prompts-for-business-a-simple-framework-for-teams). --- # The Five-Part Business Prompt Use this framework when a request should produce a consistent, decision-ready output. Put one-off instructions in [Chat](#doc-chat), maintain role-level instructions in [Agent Prompts](#doc-agents-prompts), and save a tested reusable starting point in the [Library](#doc-templates). ## 1. Role Define the relevant perspective and responsibility, not a theatrical persona. ```text Act as a procurement risk analyst preparing evidence for a human approver. ``` ## 2. Context Explain the business situation, audience, supplied sources, terminology, and known limitations. ## 3. Task State the action and outcome precisely. Use verbs such as extract, compare, classify, draft, map, or identify. ## 4. Format Define the structure: headings, table fields, length, schema, or order of sections. ## 5. Constraints State source boundaries, approval rules, policy restrictions, tone, and how to handle missing information. ## Copy-Ready Template ```text Role: Act as [relevant professional perspective]. Context: We need to [business situation]. The audience is [audience]. Use only [sources or attached material]. Task: [specific action and intended outcome]. Format: Return [required structure, fields, length, or schema]. Constraints: Do not [prohibited behavior]. Separate verified facts from assumptions. If evidence is missing, mark it Unknown and list what is required. ``` The framework is a quality control, not a guarantee. Always review whether the supplied sources and requested action are appropriate for the selected agent. Next, test the result and decide what is safe to reuse with [Improve and Review Prompts](#doc-user-guide-ai-working-practices-improve-and-review-prompts). --- # Improve and Review Prompts Treat prompting as an iterative process. Review the output, identify which expectation was missing, update the controlled instruction in [Agent Prompts](#doc-agents-prompts), and test it again on representative cases. Use Feedback to inspect response-quality evidence and the [Library](#doc-templates) to distribute an approved reusable starting point. ## Pre-Run Quality Check | Check | Question | | --- | --- | | Objective | Is the real business goal clear? | | Audience | Does the agent know who will use the output? | | Context | Are essential facts, definitions, and sources supplied? | | Task | Is the requested action specific? | | Format | Is the expected output structure defined? | | Evidence | Are acceptable sources and citation needs stated? | | Unknowns | Does the prompt explain what to do when information is missing? | | Restrictions | Are security, policy, tone, and action boundaries included? | | Actionability | Will the result support a decision or next step? | | Reusability | Could a teammate use the same template safely? | ## Diagnose the Output - If it is generic, add the decision, audience, and evaluation criteria. - If it invents facts, constrain sources and define how to report unknowns. - If it is hard to review, define a table, fields, or section order. - If tone varies, supply a short approved example. - If content is incomplete, list mandatory sections and evidence. - If it takes an unsafe action, remove the tool or require confirmation. ## Maintain a Prompt Library Keep a small set of templates for recurring work. Record the owner, purpose, expected sources, compatible agent, output contract, restrictions, test examples, and review date. Retire templates when policy or workflow changes make them unsafe or misleading. The goal is not more prompts. It is a smaller set of tested instructions that teams can understand and improve. Next, see how the same source, specialist-agent, and human-review pattern scales in [Enterprise AI Use-Case Patterns](#doc-user-guide-ai-working-practices-enterprise-ai-use-case-patterns). Agent owners can use [Evolution](#doc-agents-evolution) to review prompt improvements grounded in feedback. --- # Enterprise AI Use-Case Patterns High-value enterprise use cases often share a common shape: many complex inputs, a short decision window, expensive omissions, and a need for both structured findings and follow-up questions. Once the reviewed sequence is stable, [Workflows](#doc-workflow) can coordinate its repeatable steps and approval points. ## Pattern 1: Complex Document Review Examples include due diligence, policy review, audit preparation, and technical assessment. 1. Ingest approved documents through [Data](#doc-data-collections) and preserve source identity. 2. Extract relevant text, tables, and metadata. 3. Organize the material into an access-controlled collection. 4. Ask [specialist agents](#doc-agents-overview) to review defined risk areas. 5. Produce a structured report with evidence links and open questions. 6. Let qualified reviewers validate findings and make the decision. ## Pattern 2: Requirements and Proposal Review For tender, procurement, or proposal workflows: - extract requirements, obligations, deadlines, and evaluation criteria, - create a traceable requirements register, - provide grounded question answering during preparation, - compare the proposed response against the original requirements, - flag missing, weak, conflicting, or unsupported sections, - route final readiness and risk decisions to accountable reviewers. ## Shared Architecture ![Governed data and intelligence layers for enterprise use cases](/img/guides/flow-layers.svg) The model is only one part of the solution. Reliable work also needs source processing, access controls, memory or retrieval, specialist instructions, tools, review checkpoints, and evidence in the final output. ## Start Safely Begin with a read-only pilot and a representative document set. Define what complete coverage means, test known hard cases, and measure reviewer acceptance and missed requirements. Do not promise that AI replaces legal, financial, security, or domain-expert judgment. Ask an admin to approve sources and access before loading sensitive material through [Data Governance](#doc-admin-guide-govern-data-collections-and-sources). Follow [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) for the day-to-day product workflow, then [Repeat Work With Workflows](#doc-user-guide-create-useful-workflows) only after the read-only pattern is stable. --- # Ask in Chat Effectively [Chat](#doc-chat) is the fastest place to ask, draft, compare, summarize, and work with files. It can also continue into agent work, task creation, [tool calls](#doc-tools), and realtime conversations when those capabilities are enabled. ## Write Requests The Agent Can Execute Good chat requests include four parts: - **Source**: the file, conversation, data collection, memory page, URL, or pasted text to use. - **Goal**: what should be produced or decided. - **Constraints**: tone, length, audience, allowed sources, deadline, or system limits. - **Next action**: whether to only draft, ask for confirmation, create a task, or prepare an external action. ```text Use the attached customer email and the Support FAQ data collection. Draft a reply for a non-technical customer, under 120 words, and do not send it. ``` ## Use Files Deliberately Attach files when the agent needs current context that is not already in Data or Memory. Name what each file is for: summarize, extract action items, compare two versions, clean a CSV, draft a report, or inspect a screenshot. If the work should be reused by many users, move the source into **Data** or **Memory** instead of reattaching the same file in every chat. ## Before A Tool Action Ask for a preview before external writes: ```text Prepare the Jira ticket, but show me the summary, description, priority, and acceptance criteria before creating it. ``` When a tool runs, the conversation can show status and approval behavior. If something looks wrong, open [Tool Executions](/tool-executions) and inspect the action, arguments, result, and approval state. ## Prompt Patterns That Work ### Summarize a source ```text Summarize this recording into decisions, risks, owners, and follow-up tasks. Quote only short fragments when needed. ``` ### Compare files ```text Compare these two PDFs. Return only changed obligations, missing sections, and open questions in a table. ``` ### Continue later ```text Turn this into a task for the Sales Operations agent. Include context, expected output, and what needs review. ``` ### Use a data collection ```text Answer only from the Q2 Product Feedback data collection. If the answer is not there, say what is missing. ``` ## When Chat Is Not Enough Move from Chat to the corresponding operating guide: - [Choose and Use Agents](#doc-user-guide-work-with-agents) when the work needs a prepared role, tools, and controlled data. - [Use Tasks to Track Work](#doc-user-guide-use-tasks-to-track-work) when work needs status, ownership, or review. - [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) when files or synced sources should be reused. - [Repeat Work With Workflows](#doc-user-guide-create-useful-workflows) when the same steps should run repeatedly. --- # Choose and Use Agents import Link from '@docusaurus/Link'; # Choose and Use Agents [Agents](#doc-agents) are prepared assistants with a role, model configuration, prompts, data access, tools, interfaces, analytics, conversations, feedback, and history. Review an agent's intended purpose in [Overview](#doc-agents-overview) and its core setup in [Configuration](#doc-agents-configuration). Use agents when the answer should follow a known operating pattern instead of a one-off chat.
Overview Configuration Interfaces Prompts Analytics Evolution Conversations Feedbacks History
## Choose The Right Agent Use the agent that already matches the job. Check the name, description, access level, model, tools, data collections, and whether it is intended for internal chat, public chat, widget use, or automated work. Do not ask a general agent to do work that depends on a specialized tool or private data collection. If the agent cannot see the source, it will either ask for more context or produce a weaker answer. ## What To Check Before Trusting Output - **Source**: did the agent use the right file, data collection, memory page, or conversation? - **Tool use**: did it call the expected tool, and did that call succeed? - **Scope**: is the answer inside the agent's configured purpose? - **External action**: did you approve the final action before it changed another system? - **Review**: should the result become a Task for someone else to approve? ## Agent Pages In The Product | Page | Use it for | | --- | --- | | Overview | Understand what the agent is for and whether it is the right choice. | | Configuration | Review core setup such as model, data, tools, and access policy. | | Interfaces | Public chat, web widget, authenticated widget, and external exposure settings. | | Prompts | See or manage the agent instructions and reusable prompt versions. | | Analytics | Review usage and behavior trends for the agent. | | Evolution | Inspect or apply prompt improvements from feedback. | | Conversations | Review conversations created with this agent. | | Feedbacks | Inspect ratings, comments, and feedback message context. | | History | Audit changes made to agent configuration and related records. | ## Common Agent Jobs - Draft customer replies from approved support knowledge. - Create tasks, tickets, or CRM notes after user confirmation. - Summarize meeting recordings and extract owners. - Answer from a data collection without inventing missing policy details. - Run website assistant or widget flows through the agent interface. ## If The Agent Is Wrong Do not keep retrying the same vague prompt. Add the missing source with [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections), switch to the correct agent, check [Tool Executions](/tool-executions), or [create a Task for review](#doc-user-guide-use-tasks-to-track-work) with the failed output attached. --- # Use Tasks to Track Work

Reviewable agent work

Turn agent output into tracked work.

Tasks make agent work visible, reviewable, and resumable. Use them when an answer needs ownership, a status, acceptance criteria, or a human review loop.

Siesta AI
For the exact workspace, filters, statuses, and task-detail behavior, see the [Tasks Product Specification](#doc-tasks). If task behavior changed after it was created, [Agent History](#doc-agents-history) helps an administrator check whether the assigned agent's configuration changed. ## When To Create A Task

Needs review

A result should be checked before it is sent, published, or used outside the conversation.

Needs an owner

Someone needs to own follow-up work, make a decision, or continue the next step later.

Needs continuity

The agent should resume later with the same context instead of starting from an empty chat.

Needs investigation

A workflow, tool call, or conversation produced a concrete action item or failure to inspect.

## Statuses The task board uses four operating states:
Todo

Work is captured but not started.

In progress

The owner or agent is actively working.

In review

The output needs a human or teammate check.

Done

The work is complete and no more action is expected.

Tasks can be reviewed in table or kanban style views. Use search and status filters when the list grows. ## A Good Task Has
A short outcome-focused title. The source conversation, file, or data collection. The assigned agent or owner. A clear expected output. Acceptance criteria or review notes.
```text Create a task for the Reporting agent. Goal: compare Q2 feedback themes with last quarter. Output: table of top issues, count, source examples, and recommended next action. Status: In review. ``` ## Recover Missing Context If a task result looks detached from the original request, open the [source conversation](#doc-conversations) or task conversation history. If the source is missing, add it directly to the task before asking the agent to continue. Use [Continue Past Work](#doc-user-guide-use-recordings-and-conversations) when you need to reconstruct a longer handoff. --- # Use Connections Safely

Connected work

Let agents use tools without losing control.

Connections let agents work with email, calendars, storage, CRM, issue trackers, REST APIs, MCP servers, and internal tools. A successful call can read, create, update, or send real data, so treat each connection as both capability and permission.

Siesta AI
For the connection catalog, authentication fields, sharing model, and function policies, see [Connections](#doc-connections) and [Tools](#doc-tools) in the Product Specification. ## How Connections Work

Account

A connection points to credentials or OAuth for a provider. The agent can only do what that connected account is allowed to do in the external system.

Access policy

Connections can be personal, shared with a team, or controlled by organization policy. If you cannot use one, the agent may not have access to that connection.

Function rules

Each function can be enabled, disabled, or enabled with confirmation. Read-only functions usually run directly; data-changing functions should be reviewed first.

Execution trace

Tool Executions keep the function name, arguments, status, result, and approval state. Use Tool Executions or conversation history when you need to audit what happened.

## Personal And Shared Connections Use a **personal connection** when the work should happen as you: Gmail, calendar scheduling, Drive files, Slack messages, or anything tied to your account permissions. Use a **shared connection** when a team or organization owns the integration: a support Jira project, a CRM workspace, a shared mailbox, a company REST API, or a production MCP server. Shared connections are better for repeatable agents and workflows because they do not depend on one user's private account staying connected. If a request fails, ask the agent which connection it tried to use. Then check whether you are in the right organization, whether the agent has that connection attached, and whether an admin forced a stricter function rule. ## Common User Use Cases
Schedule a meeting

Ask the agent to find open times, draft the calendar event, show attendees and description, then create it only after you approve the payload.

Create a Jira or CRM follow-up

Turn a chat result into a ticket, lead note, or customer record. Include source context, owner, priority, due date, and acceptance criteria before writing.

Research from connected files

Let the agent read Drive, OneDrive, SharePoint, Confluence, Gmail, or Slack content to answer a question without uploading the same files again.

Call an internal tool

Use REST or MCP connections for product actions such as checking subscription state, fetching customer data, creating an internal task, or triggering a workflow.

Run repeatable workflows

Use a shared connection for recurring work where the agent should produce the same structured result every time, such as weekly reporting or ticket triage.

Investigate a failed action

Open the tool execution record, inspect the arguments, approval state, result, and error. That usually shows whether the issue is access, payload, or provider state.

## Before A Write Action Ask the agent to show the exact payload before it changes another system: ```text Prepare the Google Calendar event, but show me title, attendees, time, description, conference settings, and timezone before creating it. ``` ```text Draft the Jira issue first. Include project, issue type, summary, description, priority, assignee, labels, linked customer, and acceptance criteria. Do not create it until I approve. ``` Use this pattern for emails, calendar events, Jira issues, CRM notes, file updates, workflow actions, REST calls, or any tool call that changes another system. If the function is configured as `EnabledWithConfirmation`, Siesta AI should pause with a pending approval before the write is executed. ## What To Check
The connected account is the account you intended to use. The agent has the connection attached or can access the shared tool. The function is not disabled by organization policy. Data-changing functions are reviewed before approval. The payload contains the right workspace, project, folder, channel, or CRM object. The result in Tool Executions is Success after the provider accepts the call.
## Common Problems | Symptom | Likely cause | Next step | | --- | --- | --- | | Tool is missing | The agent does not have that tool or connection attached | Use the correct agent or ask an admin to add the connection. | | Authorization failed | OAuth token expired, API key changed, or the external account lost permission | Reconnect the account or ask the owner of the shared connection to refresh it. | | Approval required | The function changes data and is configured with confirmation | Inspect the arguments, approve if correct, or reject and ask the agent to revise. | | Access denied | The connected account cannot reach the external workspace, folder, project, or record | Switch to the right connection or request access in the external system. | | Function disabled | Organization governance forced the function to `Disabled` | Ask an admin whether that provider action is allowed for your team. | | Wrong workspace | You are in the wrong Siesta AI organization, team, or external tenant | Switch context before retrying. | | Provider rejected the payload | Required fields, IDs, enum values, or formatting do not match the external system | Ask the agent to show the exact payload and repair the invalid fields. | ## After The Tool Executes Check the final result where the work happened, not only in chat. For a calendar event, open the calendar. For Jira or CRM, open the created record. For a REST or MCP action, check the returned object ID or status. If anything looks wrong, use the [details in Tool Executions](/tool-executions) to see the original arguments and ask the agent to correct or revert the action where possible. For a failed personal or shared integration, follow [Troubleshoot Common Problems](#doc-user-guide-fix-common-problems). Admins can use [Configure Shared and Private Connections](#doc-admin-guide-configure-shared-and-private-connections) when the issue affects a team-owned credential or policy. --- # Use Sources and Files Data collections let you reuse trusted files and records across conversations and agents. A collection is not just a folder: Siesta AI imports the selected content, processes it into searchable chunks, and makes those chunks available to assigned agents. For the complete field-by-field reference, see [Data](#doc-data-collections). This guide focuses on the choices a user makes during everyday work. ## Detailed Source Setup Use the source-specific guides for the exact fields and examples shown in the current application: - [Choose a Data Source](#doc-data-choose-a-source) - [Manual Upload](#doc-data-manual-upload) - [Google Drive](#doc-data-google-drive) - [Microsoft 365: OneDrive and SharePoint](#doc-data-microsoft-365) - [Azure Storage Account and Azure File Share](#doc-data-azure-storage) - [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion) - [Jira and Confluence](#doc-data-atlassian) - [Firecrawl](#doc-data-firecrawl) - [Processing, Sync, and Troubleshooting](#doc-data-processing-sync-and-troubleshooting) As a user, focus on choosing the authoritative material, entering the right folder, path, or key, verifying indexed documents, and testing the agent. Follow [Use Connections Safely](#doc-user-guide-use-connections-safely) for personal access; ask an admin to prepare shared credentials, change access boundaries, or resolve provider-wide authentication failures through [Admin Data Governance](#doc-admin-guide-govern-data-collections-and-sources). ## Decide Between An Attachment And A Collection | Situation | Use | | --- | --- | | You need one file in one conversation | Attach the file in Chat | | The same source should serve several conversations or agents | Data collection | | A folder or external system changes over time | Synchronized data source | | The content is a signed-off snapshot that should not change silently | Manual Upload | | The information is short knowledge you maintain directly in Siesta AI | Memory | ## Pick The Source That Matches Ownership - **Manual Upload**: you own a stable copy and intentionally replace it when a new version is approved. - **Google Drive**: a Google account or Shared Drive owns the live folder. - **OneDrive**: one Microsoft user owns or receives the live files. - **SharePoint**: a team site or document library owns governed business content. - **Azure Storage Account**: an application or data pipeline publishes blobs. - **Azure File Share**: an operational file share is the source of truth. - **Jira**: project issues are the source of truth. - **Confluence**: one space is the maintained knowledge base. - **Firecrawl**: an approved website is the source and no native connector is available. Choose the system that already owns updates. Re-uploading a frequently changing Drive folder manually creates stale copies and makes ownership unclear. ## Create A Useful Collection 1. Open **Data**. 2. Select **Create collection**. 3. Use a name that describes the knowledge, such as `Customer onboarding — approved`. 4. In the description, record the owner, content scope, and intended agents. 5. Keep the collection Private unless team or organization sharing is intentional. Good collections have one purpose. Split `HR policies`, `Sales collateral`, and `Engineering runbooks` instead of creating one collection called `Company files`. ## Add A Manual Upload 1. Open the collection and select **Add data source → Manual Upload**. 2. Name the source after the snapshot or release, for example `Support policies — 2026 Q3`. 3. Upload at least one file. 4. Leave processing defaults unless you have tested a reason to change them. 5. Confirm and wait for the source to finish processing. Manual Upload supports the file classes shown in the app: JSON, text, PDF, Word, Excel, PowerPoint, Markdown, and Other. It is best for approved snapshots, exports, signed documents, and small controlled sets. When a new version arrives, agree with the collection owner whether to replace, delete, or retain the old source. Keeping two documents that give different answers is a common cause of inconsistent agent output. ## Add Google Drive Ask an admin for a shared Google Drive connection, or use a private connection when the source is personal. 1. Open the target folder in Drive. 2. Copy only the folder ID from the URL after `/folders/`. 3. In the Google Drive source form, select the intended connection. 4. Add the folder ID under **Folders**. 5. Enable **Include subfolders** only if the full tree belongs in the collection. 6. Enable **Include shared drives** when the content is in a Shared Drive. 7. Choose a sync frequency based on how often the source changes. If a file is missing, first confirm that the connected Google account—not only your personal account—can open it. ## Add Microsoft Content ### OneDrive Use paths relative to the connected OneDrive, such as: ```text Documents/Customer Onboarding Shared/Monthly Reports ``` Use OneDrive for user-owned content. The source can stop seeing files if sharing or the connected user's permissions change. ### SharePoint Use SharePoint for team-owned libraries and governed departmental documents. Enter the exact library/folder path, for example: ```text Shared Documents/Policies ``` If you cannot decide: personal drive content belongs in OneDrive; team-site/library content belongs in SharePoint. ## Add Azure Content ### Azure Storage Account The administrator first creates an Azure Storage connection containing the credential. In Data, you select that connection and enter the **Blob** name/path or selector required for the target storage ingestion. Never paste the connection string or account key into Blobs. Use this source for application exports, generated documents, archive feeds, or large repositories delivered to Blob Storage. ### Azure File Share Select the prepared connection and add the exact Azure file-share name. Use it for an established file share; do not use it for blobs simply because both live in one Azure Storage account. If the source succeeds but contains no files, give the admin the connection name, collection name, source name, entered selector/share name, and the latest log status. Do not send credentials in chat or screenshots. ### Use an automated Azure File Share feed In an automated feed, an administrator publishes approved internal documents to Azure File Share and Siesta AI synchronizes them into your collection. You do not need mount commands or storage credentials. After each relevant update: 1. Open **Files** and confirm that the expected document is present, Indexed, and Readable. 2. Check the document title, source, and visible version information. 3. Ask a known-answer question and require a citation to the source document. 4. Ask one question that is not covered and confirm that the agent does not invent an answer. 5. After a version change, confirm that the citation and answer use the new approved version. Report stale or missing data with the collection name, source name, expected document, expected version, last sync time, and observed answer. Do not include credentials. An admin can then determine whether the problem is in the upstream selection, Azure publication, ingestion, or agent retrieval. ## Add Jira Or Confluence For Jira, enter the project key such as `SUP`, not `SUP-123`, a board name, or JQL. Use it when issue descriptions and status history should be searchable. For Confluence, select the space key such as `HELP`. Use it when pages in that space are maintained as the official knowledge base. If Jira and Confluence have different audiences, keep them in different collections even when both use the same Atlassian account. ## Add A Website With Firecrawl Use **Scrape** for one page and **Crawl** for a controlled section of a site. Start small: ```text URL: https://example.com/docs Limit: 20 Include paths regex: ^/docs Exclude paths regex: ^/docs/archive ``` Do not crawl authenticated applications, personal dashboards, customer portals, or sites that you are not allowed to copy. A broad crawl can import navigation, duplicate pages, outdated versions, and irrelevant content. ## Choose A Sync Frequency - **On Demand**: signed policies, quarterly exports, and sources that change only after review. - **Daily**: operational documentation, active project issues, and frequently updated shared folders. - **Weekly**: maintained knowledge whose changes are not urgent. - **Monthly**: slow-moving archives and reference material. Faster is not automatically better. Frequent syncs consume provider and processing capacity and can introduce unreviewed changes into agent answers sooner. ## Wait For The Right Status Do not attach a new source to a production agent merely because it exists. - **Scheduled/Created**: ingestion is queued. - **Pending**: documents are being processed. - **Processed/Successful**: the run completed; verify the files. - **Failed**: inspect Logs and correct the connection or selector. - **Skipped**: review file types and document readability. Open **Files** and check that representative documents are `Indexed` and `Readable`. Open one document and confirm that its chunks contain useful text rather than headers, empty output, or corrupted characters. ## Use A Collection In An Agent After the collection owner or admin attaches it to an agent, make the source requirement explicit in your prompt: ```text Answer from the Customer Onboarding collection only. For every recommendation, cite the source document name. If a point is not covered, write “not found in the collection”. ``` When comparing collections: ```text Compare the current policy in Approved Policies with the proposal in Draft Policies. Keep the two sources separate and list contradictions with document names. ``` ## Evaluate The Result Test the agent with four question types: 1. A fact you know is present. 2. A fact you know is absent. 3. A fact that appears in two versions. 4. A fact changed since the last synchronization. If the agent guesses when information is absent, improve the agent instruction. If known text cannot be found, inspect the document and chunks before changing the prompt. ## Safe Daily Practices - Use collection and source names in prompts instead of saying “use the files”. - Verify the source document before acting on a high-impact answer. - Do not upload secrets, credential exports, private keys, or files outside the approved audience. - Do not delete failed documents until the owner decides whether they are needed. - Ask an admin before changing access from Private to team or organization scope. - Report stale content with the source name, expected document, last sync, and current status. ## Troubleshooting As A User | Problem | What to do | | --- | --- | | You cannot see a collection | Ask the owner/admin to verify team membership and collection access. | | The provider connection is missing | Ask for the correct shared connection or create an approved private connection. | | A folder imports nothing | Recheck the folder ID/path and whether the connected account has access. | | A source is Failed | Open Logs and send the non-secret error/status context to the admin. | | A document is present but not used | Confirm Indexed/Readable, inspect chunks, and verify the collection is attached to the agent. | | The answer uses an old version | Check last sync, trigger a refresh if allowed, and identify duplicate documents. | --- # Repeat Work With Workflows import Link from '@docusaurus/Link'; # Repeat Work With Workflows Use [Workflows](#doc-workflow) when the same process needs to run more than once with predictable inputs, checks, and tool actions. An external system can start an approved flow through [Webhooks](#doc-webhooks). A workflow should remove repeated manual steps, not hide unclear decisions. ## Good Workflow Candidates - Create a task or ticket from a structured intake. - Summarize a recurring recording and route action items. - Check a source, classify the result, and notify the right team. - Run a reporting sequence that uses the same data collection each time. - Prepare an external update and wait for approval before sending. ## Before You Build Define: - Trigger or input. - Agent or tool that should handle each step. - Data collection or memory source. - Approval points. - Failure owner and retry rule. - Final output or external system update.

Keep workflows inspectable If a workflow changes another system, make the payload visible before approval and review Tool Executions when something fails.

## Example Flow 1. User submits an intake request. 2. Agent summarizes the request and checks missing fields. 3. Agent searches the approved data collection. 4. Tool creates a draft task or ticket. 5. Human reviews the payload. 6. Workflow records the result and marks the task for review. ## Debug A Workflow When a workflow fails, open the related conversation or [Tool Executions](/tool-executions). Check which action failed, whether the approval state is pending, whether the connection expired, and whether the input was complete. Use [Connections Safely](#doc-user-guide-use-connections-safely) to verify the account, access policy, and approval rule before retrying. --- # Use the Library The [Library](#doc-templates) helps users start from a known template instead of rebuilding the same agent, task, prompt, or workflow structure. Check [Agent Prompts](#doc-agents-prompts) when the reusable behavior belongs to an agent rather than only to one template. Use a template when the desired output has a repeatable shape. ## How To Use A Template 1. Choose the closest template. 2. Read the required fields before running it. 3. Replace placeholders with real source material, audience, constraints, and review owner. 4. Run once with a low-risk example. 5. Save or share only after the output is predictable. ## Good Template Inputs - Role or business process. - Source system or data collection. - Expected output format. - Approval rule. - Escalation owner. - Example of a correct result. ## Template Examples | Template | Use it for | | --- | --- | | Customer reply | Draft support responses from approved knowledge. | | Bug intake | Turn a report into a structured task or ticket. | | Meeting summary | Extract decisions, owners, risks, and follow-ups. | | Sales research | Gather account context and prepare outreach notes. | | Reporting | Produce the same table or narrative from updated inputs. | ## Avoid Template Drift If people keep editing the same fields after every run, the template is probably too generic. Add sharper placeholders, clearer constraints, and a short example output. Before publishing a prompt-based template for a team, apply the checklist in [Improve and Review Prompts](#doc-user-guide-ai-working-practices-improve-and-review-prompts). Ask an admin to review organization-wide reuse through [Prepare Agents and Workflows for Teams](#doc-admin-guide-prepare-agents-and-workflows-for-teams). --- # Continue Past Work

Context recovery

Find the thread, recording, or agent change that explains what happened.

Use conversations, recordings, and agent history when work should continue from existing context, when a decision needs evidence, or when an answer changed and you need to understand why.

Siesta AI
The Product Specification documents the exact [Recordings](#doc-recordings), [Conversations](#doc-conversations), and [Agent History](#doc-agents-history) views. This guide focuses on choosing the right evidence and carrying it forward safely. ## Pick The Right History Source

Continue a conversation

Use the existing conversation when the same source files, tool results, approvals, or decisions should still influence the next answer.

Summarize a recording

Use a recording when you need meeting decisions, owners, risks, customer asks, or follow-up tasks extracted from a call.

Explain a behavior change

Use agent history with feedback and conversations when an agent used to answer correctly but now follows a different prompt, tool, data source, or access rule.

## Real User Scenarios
Resume a customer answer

Open the last conversation, ask the agent to restate the current answer, missing evidence, and recommended next action. Create a Task if someone should own the follow-up.

Turn a meeting into work

Ask for decisions, owners, due dates, unresolved risks, and suggested tasks. Keep task creation in draft mode until the owners and deadlines are confirmed.

Audit a tool action

Use the conversation and Tool Executions together: the conversation explains intent, while Tool Executions show the exact function, arguments, approval, result, and error.

Start fresh safely

When the old thread contains the wrong customer, stale policy, or unrelated tool result, create a new conversation and paste only the facts that should carry forward.

## Conversation Or New Chat Use the same conversation when you need continuity: - The source files or pasted context are still relevant. - The agent already asked clarifying questions. - A tool action, approval, or generated file belongs to the same work. - You need to turn the thread into a Task or share it with another user. Start a new chat when the topic, customer, permissions, or required source changes. This prevents stale context from shaping the next answer. ## Recording Prompt Pattern ```text Summarize this recording into decisions, owners, risks, open questions, and follow-up tasks. Do not create tasks until I approve the list. Mark anything that was discussed but not decided. ``` For customer calls, add: ```text Separate customer commitments from internal ideas. Include exact next steps, owner, due date, and which source or speaker supports each action item. ``` ## When The Answer Changed If an agent behaves differently than before, check in this order: 1. Conversation context: did an old instruction or file influence the answer? 2. Agent prompts: did the role, constraints, or expected output change? 3. Data and Memory: was a source attached, removed, stale, or reprocessed? 4. Connections and tools: did access, function confirmation, or an external account change? 5. Feedback and history: did someone approve a prompt improvement or configuration edit? ## Handoff Checklist
Link the conversation or recording. Name the agent used for the work. List source files, data collections, or memory pages. Include tool action status and approval state. State what is already decided and what still needs review. Create a Task when ownership or status tracking matters.
Use [Tasks to Track Work](#doc-user-guide-use-tasks-to-track-work) when the recovered context needs an owner, status, or review step. If the issue comes from a changed shared setup, ask an admin to follow [Monitor Usage, Audit Logs, and Risk](#doc-admin-guide-monitor-usage-audit-logs-and-risk). --- # Save Reusable Context [Memory](#doc-memory) is for maintained knowledge that should stay available across work. In [Chat](#doc-chat), context is the temporary material in a conversation: messages, files, selected agent state, and tool results. ## Use Memory For - Team playbooks. - Terminology and standard answers. - Policies, FAQs, and escalation rules. - Customer or project notes that need maintenance. - Short reusable guidance that agents should apply repeatedly. If an agent has Memory attached, it can still be read-only. Ask an admin or agent owner whether **Memory write** is enabled before expecting the agent to create or update Memory pages directly. ## Use Data Instead When - The source is a file, folder, repository of documents, synced SaaS system, or website crawl. - You need processing status and source-level updates. - The source should be attached to a specific agent or collection. Follow [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections) for that workflow and use the [Data Product Specification](#doc-data-collections) for every source type and field. ## Keep Memory Useful - Keep pages short and current. - Name the audience and scope. - Remove stale rules instead of adding corrections below them. - Tell the agent which Memory page to use. - Ask the agent to say when the answer is not present in Memory. ## Example ```text Use the Support Escalation memory page. Classify this customer issue, explain the next step, and list anything missing from the memory page. ``` ## Fix Wrong Context If the answer uses the wrong customer, policy, or prior instruction, start a new conversation or explicitly reset context: ```text Ignore earlier customer examples in this conversation. Use only the attached contract and the Enterprise Pricing memory page. ``` If you need to preserve evidence from the previous work instead of resetting it, follow [Continue Past Work](#doc-user-guide-use-recordings-and-conversations). --- # Troubleshoot Common Problems Most user-facing problems come from missing access, missing source material, expired connections, unclear prompts, or a tool action that failed. Diagnose the smallest visible symptom first. Use the [Help page](#doc-help) for support channels. ## Fast Diagnosis | Symptom | Likely cause | First action | | --- | --- | --- | | Agent cannot find a file | Data collection is not attached, not processed, or not visible | Follow [Use Sources and Files](#doc-user-guide-upload-and-use-data-collections), check Data status, and name the collection. | | Tool is missing | Agent does not have the tool or connection enabled | Follow [Choose and Use Agents](#doc-user-guide-work-with-agents) or ask an admin to enable it. | | Authorization failed | Personal or shared connection expired | Follow [Use Connections Safely](#doc-user-guide-use-connections-safely), reconnect, or ask the shared connection owner. | | Output is vague | Request lacks source, audience, constraints, or format | Rewrite the request with the exact source and expected output. | | Tool failed | Bad input, missing permission, or external API error | Inspect [Tool Executions](/tool-executions) and send the error to an admin. | | Wrong team data appears | Organization, team, or agent scope is wrong | Switch workspace or stop and ask an admin. | ## Better Retry Pattern Do not just type "try again." Add the missing detail: ```text Retry using the Q2 Support Feedback data collection only. If the answer is not present, return "not found" and list the missing source. ``` For external actions: ```text Retry only after showing me the exact payload. Include the connected account, destination workspace, and record that will be changed. ``` ## What To Send To Support Or An Admin - Organization and team. - Agent name. - Conversation or task link. - Data collection or memory page name. - Tool execution status, action, arguments, and error. - What you expected to happen. - Screenshot only if the page state matters. --- # Release Notes export const releases = [ { version: '1.2.6', dateLabel: 'July 23, 2026', title: 'Image Generation, Chrome Extension, GitHub, and Azure AI Foundry Model Router', summary: 'Image Generation, Chrome Extension, GitHub, Azure AI Foundry Model Router, Organization Library, Azure File Share ingestion, richer chat outputs, clearer limits, and workflow recovery.', href: '/releases/1-2-6', tags: ['Feature'], }, { version: '1.2.5', dateLabel: 'June 16, 2026', title: 'Onboarding guidance, connection expansion, and safer public-agent behavior', summary: 'Expanded onboarding guidance, added Azure Dev Ops, Airtable, and LinkedIn Ads, and improved auditing, public-agent behavior, and data-processing reliability.', href: '/releases/1-2-5', tags: ['Feature', 'Fix'], }, { version: '1.2.4', dateLabel: 'April 1, 2026', title: 'Memory, Skills, Google Analytics, Office 365, and OneDrive', summary: 'Memory and Skills, new Google Analytics, Office 365, and OneDrive integrations, simplified registration.', href: '/releases/1-2-4', tags: ['Feature', 'Fix'], }, { version: '1.2.3', dateLabel: 'March 5, 2026', title: 'Onboarding, invitations, SharePoint, Ads, Trends, and workflow timing', summary: 'Onboarding wizard, user invitations, SharePoint data source, Google Ads and Google Trends tools, workflow time triggers and conditions.', href: '/releases/1-2-3', tags: ['Feature'], }, { version: '1.2.2', dateLabel: 'February 20, 2026', title: 'Firecrawler, Jira, Confluence, imports, scheduling, and triggers', summary: 'New Firecrawler, Jira, and Confluence data sources, import management, scheduling, and trigger-based updates.', href: '/releases/1-2-2', tags: ['Feature', 'Fix'], }, { version: '1.2.1', dateLabel: 'February 5, 2025', title: 'Backend stabilization and clearer agent access controls', summary: 'Backend stabilization, working Azure AI Foundry integration, clearer private/shared/organization agent access, and default recording settings.', href: '/releases/1-2-1', tags: ['Fix'], }, { version: '1.2.0', dateLabel: 'January 26, 2025', title: 'UX, permissions, expanded chat, public chat, workflows, and recordings', summary: 'UX improvements, user and permission management, expanded chat, Public Chat configuration, Workflows beta, Webhooks, and Recordings.', href: '/releases/1-2-0', tags: ['Feature', 'Fix'], }, { version: '1.1.12', dateLabel: 'December 3, 2025', title: 'Sharing, copy actions, Stop in chat, localization, and bug reporting', summary: 'Conversation sharing, message copying, Stop in chat, default General Agent, localization fixes, and unified bug reporting form.', href: '/releases/1-1-12', tags: ['Feature', 'Fix', 'Docs'], }, ]; export const latestRelease = releases[0]; # Release Notes Track the visible product changes across Siesta AI. Each version links to its detailed release note. This page is the operational summary: what changed, when it shipped, and which type of change it was. The latest public release is {latestRelease.version} ({latestRelease.dateLabel}): {latestRelease.title}. ## Release Timeline {releases.map((release) => ( ))}
Version Date Highlights
{release.version} {release.dateLabel} {release.title}
--- # Release 1.2.6 **Version:** 1.2.6 **Release Date:** 23.7.2026 **Release Type:** Minor Release ## Summary This release expands what agents can create and where they can work. Agents can now generate images, work directly in the browser through the Chrome Extension, and connect to GitHub. Azure AI Foundry Model Router, Organization Library, Azure File Share ingestion, richer chat outputs, clearer limit visibility, and workflow error handling bring additional capabilities for enterprise teams. ## New Features ### Image Generation - Agents can now generate original images as part of their work, expanding their outputs beyond text-based responses. ### Chrome Extension - The new Chrome Extension places agent chat in a side panel alongside the page you are viewing. - Agents can work with the open page, selected text, screenshots, and uploaded files, with support for voice interaction. ### Azure AI Foundry Model Router - Azure AI Foundry Model Router can select a suitable model for each request, reducing the need to configure a specific model for every agent and scenario. ### Organization Library - Teams can share templates through a central library available across the organization. - Skills, templates, and categories can be imported into the Organization Library for enterprise deployments. ### Richer Chat Outputs - Generated HTML can be displayed in an isolated iframe preview directly in chat. - Generated code can be downloaded as a file for further use. ## New Integrations ### GitHub Connection - The GitHub connection enables agents to read repositories and work with branches, issues, and workflows. - Agents can also prepare changes and pull requests through a controlled workflow. ### Azure File Share - Azure File Share can now be connected as an enterprise data source, making its content available for ingestion and use by agents. ## Improvements ### Analytics and Limits - A dedicated **Limits** analytics dashboard provides a clearer view of available model and connection limits. - Chat now shows context usage and applicable limits, helping users understand the capacity available for the current conversation. ### Workflows - Workflows can define an explicit **Error Handler** path for failed nodes, making fallback and recovery behavior more predictable. --- # Release 1.2.5 **Version:** 1.2.5 **Release Date:** 16.6.2026 **Release Type:** Minor Release ## Summary This release expands onboarding and connection coverage, improves security and auditing readiness, and resolves several issues affecting public-agent behavior, content safety, and data processing reliability. ## Improvements - Improved onboarding flow to guide users toward more relevant promoted agent categories during registration. - Strengthened platform readiness for safer public-agent and content-handling scenarios. - Improved reliability in public chat and data-processing flows. ## New Integrations - Azure Dev Ops - Airtable - LinkedIn Ads ## New Features ### Onboarding - Registration onboarding now better supports category-based agent selection. - Promoted categories and promoted agents can be surfaced earlier in the onboarding flow to help users activate a more relevant first assistant faster. ### Security and Auditing - Prompt-injection mitigation work was extended toward clearer best-practice handling and safer treatment of untrusted inputs. - Audit coverage for tool calls was expanded so operational review of agent actions is more structured and easier to trace. ### Agent and Chat Experience - Intro-message behavior was improved so the first assistant interaction can work more clearly as a guided opening message. - Public-agent behavior was improved so shared or public-facing agents can trigger configured skills more reliably. ## Bug Fixes - Fixed cases where chat crashed when processing HTML files. - Fixed content-safety limit behavior. - Fixed storage-account data processing issues, including cases where processing incorrectly finished without extracted content. - Fixed issues affecting default-agent setup behavior. - Fixed connection-scope limitations in Google Tag Manager write operations. --- # Release 1.2.4 **Version:** 1.2.4 **Release Date:** 1.4.2026 **Release Type:** Minor Release ## Summary This release introduces the new Memory and Skills features, which significantly expand AI capabilities for working with context and task automation, together with new integrations and platform improvements. ## Improvements - Simplified registration process for new users. ## New Integrations - Google Analytics - Office 365 (Excel, Word) - OneDrive ## New Features ### Memory - Memory makes it possible to store and share structured context, such as company, product, or customer information, in the form of pages that the agent automatically uses in responses. - By separating Memory from agent instructions, it can be managed in one place and reused across multiple agents, ensuring more consistent outputs and simpler maintenance. ### Skills - Skills define what an agent can do, including specific capabilities, tools, and procedures. - Separating Skills from the system prompt makes it possible to expand agent functionality more flexibly, reuse skills across agents, and better scale and manage agent behavior. ### Agents - Subagents - the ability to use specialized subagents for more complex scenarios - Favorite agents - quick access to the most frequently used agents. --- # Release 1.2.3 **Version:** 1.2.3 **Release Date:** 5.3.2026 **Release Type:** Minor Release ## Summary Version 1.2.3 introduces a new onboarding wizard for a quicker start with the platform. This release also includes new data sources, improvements in workflow automation, and several enhancements in the areas of integrations and user-friendliness. ## New Features ### Onboarding - Added Onboarding Wizard for new users during registration. - After account creation, users have the option to immediately activate pre-configured agents. - The wizard also guides users through connecting the necessary tools and integrations required for these agents (e.g., Google Ads). ### User Management - Added the option to Invite user – inviting a new user to the organization. ### New Data Sources - SharePoint ### New Tools - Google Ads - Google Trends ## Improvements ### Workflow Automation - Added time triggers for launching workflows based on time. - Added Flow Control – Condition option for creating conditional logic in workflows. ### Agents - Added display of connected tool icons on the agent detail and in the agent list for better overview of used integrations. ### Recordings - Added the option to share recordings via a public URL. --- # Release 1.2.2 **Version:** 1.2.2 **Release Date:** 19.2.2026 **Release Type:** Minor / Stability Release ## Summary This release introduces new data sources, more flexible data import control, and improved data collection management. It increases data freshness and improves extraction quality across the platform. ## Improvements ### Data Sources Added support for new data sources: - Firecrawler - Jira - Confluence - Ability to change which data collection a data source writes its data to. - Data import control (scheduled and trigger-based). - Ability to set and adjust the data import frequency at any time. - Support for trigger-based updates that allow imports to start immediately based on an event or manual action, without waiting for a scheduled run. - Advanced content extraction. --- # Release 1.2.1 **Version:** 1.2.1 **Release Date:** 5.2.2025 **Release Type:** Patch Release ## Summary This patch focuses on technical fixes and stabilization of the backend without impacting existing functionality for users. ## Improvements ### General Enhancements - Stabilization of the backend and technical fixes without changes in user behavior. ### Azure AI Foundry - Integration with Azure AI Foundry is now fully functional. - Agents and workflows can run on the Azure AI Foundry backend without restrictions. ### Private Agents - Access to agents is controlled through **Access**: **Organization**, **Shared**, and **Private**. - **Private** = the agent is visible and available only to the author; ideal for testing, prototypes, and personal tools. - **Shared** = the agent is made available to selected users or teams; allows targeted sharing without opening it to the entire organization. - **Organization** = the agent is available to everyone in the organization; suitable for production agents and standardized use cases. ### Default Recording Settings in Organization - In the **Organization**, a default AI for transcription can be set and recording can be enabled/disabled. - This setting applies across the entire platform and unifies the behavior of working with recordings for the whole organization. --- # Release 1.2.0 **Version:** 1.2.0 **Release Date:** January 26, 2025 **Release Type:** Minor Release ## Summary This release brings improvements focused on faster and clearer work with the platform, better management of agents and connections, and a significant expansion of chat capabilities and handling of recordings. ## Enhancements ### User Interface and UX - A clearer user interface and navigation across the platform. - Improved consistency and readability of the user interface. ### Users and Permissions - Simplified management of users and their roles. - Fixes related to permissions and visibility across the system. ### Chat and File Handling - Inserting files into chat using Ctrl+V. - Enhanced feedback handling in chat — feedback (thumbs up / down) can be removed or changed by repeated clicking, without the need to delete the entire conversation. - Centralized feedback overview — all feedback related to conversations is now available in the agent detail in a separate section. ### Deletion and Error States - Improved logic for deleting agents and connections. - More precise and understandable error messages during login. ### Public Chat - The Public Chat Widget is now fully configurable: appearance adjustments, chat behavior settings, file handling, enabling or disabling selected features directly from administration. ### Connections - Improved management of connections: expanded with filters (All / LLM Models / Tools), clearer sharing, better handling of types and visibility. ### Agents - Enhanced overview of agents with key information (icon, name, model, number of conversations, feedback status, status). - Ability to configure the behavior and reasoning of AI agents. - Better management of access and sharing of agents (organizational, shared, private). - Clearer visibility of agents according to team and user permissions. - Added a new chat model GPT-5.2 available in agent configuration. ## New Features ### Workflows (beta) - Workflows are available in beta version. - Functionality is available upon consultation with the development team. ### Webhooks - New webhook functionality: simple editing, ability to call external URLs, sending payloads, ability to trigger workflows. ### Recordings - New Recordings section with an overview table and detailed view of recordings. - Ability to record and manage recordings including support for uploads via API. - Automatic AI transcription of recordings with an overview of status and resulting transcript. - Setting the default AI connection for transcriptions at the organizational level. --- # Release 1.1.12 **Version:** 1.1.12 **Release Date:** 3.12.2025 **Release Type:** Minor Release ## Summary This release brings significant improvements to chat, new features for agents, a completely new way to share conversations, and fixes in the areas of login, user permissions, and bug reporting. ## New Features ### Login - Linking profile with Google account: Users who originally registered using email and password can now additionally link their account with a Google account for faster login and easier identity management. ### Chat - Sharing via link: Users can now share conversations through a secure link. - Public sharing: Anyone with the link can view the conversation, even without an account in Siesta AI. - Internal sharing: Access is limited to logged-in users from the same organization. - Copy Message: Users can copy any message in the conversation with a single click. - Stop button in chat: A Stop button has been added to the chat, which immediately ends the ongoing action or response generation. - Improved start of a new conversation: The unnecessary popup has been removed, the new chat window opens immediately, and the cursor is automatically set to the input field. - Searching for agents when starting a new conversation: When creating a new conversation, it is now possible to directly search for an agent. ### Agents - Automatic creation of "General Agent": Every newly created organization now automatically receives a default agent. ## Improvements ### Chat - Enhanced feedback system: The modified and clarified rating of individual responses allows for faster and more convenient feedback. This also includes improvements to the Evolution section, which now displays the agent's development history and learning process more clearly. ### Localization - Missing or inconsistent translations have been fixed in various places within the application. ### Help - New unified bug reporting form: A central form for reporting bugs has been created, available here: https://siestalabs.atlassian.net/jira/software/c/form/1fe30bb7-3755-4f34-95ae-5d93f716546b. The form is also accessible in the Help section to make reporting faster and clearer. --- # User Manual In this section, you will find detailed manual for individual components of Siesta AI. We mainly focus on guides on how to connect services and data sources and how to use them in real user scenarios on the platform. Practical procedures are written step by step, similar to the example of connecting Gmail to Siesta AI. We will continuously add more guides for Connection and other parts of the platform. --- # Build With Siesta AI import DeveloperEntryGrid from '@site/src/components/DeveloperEntryGrid'; # Build With Siesta AI Integrate Siesta AI into your own products: call agents from your backend, build realtime voice and event sessions, or embed a guided web assistant. Each integration path has its own reference with authentication, request shapes, and response contracts. Pick the surface that matches the experience you want to build, then use the Public API v1 reference for exact request and response contracts before coding. ## Developer Entry Points --- # REST API Reference import OpenApiReference from '@site/src/components/OpenApiReference'; Browse Siesta AI REST API endpoints, parameters, request schemas, response schemas, and copyable request examples generated from the OpenAPI specification. This reference covers the authenticated `/api/v1` REST API surface. Webhook trigger URLs are documented separately in the product docs and should be treated as API-key-protected server-to-server entry points rather than anonymous public callbacks. --- # Getting Started The Siesta AI REST API lets your backend create, read, and update selected Siesta AI resources from your own systems. Use it for server-side integrations, admin workflows, reporting, and application features that need a stable HTTP contract. The REST API is inbound: your system calls Siesta AI. This is different from the [REST API connection](#doc-connections-rest-api), which is outbound, letting Siesta AI call another HTTP API. Common integrations: - Send a user question to an agent and store the returned `conversationId`. - Provision or list agents from an admin backend or customer portal. - Upload a temporary file and pass it to an agent as context. - Create or update tasks from a CRM, ticketing system, or workflow engine. - Start a realtime voice or streaming session with an agent. - Export audit log records for compliance or operational monitoring. ## Base URL Use the production API base URL: ```text https://api.siesta.ai ``` Endpoint paths in the reference include the `/api/v1` prefix. Combine the base URL with the path shown on each endpoint. ## First Request Start with a read-only endpoint, such as listing agents or tasks. Keep API credentials on your backend and send the required headers with each request. ```bash curl -X GET "https://api.siesta.ai/api/v1/Agent?Limit=10" \ -H "X-Api-Key: " \ -H "X-Org-Id: " ``` Use the [REST API Reference](#doc-developers-rest-api) for exact paths, query parameters, request bodies, response schemas, and examples generated from the current OpenAPI contract. ## Pagination And Errors List endpoints commonly accept pagination parameters such as `Offset` and `Limit` when they are present in the OpenAPI contract. Responses and error shapes are documented per endpoint in the reference. Handle these status families consistently: - `2xx`: request succeeded. - `4xx`: request was rejected because of input, authentication, authorization, rate limit, or missing resource. - `5xx`: Siesta AI could not complete the request. ## Authentication Every REST API request must include both headers: ```http X-Api-Key: X-Org-Id: ``` `X-Api-Key` identifies the calling integration. `X-Org-Id` scopes the request to one Siesta AI organization. A valid key without the matching organization context will still fail for resources outside that scope. Manage API keys in the Siesta AI app under **Organization → API Keys**. Use a separate key per integration and per environment, and delete keys that are no longer used. The interactive reference uses placeholders in code samples. Replace them in your backend or local test tool. Do not expose production API keys in frontend code. ### Trusted Execution Only Use API keys only from trusted server-side code: - backend route handlers; - scheduled jobs; - internal integration services; - local development tools. Do not place API keys in: - browser bundles or static sites; - mobile apps distributed to end users; - screenshots, tickets, or shared chat messages; - logs, analytics events, or client-side error reporting; - public repositories or checked-in config files. If you need browser-based behavior, send the request through your own backend and inject the Siesta AI credentials there. ### Key Storage And Rotation Store the API key in a secret manager or environment variable controlled by your backend deployment. Keep `X-Org-Id` alongside the integration configuration so each environment points to the correct organization. Recommended setup: 1. Keep production and non-production keys separate. 2. Use one integration identity per environment or app surface when possible. 3. Rotate keys by updating the backend secret first, then re-testing a read-only endpoint. 4. Remove unused keys when an integration is retired. ## Testing From The Docs The API reference includes an inline `Try request` section for quick testing. Values entered there are kept in the browser session and are not committed to the docs repository or placed in the page URL. Use that mode only for controlled local validation. If browser policy, company network rules, or CORS settings prevent the request from being sent from the docs domain, use the generated curl command instead. ## Common Status Codes - `400 Bad Request`: invalid input, unsupported parameter combination, or malformed payload. - `401 Unauthorized`: missing, expired, or invalid API key. - `403 Forbidden`: the key is valid but does not have access to the resource or organization. - `404 Not Found`: the resource does not exist or is not visible to the current organization. - `429 Too Many Requests`: the client is sending requests too quickly. - `500 Internal Server Error`: unexpected server-side failure. Show a fallback message and keep enough local context to retry safely. Review the response section for each endpoint in the [REST API Reference](#doc-developers-rest-api) for exact documented response shapes. ## Recommended Workflow 1. Read the endpoint in the reference. 2. Copy the curl sample and replace placeholders. 3. Test with a read-only request. 4. Generate typed helpers from the OpenAPI document if your integration is large. ## Security And Governance Apply the same governance to API integrations as to in-product use: - Restrict each integration to the minimum workflow it needs. - Prefer separate agents for different integration contexts. - Use connection governance for tools that read sensitive data or modify external systems. - Require approvals for actions that change business data. - Enable content safety and prompt shield settings for public or customer-facing integrations. - Monitor agent usage, tool executions, and audit logs after deployment. - Review token limits and cost controls before enabling high-volume automation. --- # Realtime API The Realtime API lets an external application create a short-lived Siesta AI agent session, open a WebSocket, and stream provider events through Siesta AI. Use it for voice-style experiences, live agent interfaces, public widgets, and clients that need to react to transcripts, tool execution, approval states, and persisted conversation events as they happen. See the [Public API v1 reference](https://api.siesta.ai/swagger/index.html?urls.primaryName=Public+API+v1) for the full schema. ## Endpoints | Method | Endpoint | Purpose | | --- | --- | --- | | `POST` | `/api/v1/Agent/{agentId}/realtime-session` | Create a one-time realtime session. | | `GET` | `/api/v1/Agent/{agentId}/realtime` | Open the WebSocket with `conversationId` and `sessionId`. | ## At a Glance | Topic | Detail | | --- | --- | | Server contract | Create sessions from a trusted server. `X-Api-Key` and `X-Org-Id` are used only for the backend session-creation call. | | Session lifecycle | The returned `sessionId` is a short-lived, one-time token, consumed when the socket connects. | | Realtime defaults | Sessions default to the `gpt-realtime-2` model and `pcm16` audio. | ## Live Example [cmd.siesta.ai](https://cmd.siesta.ai/) is a live use case built on top of Siesta AI. Use it as a reference for how an agent-powered, realtime workflow feels when the integration is already wired. ## What This API Does The API creates a realtime session for a specific Siesta AI agent conversation and proxies traffic between your client and the configured realtime provider. Siesta AI injects the agent system instructions, backend tools, optional client tools, audio settings, transcription settings, and conversation persistence. - **Realtime conversation**: stream audio and provider events over WebSocket after creating a one-time session. - **Backend tools**: tools configured on the Siesta AI agent are executed by Siesta AI and reported through custom events. - **Client tools**: your application can expose local functions to the model and execute them inside the client. - **Conversation persistence**: transcripts, assistant responses, tool status, and sub-agent status can be persisted back to the Siesta AI conversation. The realtime session token is short-lived and one-time use. Create the session immediately before opening the WebSocket. ## Quick Start Flow 1. Create a realtime session with `POST /api/v1/Agent/{agentId}/realtime-session`. 2. Connect to `wss://{api-host}{webSocketPath}`. 3. Send standard realtime provider client events. 4. Route incoming messages by top-level `type`. 5. Execute declared client tools locally. 6. For backend tool approvals, send `approval.approve` or `approval.reject`. 7. If the session expires, is consumed, or disconnects, create a new session. ## Authentication :::warning Keep the external API key server-side Create realtime sessions from your backend and return only `webSocketPath` to the browser. ::: The HTTP session creation endpoint is authenticated with external API headers: ```http X-Api-Key: X-Org-Id: ``` The WebSocket endpoint does not use `X-Api-Key`. It is authorized by the short-lived one-time `sessionId` embedded in the returned `webSocketPath`. Do not expose `X-Api-Key` in browser code. Browser clients should call a trusted backend, and that backend should create the realtime session. The browser should receive only the returned `webSocketPath`. ## Create Realtime Session **`POST /api/v1/Agent/{agentId}/realtime-session`** Returns `sessionId`, `conversationId`, expiry metadata, supported formats, and `webSocketPath`. ```http POST /api/v1/Agent/{agentId}/realtime-session Content-Type: application/json X-Api-Key: X-Org-Id: ``` If `conversationId` is omitted, Siesta AI creates a new conversation for the agent. If it is provided, it must belong to the same agent. ### Request Body | Property | Type | Default | Description | | --- | --- | --- | --- | | `conversationId` | `uuid \| null` | `null` | Existing conversation id. Omit to create a new conversation. | | `inputAudioFormat` | `string` | `pcm16` | Requested input audio format. | | `outputAudioFormat` | `string` | `pcm16` | Requested output audio format. | | `voice` | `string` | `alloy` | Provider voice used for output audio. | | `additionalInstructions` | `string \| null` | `null` | Extra instructions appended after the agent system message for this session. | | `clientTools` | `array` | `[]` | Tools executed by your client, not by Siesta AI. | ### Example Request ```http POST /api/v1/Agent/3f67ef24-3f96-4c20-a3b3-5fd0abef15a1/realtime-session HTTP/1.1 Host: api.siesta.ai Content-Type: application/json X-Api-Key: YOUR_EXTERNAL_API_KEY X-Org-Id: 4bdaed95-19f8-47c2-bbf0-8a476cf0a527 { "inputAudioFormat": "pcm16", "outputAudioFormat": "pcm16", "voice": "alloy", "additionalInstructions": "Keep answers short and ask one question at a time.", "clientTools": [ { "name": "open_booking_calendar", "description": "Open the booking calendar for a requested date.", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "Date in YYYY-MM-DD format." } }, "required": ["date"] } } ] } ``` ### Response Body | Property | Type | Description | | --- | --- | --- | | `sessionId` | `string` | One-time token used to connect to the realtime WebSocket. | | `conversationId` | `uuid` | Conversation id used by this realtime session. | | `expiresAt` | `datetime` | UTC expiration time for opening the WebSocket. Default TTL is 60 seconds. | | `webSocketPath` | `string` | Relative WebSocket path to connect to. | | `supportedInputAudioFormats` | `string[]` | Input formats supported by the deployment. | | `supportedOutputAudioFormats` | `string[]` | Output formats supported by the deployment. | | `maxSessionSeconds` | `number` | Maximum realtime session duration returned to clients. Default: `1800`. | | `idleTimeoutSeconds` | `number` | Idle timeout returned to clients. Default: `60`. | | `providerModelName` | `string` | Provider realtime model name, usually `gpt-realtime-2`. | ```json { "sessionId": "15f3c5c7b61c4a16893621b3ec969962", "conversationId": "6ad53918-7055-4f10-bd81-b06f8fcfae2a", "expiresAt": "2026-06-09T12:00:45.1234567Z", "webSocketPath": "/api/v1/Agent/3f67ef24-3f96-4c20-a3b3-5fd0abef15a1/realtime?conversationId=6ad53918-7055-4f10-bd81-b06f8fcfae2a&sessionId=15f3c5c7b61c4a16893621b3ec969962", "supportedInputAudioFormats": ["pcm16"], "supportedOutputAudioFormats": ["pcm16"], "maxSessionSeconds": 1800, "idleTimeoutSeconds": 60, "providerModelName": "gpt-realtime-2" } ``` The generated session is consumed when the WebSocket connects. In multi-instance deployments, use sticky routing or shared session storage. ## Realtime WebSocket **`GET /api/v1/Agent/{agentId}/realtime?conversationId={conversationId}&sessionId={sessionId}`** Upgrade to WebSocket on the same API host using the returned one-time session token. Connect to the returned `webSocketPath` on the same API host: ```text wss://{api-host}{webSocketPath} ``` The path has this shape: ```http GET /api/v1/Agent/{agentId}/realtime?conversationId={conversationId}&sessionId={sessionId} ``` After the socket is accepted, Siesta AI connects to the provider, sends `session.update`, and starts bidirectional proxying. Your client receives provider events and Siesta AI custom events on the same socket. :::info Route incoming frames by `type` Raw provider events and Siesta AI custom events share the same socket, so keep event routing explicit. ::: ## Backend Session Configuration Clients do not send this configuration. Siesta AI sends it internally after connecting to the provider: ```json { "type": "session.update", "session": { "type": "realtime", "model": "gpt-realtime-2", "output_modalities": ["audio"], "instructions": "{agent system message}\n\n{additionalInstructions}", "audio": { "input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transcription": { "model": "gpt-realtime-whisper" }, "turn_detection": { "type": "semantic_vad" } }, "output": { "format": { "type": "audio/pcm", "rate": 24000 }, "voice": "alloy" } }, "tools": [ "{backend agent tools}", "{client tools from realtime-session request}" ], "tool_choice": "auto" } } ``` ## Client To Server Messages The backend forwards most client WebSocket messages to the provider unchanged. Use standard realtime provider client event shapes. | Message | Behavior | | --- | --- | | Standard realtime client events | Forwarded to provider unchanged. | | Binary frames | Forwarded to provider unchanged, subject to max frame size. | | `{ "type": "approval.approve", "callId": "..." }` | Consumed by Siesta AI if the call is waiting for approval. | | `{ "type": "approval.reject", "call_id": "..." }` | Consumed by Siesta AI if the call is waiting for approval. Both `callId` and `call_id` are accepted. | ## Incoming Events Your client receives two categories of messages: - raw provider events, - Siesta AI custom events. Route by the top-level `type` property. ### Raw Provider Events Provider messages are forwarded first and unchanged. Examples include: - `response.created` - `response.done` - `response.audio.delta` - `response.audio_transcript.done` - `response.output_audio_transcript.done` - `response.output_text.done` - `response.content.done` - `conversation.item.input_audio_transcription.completed` - `input_audio.transcript.done` - `response.function_call_arguments.done` - `error` Siesta AI listens to some provider events to persist conversation messages and execute backend tools, but the raw events still reach your client. ### Persistence Trigger Events | Provider event | Persisted role | Custom events | | --- | --- | --- | | `conversation.item.input_audio_transcription.completed` | User | `message.created` | | `input_audio.transcript.done` | User | `message.created` | | `response.audio_transcript.done` | Assistant | `response.id`, then `response.completed` | | `response.output_audio_transcript.done` | Assistant | `response.id`, then `response.completed` | | `response.output_text.done` | Assistant | `response.id`, then `response.completed` | | `response.content.done` | Assistant | `response.id`, then `response.completed` | ### Siesta AI Custom Event Envelope ```json { "type": "event.name", "data": { "property": "value" } } ``` ### Custom Event Reference | Event | Data | When it is sent | | --- | --- | --- | | `message.created` | `{ chatbotId, id, role, content, createdAt }` | User transcript was persisted as a conversation message. | | `response.id` | `{ chatbotId, id }` | Assistant transcript was persisted. | | `response.completed` | `{ chatbotId }` | Assistant response persistence completed. | | `response.function_invocation.start` | `{ id, callId, title, imageUrl, chatbotId, arguments, approvalRequired, functionName }` | Backend tool execution started or is waiting for approval. | | `response.function_invocation.done` | `{ id, callId, text, title, imageUrl, button, buttonLabel, buttonLink, chatbotId, status, executionTimeSeconds }` | Backend tool execution finished, failed, was rejected, or timed out. | | `approval.waiting` | `{ callId, messageId, timeoutSeconds }` | Backend tool requires user approval before execution. | | `approval.approved` | `{ callId, messageId }` | Approval was accepted and the backend is executing the tool. | | `approval.expired` | `{ callId, messageId }` | Approval timeout elapsed. | | `subagent.start` | `{ id, name, icon, iconColor, callId }` | Sub-agent invocation started. | | `subagent.done` | `{ chatbotId }` | Sub-agent invocation completed. | Tool execution status is serialized as a number by the current custom WebSocket serializer: | Status | Meaning | | --- | --- | | `0` | Pending | | `1` | Success | | `2` | Failed | | `3` | Pending approval | ## Client Tools Client tools are functions declared by your client during session creation. The model sees them as function tools, but Siesta AI does not execute or persist them. Your application must listen for tool calls, execute the local function, send the function output to the provider, and request the next response. ### Declaration ```json { "clientTools": [ { "name": "open_booking_calendar", "description": "Open the booking calendar for a requested date.", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "Date in YYYY-MM-DD format." }, "durationMinutes": { "type": "integer", "description": "Requested meeting duration in minutes." } }, "required": ["date"] } } ] } ``` ### Rules - `name` and `description` are required and cannot be empty. - Tool names are case-sensitive. - Client tool names must be unique. - Client tool names must not conflict with backend agent tool names. - `parameters` must be an object. If omitted, an empty object schema is used. - Client tool execution is not persisted by Siesta AI. - Client tools do not emit custom `response.function_invocation.*` events. ### Handling A Client Tool Call When the provider calls a client tool, your client receives a raw provider event: ```json { "type": "response.function_call_arguments.done", "call_id": "call_open_calendar_01", "name": "open_booking_calendar", "arguments": "{\"date\":\"2026-06-10\",\"durationMinutes\":30}" } ``` If `name` matches a tool you declared, execute it locally and send the function output: ```json { "type": "conversation.item.create", "item": { "type": "function_call_output", "call_id": "call_open_calendar_01", "output": "{\"status\":\"success\",\"result\":\"Calendar opened for 2026-06-10.\"}" } } ``` Then request the model to continue: ```json { "type": "response.create" } ``` If the function call is not your declared client tool, wait for Siesta AI custom backend-tool events instead. ## Approval Flow For Backend Tools Some backend tools may require user approval. The model calls the backend tool, Siesta AI persists a pending approval, and your client must ask the user to approve or reject it. 1. Client receives `response.function_invocation.start` with `approvalRequired: true`. 2. Client receives `approval.waiting` with `callId`, `messageId`, and `timeoutSeconds`. 3. User approves or rejects. 4. Client sends `approval.approve` or `approval.reject` with the same `callId`. 5. Approved tools emit `approval.approved` and `response.function_invocation.done`. 6. Timed-out approvals emit `approval.expired`. ```json { "type": "approval.waiting", "data": { "callId": "call_send_email_01", "messageId": "da3ba88e-22f5-49de-8421-e4f43834ba42", "timeoutSeconds": 300 } } ``` Approve: ```json { "type": "approval.approve", "callId": "call_send_email_01" } ``` Reject: ```json { "type": "approval.reject", "call_id": "call_send_email_01" } ``` Default approval timeout is 300 seconds. If approval expires, Siesta AI returns a timeout error result to the model. ## Audio And Transport | Setting | Default | Notes | | --- | --- | --- | | Input format | `pcm16` | Mapped to provider `audio/pcm` with sample rate `24000`. | | Output format | `pcm16` | Mapped to provider `audio/pcm` with sample rate `24000`. | | Voice | `alloy` | Passed to provider session configuration. | | Turn detection | `semantic_vad` | Configured by backend in `session.update`. | | Input transcription model | `gpt-realtime-whisper` | Configured by backend in `session.update`. | | Max WebSocket message size | `65536` bytes | Larger messages can close the target socket with `MessageTooBig`. | Siesta AI does not transcode client audio. Use provider-compatible realtime event payloads for the selected format. ## Implementation Example In production, create the session on a trusted backend so your external API key is not exposed in a browser. ```js const apiBaseUrl = "https://api.siesta.ai"; const agentId = "3f67ef24-3f96-4c20-a3b3-5fd0abef15a1"; async function createRealtimeSession() { const response = await fetch(`${apiBaseUrl}/api/v1/Agent/${agentId}/realtime-session`, { method: "POST", headers: { "Content-Type": "application/json", "X-Api-Key": "YOUR_EXTERNAL_API_KEY", "X-Org-Id": "4bdaed95-19f8-47c2-bbf0-8a476cf0a527" }, body: JSON.stringify({ inputAudioFormat: "pcm16", outputAudioFormat: "pcm16", voice: "alloy", clientTools: [ { name: "open_booking_calendar", description: "Open the booking calendar for a requested date.", parameters: { type: "object", properties: { date: { type: "string" } }, required: ["date"] } } ] }) }); if (!response.ok) { throw new Error(await response.text()); } return response.json(); } function openRealtimeSocket(session) { const wsUrl = new URL(session.webSocketPath, apiBaseUrl.replace(/^http/, "ws")); const socket = new WebSocket(wsUrl); socket.addEventListener("message", async event => { const message = JSON.parse(event.data); if (message.type === "response.function_call_arguments.done") { await maybeHandleClientTool(socket, message); return; } if (message.type === "approval.waiting") { showApprovalDialog(socket, message.data); return; } handleRealtimeEvent(message); }); return socket; } async function maybeHandleClientTool(socket, event) { if (event.name !== "open_booking_calendar") { return; } const args = JSON.parse(event.arguments || "{}"); const result = await openBookingCalendar(args.date); socket.send(JSON.stringify({ type: "conversation.item.create", item: { type: "function_call_output", call_id: event.call_id, output: JSON.stringify({ status: "success", result }) } })); socket.send(JSON.stringify({ type: "response.create" })); } function approve(socket, callId) { socket.send(JSON.stringify({ type: "approval.approve", callId })); } function reject(socket, callId) { socket.send(JSON.stringify({ type: "approval.reject", callId })); } const session = await createRealtimeSession(); const socket = openRealtimeSocket(session); ``` ## Sending Audio Or Text Use the provider realtime event format. Siesta AI forwards these events unchanged. ```json { "type": "input_audio_buffer.append", "audio": "BASE64_PCM16_AUDIO_CHUNK" } ``` ```json { "type": "input_audio_buffer.commit" } ``` ```json { "type": "response.create" } ``` ## Errors And Limits Realtime domain errors return HTTP 400 with this shape: ```json { "status": 400, "detail": "Realtime session has expired.", "errorCode": "RealtimeSessionExpired" } ``` ### Error Codes | Error code | Meaning | Client action | | --- | --- | --- | | `RealtimeNotEnabled` | Realtime is disabled for the deployment or access mode. | Disable realtime UI or contact the API owner. | | `RealtimeUnsupportedConnection` | The agent connection does not support realtime audio or is disabled by governance. | Use an agent with a supported OpenAI connection. | | `RealtimeUnsupportedModel` | The selected agent model does not support realtime audio or does not match the configured provider model. | Use an agent configured with a realtime-capable model. | | `RealtimeAudioFormatUnsupported` | Requested input or output audio format is not supported. | Use a format returned by session creation, usually `pcm16`. | | `RealtimeSessionInvalid` | Missing, unknown, mismatched, or otherwise invalid session token. | Create a new realtime session and reconnect. | | `RealtimeSessionExpired` | Session token expired before WebSocket connection. | Create a new realtime session and connect immediately. | | `RealtimeSessionAlreadyUsed` | One-time session token was already consumed. | Create a new realtime session. Do not retry the same token. | ### Default Limits | Limit | Default | | --- | --- | | Session TTL before WebSocket connect | 60 seconds | | Max session duration | 1800 seconds | | Idle timeout | 60 seconds | | Approval timeout | 300 seconds | | Max WebSocket message size | 65536 bytes | | Provider connect timeout | 15 seconds | If the WebSocket is opened with the wrong `agentId`, the one-time session may already be consumed before the mismatch is reported. Create a new session instead of retrying the same token. ## Implementation Checklist - Store `apiBaseUrl`, `agentId`, and organization credentials in trusted server-side configuration. - Call `POST /api/v1/Agent/{agentId}/realtime-session` immediately before opening a WebSocket. - Build the WebSocket URL as `wss://{host}{webSocketPath}`. - Do not send `X-Api-Key` to the WebSocket. - Parse every incoming text frame as JSON and route by top-level `type`. - Handle raw provider audio and response events according to the provider realtime protocol. - Handle Siesta AI custom events with the `{ type, data }` envelope. - For backend tool events, update UI state but do not send function outputs yourself. - For declared client tools, listen for `response.function_call_arguments.done`, execute locally, send `conversation.item.create`, then send `response.create`. - For `approval.waiting`, show approval UI and send `approval.approve` or `approval.reject` with the same `callId`. - On `RealtimeSessionExpired` or `RealtimeSessionAlreadyUsed`, create a new session instead of retrying the old one. - Keep individual WebSocket messages under `65536` bytes unless your deployment config says otherwise. --- # MCP import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # MCP Connect Siesta AI to any MCP-compatible AI client (Claude, Cursor, VS Code, Antigravity, and others). Once connected, the client can manage your agents, skills and workflows, send messages, and read conversations directly from your Siesta AI organization. ## How to install Add one of the connection definitions below to your AI client's MCP configuration. Replace `[YOUR-API-KEY]` and `[YOUR-ORGANIZATION-KEY]` with the values from your Siesta AI organization. Recommended. No external dependencies, though a few clients may not support it yet. ```json "siesta": { "type": "http", "url": "https://api.siesta.ai/mcp", "headers": { "X-Api-Key": "[YOUR-API-KEY]", "X-Org-Id": "[YOUR-ORGANIZATION-KEY]" } } ``` Needs Node.js. Use only as a fallback when the client cannot connect over HTTP. ```json "siesta": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.siesta.ai/mcp", "--header", "X-Api-Key:[YOUR-API-KEY]", "--header", "X-Org-Id:[YOUR-ORGANIZATION-KEY]" ] } ``` :::tip Easiest way to install Every AI provider (Claude, Antigravity, and others) stores MCP servers differently and expects these definitions in its own JSON config. The fastest path is to copy the JSON above (with your API key and organization ID from Siesta AI), paste it into the client's chat, and ask the AI to install it. Then follow any instructions it gives, for example restarting the client to refresh the MCP tools. ::: ## OAuth installation :::note Coming soon OAuth-based installation is in progress. ::: ## Tools Once connected, the client can use the tools below. All operate within the organization identified by your API key and organization ID. ### Agents | Tool | Description | | --- | --- | | `list_agents` | List the agents (chatbots) in your organization. Use it to find an agent's ID before messaging or editing it. | | `get_agent` | Read an agent's full configuration: system message, model, connection, skills, sub-agents and tools. | | `create_agent` | Create a new agent from a name and system message, optionally attaching a model, skills, sub-agents and tools. | | `update_agent` | Update an existing agent. Only the fields you pass change; list fields replace the whole set. | ### Conversations | Tool | Description | | --- | --- | | `send_message` | Send a message to an agent and get its reply. Pass an `agentId` to start a new conversation or a `conversationId` to continue one. | | `list_conversations` | List existing conversations (newest first), with optional filtering by agent or title search and paging. | | `get_conversation` | Read the full message history of a conversation before resuming it. | ### Skills | Tool | Description | | --- | --- | | `list_skills` | List the skills (named instructions plus bound tool functions) available in your organization. | | `get_skill` | Read a skill's full detail: its instructions and bound functions. | | `create_skill` | Create a new skill from a name, instructions and optional bound functions. | | `update_skill` | Update an existing skill. Only the fields you pass change; passing functions replaces the whole set. | | `list_skill_functions` | List the tool functions that can be bound to a skill, returning the IDs to use when creating or updating one. | ### Workflows | Tool | Description | | --- | --- | | `list_workflows` | List the workflows in your organization. Use it to find a workflow's ID before reading or editing it. | | `get_workflow` | Read a workflow's full graph: nodes (with IDs, types and input mappings) and edges. | | `create_workflow` | Create a workflow from a full graph of nodes and edges in one call. | | `update_workflow` | Replace a workflow's graph with the full set of nodes and edges it should have. | | `describe_node_types` | Discover the workflow building blocks (node types, their inputs/outputs and selectable targets) before building a workflow. | | `list_workflow_functions` | Search the tool functions that can back a workflow tool node, filtered by provider or capability. | ### Discovery | Tool | Description | | --- | --- | | `list_connections` | List the connections (integrations) available as an agent's model provider or as a tool. | | `list_models` | List the LLM models available for an agent, optionally filtered by connection. | | `list_system_tools` | List the built-in system tools (for example web grounding and scraping) that can be enabled on an agent. | --- # Documentation MCP The Siesta AI documentation MCP server gives AI coding tools read-only access to the current public documentation. Clients can search for relevant pages and read a complete page or a specific section without downloading the entire documentation set. ## Endpoint ```text https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp ``` The server is public, does not require a Siesta AI account, and cannot modify Siesta AI data. Do not send passwords, API keys, personal data, or other secrets in documentation queries. ## Codex ```bash codex mcp add --url https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp siesta-docs ``` ## Claude Code Run this command in the macOS Terminal or your IDE's integrated terminal, not as a message inside a Claude chat: ```bash claude mcp add --transport http --scope user siesta-docs https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp ``` Verify the connection with `claude mcp get siesta-docs` or `/mcp` inside Claude Code. For a Claude Code cloud session, add the server to the repository's `.mcp.json` instead: ```json { "mcpServers": { "siesta-docs": { "type": "http", "url": "https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp" } } } ``` ## Claude web and desktop Open [Claude Connectors](https://claude.ai/customize/connectors), choose **Add custom connector**, and enter the endpoint above. The server is public, so leave OAuth fields empty. In Team and Enterprise organizations, an owner may need to add the connector first. ## Cursor Add this server to your Cursor MCP configuration: ```json { "mcpServers": { "siesta-docs": { "type": "http", "url": "https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp" } } } ``` ## VS Code Add the server to `.vscode/mcp.json` or your user MCP configuration: ```json { "servers": { "siesta-docs": { "type": "http", "url": "https://wonderful-cliff-086def303.3.azurestaticapps.net/api/mcp" } } } ``` ## Available capabilities - `search_docs` searches English or Czech documentation and returns concise source excerpts with canonical links. - `read_doc` returns a complete document or a section under a selected heading. - Documentation resources expose individual pages through stable `docs://` URIs. Search results always include their documentation URL. Use that URL to verify instructions before making production changes. ## Troubleshooting If a shell reports `claude: command not found`, install Claude Code or run the command on a machine where its CLI is available. If the client still cannot connect, verify that it supports Streamable HTTP MCP servers and that your network can access `wonderful-cliff-086def303.3.azurestaticapps.net` over HTTPS. Remove and re-add the server after changing its configuration. A temporary `503` response means the published documentation index is unavailable; retry after the next documentation deployment. --- # Connections import ConnectionCardGrid from '@site/src/components/ConnectionCardGrid'; # Connections Connections are the catalog where Siesta AI links to model providers, custom API endpoints, and business applications. Authorize a service once, then assign it to agents and workflows and control which functions can run automatically or with confirmation. Connections come in three families: - **LLMs** power agents with a model provider. - **Custom** connections bring your own endpoints through MCP or REST API. - **Applications** connect SaaS tools, Google and Microsoft apps, repositories, commerce, and knowledge sources. For how to add, govern, and set token limits on connections, see [Connections Management](#doc-connections-management). ## LLMs Model providers that power agents and workflows. ## Custom Bring your own endpoints and tools. ## Applications SaaS platforms, Google and Microsoft apps, repositories, commerce, and knowledge sources. --- # OpenAI

OpenAI

The OpenAI connection lets Siesta AI use OpenAI models (such as the GPT family) for chat, reasoning, and transcription. It is a model connection: once added, it becomes available as a model provider for agents, templates, and workflows. ## Overview Siesta AI uses the OpenAI connection to: - run agents and workflows on OpenAI chat and reasoning models, - generate responses grounded in your connected data collections, - optionally transcribe audio where a compatible model is configured. Model independence is a core principle of the platform, so an OpenAI connection can coexist with other providers (Azure AI Foundry, Gemini) and be assigned per agent. ## Requirements - An OpenAI account with API access. - An API key created in the OpenAI dashboard. - A billing method or active credits on the OpenAI side. ## 1. Create an API Key 1. Sign in to the OpenAI platform at [platform.openai.com](https://platform.openai.com). 2. Open **API keys** in your account settings. 3. Create a new secret key and copy it. OpenAI shows the key only once. Keep separate keys for different environments (for example development and production) so you can rotate or revoke them independently. ## 2. Add the Connection in Siesta AI 1. Open the **Connections** section. 2. Click **Add Connection**. 3. Search for and select **OpenAI**. 4. Fill in: - **Name**: a recognizable label, for example `OpenAI - PROD`. - **ApiKey**: paste the secret key from OpenAI. - **Access**: `Private` (visible only to you) or `Shared` (usable across the organization). 5. Save. Siesta AI validates the key and stores it encrypted. ## 3. Use OpenAI Models 1. Open an **Agent**, **Template**, or **Workflow**. 2. Set the **model provider** to **OpenAI**. 3. Choose the model you want to use. 4. Save the configuration. ## Security & Governance - The API key is stored encrypted and is never shown back in full. - Use `Shared` access only for keys the whole organization may use, and review who can reach them. - Token limits can be managed per model connection at organization, team, and user level. - Usage and cost are visible through [Analytics](/analytics) and the OpenAI dashboard. ## Technical Notes - **Implementation**: OpenAI is used as a model connection, not as a business function set. - **Authentication/scopes**: authentication uses the OpenAI API key. Access to specific models depends on your OpenAI account entitlements. - **Functions**: model invocation is handled through the model connection layer; connection-style read/write functions are not exposed from this page. - **Operational notes**: confirm model availability, rate limits, and billing before assigning the connection to production agents. ## Summary The OpenAI connection adds OpenAI models to Siesta AI as a selectable provider for agents, templates, and workflows. Setup is a single API key, and access, token limits, and cost stay under your control. --- # Azure AI Foundry

Azure AI Foundry

Azure AI Foundry is a platform in Azure for the development, deployment, and management of AI applications, agents, and models. Within Siesta AI, it serves as an enterprise backend for inference and agents with support for RBAC, regional restrictions, and audits. ## Overview Siesta AI from Azure AI Foundry: - calls deployed models (chat, reasoning, transcribe), - uses an OpenAI-compatible endpoint for inference, - respects Azure RBAC and customer security policies. ## Key Terms - **Foundry resource** – Azure resource of type **Azure AI Foundry** in a subscription and resource group. - **Foundry project** – a logical project within a Foundry resource (separating teams, applications, and environments). - **Project endpoint** – API endpoint for project capabilities (agents, evaluations, inference via Foundry API). - **Model deployment** – a specific deployment of a model (e.g., `gpt-5.2`, `gpt-5.2-chat`). - **API key** – a key for authenticating calls to the Foundry API. ## Requirements - An active Azure subscription. - At least **Contributor** permissions on the target resource group. - Registered resource provider **Microsoft.Foundry**. - Access to **ai.azure.com** (Microsoft Entra ID). ## Creating Azure AI Foundry ### 1) Foundry resource 1. Sign in to **Azure Portal**. 2. Create a new resource **Azure AI Foundry**. 3. Choose **Subscription**, **Resource Group**, **Region** (e.g., `westeurope`), and resource name (e.g., `aif-sai-pro`). The Foundry resource serves as a container for all projects. ### 2) Foundry project 1. Open **ai.azure.com**. 2. On the left, select **Management Center → Projects**. 3. Click on **New project**. 4. Select an existing Foundry resource and enter the project name. ![Creating a project in Management Center](/img/connections/azure-ai-foundry-management-center-new-project.png) ## Model Deployments ### Model deployments In the project, go to **Model catalog → Model deployments** and deploy available models. Examples of deployments: - `gpt-5.2` - `gpt-5.2-chat` - `gpt-4o-mini-transcribe` - `claude-opus-4-5` Each deployment has a **deployment name**, **model version**, **status**, and **retirement date**. ![List of model deployments](/img/connections/azure-ai-foundry-model-deployments.png) > ⚠️ Siesta AI works with the **deployment name**, not the model name. ### Model router Azure AI Foundry can also expose a `model-router` deployment. In Siesta AI, use the router deployment name the same way as a direct model deployment. The router then chooses an underlying model per request based on the configured routing mode and model subset. Use model router when agents or workflows mix simple requests with more complex reasoning, RAG, or tool orchestration. See [Azure AI Foundry Model Router](#doc-connections-azure-ai-foundry-model-router) for setup guidance, recommended routing profiles, observability, and data residency notes. ## Endpoints and API Keys ### Project endpoint (Foundry API) The project endpoint is used for project capabilities (agents, evaluations, and Foundry inference API). You can find it in the project details. **Endpoint format:** ``` https://.services.ai.azure.com/api/projects/ ``` ![Project endpoint in Azure Portal](/img/connections/azure-ai-foundry-project-endpoint-portal.png) ### Endpoints and keys in the project In **ai.azure.com**, open the project and the **Endpoints and keys** section: - **Microsoft Foundry project endpoint** - **API Key** for the project ![Endpoints and keys in the project](/img/connections/azure-ai-foundry-endpoints-keys.png) ### Keys and Endpoint (Azure Portal) In Azure Portal on the Foundry resource: - **Keys and Endpoint → Foundry** - **Key 1 / Key 2** for rotation - Basic endpoint resource ![Keys and Endpoint in Azure Portal](/img/connections/azure-ai-foundry-resource-keys-endpoint.png) ## Connecting Azure AI Foundry to Siesta AI ### 1) Adding integration 1. Sign in to **Siesta AI Admin**. 2. Open **Integrations**. 3. Click on **Add integration**. 4. Select **Azure AI Foundry**. ### 2) Filling in integration details Fill in: - **Name**: e.g., `Azure AI Foundry – PROD` - **Project endpoint (OpenAI-compatible)**: ``` https://.services.ai.azure.com/openai/v1/ ``` - **ApiKey**: use the **API key of the project** (from ai.azure.com) or the key from Azure Portal. - **Access**: **Private** (recommended) ![Integration details for Azure AI Foundry in Siesta AI](/img/connections/siesta-ai-azure-ai-foundry-form.png) ### 3) Verifying integration After saving the integration: - Siesta AI will perform a validation test. - The endpoint and key will be stored encrypted. - The integration is available for **agents**, **workflows**, and **data collections**. ## Using Models in Siesta AI 1. Open **Agent / Template / Workflow**. 2. Select **Model provider: Azure AI Foundry**. 3. Choose **deployment name** (e.g., `gpt-5.2-chat`). 4. Save the configuration. ## Security & Governance - Authentication via API key. - RBAC managed at the Azure level. - Option for **Private Endpoint + VNET**. - Audit logs in **Azure Activity Log**. - Monitoring via Foundry + **Azure Monitor**. ## Recommended Architecture - One Foundry resource per environment (DEV / STAGE / PROD). - Multiple projects for teams or customers. - Separate model deployments. - Key rotation via **Key Vault**. ## Increasing Quota If you need to increase the Azure AI Foundry quota, use this document: - [Increasing Azure AI Foundry Quota](#doc-connections-azure-ai-foundry-need-to-increase-ai-foundry-quota) ## Useful Links - Azure AI Foundry portal: [https://ai.azure.com](https://ai.azure.com) - Documentation: [https://learn.microsoft.com/azure/ai-studio/](https://learn.microsoft.com/azure/ai-studio/) - Model catalog: [https://ai.azure.com/model-catalog](https://ai.azure.com/model-catalog) - Azure RBAC: [https://learn.microsoft.com/azure/role-based-access-control/](https://learn.microsoft.com/azure/role-based-access-control/) ## Summary Azure AI Foundry functions as an enterprise AI backbone, while Siesta AI builds agents, workflows, data collections, and integrations with SaaS systems on top of it. The integration is auditable and fully under the customer's control in Azure. ## Technical Notes - **Implementation**: Azure AI Foundry is used as a model connection, not as a regular connection function set. - **Authentication/scopes**: the connection depends on Azure AI Foundry endpoint, deployment, and credential configuration. Access is governed by Azure project/resource permissions and the deployed model quotas. - **Functions**: model invocation is handled through the model connection layer; connection-style read/write business functions are not exposed from this page. - **Operational notes**: verify deployment names, model availability, rate limits, and quota before assigning the connection to production agents. --- # Model Router

Azure AI Foundry Model Router

Azure AI Foundry model router is a Foundry model deployment that selects an underlying large language model for each request. In Siesta AI, use it like any other Azure AI Foundry deployment name: configure the Azure AI Foundry connection, choose the router deployment for an agent, template, or workflow, and govern usage through Siesta AI access, analytics, and token limits. This is useful when the workload is mixed. Simple prompts can run on faster and cheaper models, while complex reasoning, tool orchestration, or synthesis can be routed to stronger models without asking users to choose a model for every prompt. ## When To Use Model Router Use model router when: - agents handle both simple and complex requests, - customer support or internal helpdesk traffic has many short questions and occasional hard cases, - workflows include classification, summarization, RAG, or tool-calling steps, - admins want one deployment name instead of many per-agent model choices, - cost optimization matters, but quality must stay reliable for harder prompts. Use a direct model deployment instead when a workflow must always use exactly one approved model, needs model-specific parameters on every request, or has a strict compliance decision that cannot allow dynamic model selection. ## Deployment Setup 1. In Azure AI Foundry, deploy the `model-router` model. 2. Choose the deployment type based on data residency and throughput requirements. 3. Start with **Balanced** routing mode unless the workload is clearly cost-sensitive or quality-critical. 4. Optionally enable **Route to a subset of models** to limit the model pool. 5. In Siesta AI, select **Azure AI Foundry** as the model provider and use the router deployment name, for example `model-router`. ![Model router deployment settings in Azure AI Foundry](/img/connections/azure-ai-foundry-model-router-deployment.png) You do not need to deploy every supported underlying model separately for standard router usage. Microsoft documents Claude as a special case: Claude models must be deployed before they can be included in a router subset. Always check the current Microsoft supported-model list before finalizing a production subset. ## Routing Modes | Mode | Use when | Operating guidance | | --- | --- | --- | | Balanced | Most production agents and mixed workloads | Default starting point. Observe traffic before changing it. | | Quality | Critical outputs, complex reasoning, legal or high-risk review, difficult RAG synthesis | Expect higher cost. Use for agents where answer quality matters more than savings. | | Cost | High-volume classification, triage, simple Q&A, drafts, or batch-like work | Use only where a small quality tradeoff is acceptable. Monitor negative feedback. | Changes to routing mode or model subset can take a few minutes to take effect in Azure AI Foundry. ## Model Subsets A model subset is the safest way to make router behavior match customer policy. Treat it as a compliance and operating boundary: - include only models approved by the customer or security team, - keep at least two models in the subset so failover and routing still have value, - exclude preview or partner models unless the customer explicitly accepts them, - raise the context-window floor by selecting only models that can handle the expected prompt size, - review the subset when Microsoft adds new supported models. New models should not be assumed approved just because the router supports them. Add them intentionally after security, quality, and cost review. ## Recommended Profiles For enterprise customers, create separate router deployments instead of one deployment with unclear purpose: | Deployment | Routing mode | Typical subset | Use case | | --- | --- | --- | --- | | `router-balanced` | Balanced | Approved general-purpose and reasoning models | Default agents, internal assistants, mixed chat | | `router-quality` | Quality | Stronger reasoning and synthesis models | Legal, finance, executive, or complex RAG work | | `router-cost` | Cost | Smaller approved models | Triage, classification, simple Q&A, high-volume workflows | In Siesta AI, assign the profile that matches the agent or workflow. This keeps the user experience simple while preserving admin control. ## Data Residency The deployment type matters more than the router name: - **Global Standard** can process inference traffic in any Azure region where the selected model is available. Use it when the customer accepts global processing and wants broad availability and higher default quota. - **Data Zone Standard** processes prompts and responses only inside the Microsoft-defined data zone, such as the EU or US data zone. Use it when the customer needs zone-level residency. - **Regional Standard** processes in the deployment region where supported. Use it for stricter regional requirements, with the tradeoff that model availability and quotas can be narrower. Data stored at rest remains in the customer's designated Azure geography according to Microsoft Foundry data-residency commitments. Prompts and completions for Models sold by Azure are not available to OpenAI or other model providers and are not used to train foundation models without the customer's permission or instruction. For EU customers that ask whether data can go to the United States, do not answer from the router mode alone. Check the Azure deployment type. If the deployment is Global Standard, inference processing can happen globally. If that is not acceptable, use an EU Data Zone deployment where the required router and model subset are supported. ## Observability Use three layers of evidence: - **Azure AI Foundry playground**: test prompts and inspect which underlying model was selected. - **API response**: the `model` field identifies the underlying model that handled the request. - **Azure Monitor and Azure Cost Management**: filter by the model router deployment and split metrics by underlying model where available. In Siesta AI, use Analytics Cost charts and token limits to track model-connection usage by agent, model connection, team, and user. For underlying router distribution, use Azure Monitor as the source of truth. ## Customer Care Guidance When recommending model router to customers, frame it as a model strategy: - users should choose the right agent, not the model for every prompt, - admins should approve a model subset once and let routing handle per-request selection, - start in Balanced mode, observe traffic, then split critical or high-volume workloads into Quality or Cost router deployments, - combine router usage with Siesta AI token limits, feedback review, and agent analytics, - document the deployment type so data residency questions have a clear answer. Avoid promising fixed savings. Savings depend on the workload mix, prompt length, tool usage, selected subset, and current Azure pricing. ## FAQ ### What does the router use to decide? Microsoft documents that model router analyzes the request in real time, including system message, user message, conversation history, tool definitions, task type, complexity, and routing mode. It then selects an eligible underlying model from the configured pool. ### Do all supported models need to be deployed? No. For standard router usage, Microsoft packages router as one deployment and invokes supported underlying models. Claude models are the documented exception and must be deployed before they can be included in routing. ### Can admins see which model was used? Yes. The Foundry playground and API response expose the selected underlying model. Azure Monitor can be used to inspect routing distribution and performance by deployment and underlying model. ### What if the selected model is unexpected? Review the routing mode and model subset. If the customer does not approve a model, remove it from the subset or enforce approved models through Azure Policy. If a workload needs one exact model, use a direct deployment instead of model router. ### How should token limits be configured? Set Siesta AI token limits on the model connection that points to the router deployment. Treat the router as one shared model connection for budget enforcement, then use Azure Cost Management for deeper underlying-model cost analysis. ### What can cause high latency? Latency can come from router overhead, the selected underlying model, long prompts, tool calls, RAG retrieval, or regional capacity. For simple high-volume workloads, test Cost mode. For predictable high-throughput requirements, review provisioned deployment options in Azure. ### What can cause quota errors? Router deployments still use Azure quota and rate limits. If requests are throttled, increase quota, reduce concurrency, retry with backoff, or split traffic across reviewed deployments where the Azure architecture allows it. ## Useful Links - Microsoft model router guide: [Use model router for Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/model-router) - Microsoft concept guide: [Model router for Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/model-router) - Microsoft routing details: [How model router works](https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/model-router-how-it-works) - Microsoft deployment types: [Deployment types for Microsoft Foundry Models](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/deployment-types) - Microsoft data privacy: [Data, privacy, and security for Models sold by Azure](https://learn.microsoft.com/en-us/azure/foundry/responsible-ai/openai/data-privacy) --- # Increase of Azure AI Foundry Quota

Increase of Azure AI Foundry Quota

If you need to increase your Azure AI Foundry quota, use this document, which summarizes the necessary information and links to the [quota increase request form](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR4xPXO648sJKt4GoXAed-0pUQURHRUtCM1JTOUtOSjI3Qk4wSVNSSUNNNyQlQCN0PWcu) and the [documentation on models and regions](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure?view=foundry-classic&tabs=global-standard-aoai%2Cglobal-standard&pivots=azure-openai#model-summary-table-and-region-availability). ## Why an Increase is Needed Your AI agents run (or will run) directly in your Azure AI Foundry environment, so all AI workloads are subject to the limits of your Azure subscription (TPM/RPM). Default quotas are mainly set for testing and PoC. In production deployment, especially during document ingestion and embedding generation, these limits often represent a bottleneck and significantly slow down processing. Increasing the quota will allow for: - faster document ingestion and re-indexing, - higher throughput for embedding generation, - stable performance under concurrent user load, - lower latency and less throttling, - production scale and reliability. **Important:** Increasing the quota does not change the price. It only increases throughput. Billing remains strictly based on consumed tokens — the price per token is the same. This is a standard Azure process for production AI deployment. We will provide you with pre-filled parameters and a justification template to make the request quick and easy. ## Data for Quota Increase Request | # | Field | Value / Note | | --- | --- | --- | | 1 | Name (Authorized Representative of the Applicant) | [CLIENT] | | 2 | Surname | [CLIENT] | | 3 | Company Email (on company domain) | [CLIENT] | | 4 | Company Name | [CLIENT] | | 5 | Company Address | [CLIENT] | | 6 | City | [CLIENT] | | 7 | ZIP Code | [CLIENT] | | 8 | Country | [CLIENT] | | 9 | Subscription ID | [CLIENT] or [SIESTA.AI], if we have access to your Azure subscription | | 10 | Justification (EXAMPLE) | Below | | 11 | Model Type | Azure OpenAI | | 12 | Model Deployment Quota | Model Deployment (PTU/RPM/TPM) | | 13 | (Azure OpenAI) Quota Request Type | Global Standard | | 14 | Global Standard Region | East US2 or Sweden Central | | 15 | (Azure OpenAI) Global Standard Model | text-embedding-3-large | | 16 | Quota | 10000 | ## Example Justification We are building and operating a production AI SaaS platform focused on enterprise automation (document analysis, RAG agents, email triage, CRM integration, and automating internal processes for B2B clients). We are currently running in pilot and production deployments across industries (manufacturing, real estate, insurance, enterprise services). Typical workloads include: - high-frequency chat and API inference, - large pipelines for document ingestion and vectorization (PDF, DOCX, web crawling), - contextually demanding prompts with multi-step reasoning, - concurrent use by multiple enterprise users and teams. Current quotas are already a bottleneck during peak load and testing. With the expansion of onboarding new customers and the introduction of additional agents and integrations (HubSpot, Gmail, Google Drive, Azure Storage, internal CRM), we expect a significant increase in token throughput. We need the quota increase to: - maintain stable latency during concurrent enterprise operations, - support batch processing of documents and continuous ingestion pipelines, - ensure production reliability and SLA, - eliminate throttling during load spikes from real business workflows. This quota increase is critical for upcoming production deployments and commercial rollouts. Without higher capacity, our ability to scale customers and ensure consistent service quality will be limited. We are committed to responsible usage, cost monitoring, and effective optimization of prompts and tokens in accordance with Azure OpenAI best practices. --- # Gemini

Gemini

The Gemini connection lets Siesta AI use Google's Gemini models for chat and reasoning. Like other model providers, it becomes available for agents, templates, and workflows once added. ## Overview Siesta AI uses the Gemini connection to: - run agents and workflows on Gemini models, - generate responses grounded in your connected data collections, - provide an alternative or complement to other model providers. Because the platform is model-independent, a Gemini connection can be assigned per agent and can coexist with OpenAI and Azure AI Foundry. ## Requirements - A Google account with access to Google AI Studio. - A Gemini API key. - Any usage or billing setup required on the Google side. ## 1. Create an API Key 1. Sign in to Google AI Studio at [aistudio.google.com](https://aistudio.google.com). 2. Open **API keys** and create a new key. 3. Copy the key and store it securely. Use separate keys for development and production so they can be rotated or revoked independently. ## 2. Add the Connection in Siesta AI 1. Open the **Connections** section. 2. Click **Add Connection**. 3. Search for and select **Gemini**. 4. Fill in: - **Name**: a recognizable label, for example `Gemini - PROD`. - **ApiKey**: paste the API key from Google AI Studio. - **Access**: `Private` (visible only to you) or `Shared` (usable across the organization). 5. Save. Siesta AI validates the key and stores it encrypted. ## 3. Use Gemini Models 1. Open an **Agent**, **Template**, or **Workflow**. 2. Set the **model provider** to **Gemini**. 3. Choose the model you want to use. 4. Save the configuration. ## Security & Governance - The API key is stored encrypted and is never shown back in full. - Use `Shared` access only for keys the whole organization may use, and review who can reach them. - Token limits can be managed per model connection at organization, team, and user level. - Usage and cost are visible through [Analytics](/analytics) and the Google AI Studio console. ## Technical Notes - **Implementation**: Gemini is used as a model connection, not as a business function set. - **Authentication/scopes**: authentication uses the Gemini API key. Access to specific models depends on your Google account entitlements. - **Functions**: model invocation is handled through the model connection layer; connection-style read/write functions are not exposed from this page. - **Operational notes**: confirm model availability, rate limits, and quotas before assigning the connection to production agents. ## Summary The Gemini connection adds Google's Gemini models to Siesta AI as a selectable provider for agents, templates, and workflows. Setup is a single API key, and access, token limits, and cost stay under your control. --- # Custom LLM

Custom LLM

The Custom LLM connection lets Siesta AI use a self-hosted or third-party model endpoint that implements the OpenAI-compatible Chat Completions API. Models are declared for each connection instead of being selected from Siesta AI's shared model catalog. Custom LLM is a model connection for agents. It is not a tool connection, REST function definition, or data source. ## Requirements - An absolute OpenAI-compatible base URL that includes the API version path, for example `https://llm.example.com/v1`. - Support for Chat Completions at the configured endpoint. - An API key. Siesta AI requires one for Custom LLM inference even if the endpoint can otherwise accept unauthenticated requests. - Network access from the Siesta AI backend to the endpoint. - At least one model declared on the connection before an agent can select it. To load the endpoint's advertised models automatically, it must also support the OpenAI-compatible models endpoint at `/models`, for example `https://llm.example.com/v1/models`. ## Add the Connection 1. Open **Connections**. 2. Click **Add Connection** and select **Custom LLM**. 3. Enter a recognizable **Name**, for example `Private LLM - PROD`. 4. Enter the OpenAI-compatible **Base URL**, including `/v1` when required by the provider. 5. Enter the **ApiKey** and choose the appropriate private or shared access policy. 6. Add and review at least one model definition, then save the connection. 7. Open an agent and select the Custom LLM connection and one of its declared models. :::warning Current app availability The backend supports model discovery and per-connection model definitions, but some current Siesta AI App versions do not yet show the model controls in the connection form. If the **Models** section is not available in your deployment, the visible form cannot complete a usable Custom LLM setup. Contact your Siesta AI administrator before using the connection in production. ::: ## Declare Models Use **Load models** where the control is available to read model IDs from `/models`. A model whose name matches the Siesta AI catalog receives best-effort capability defaults. These values are editable hints, not a compatibility guarantee. An unknown model can still be declared manually. | Field | How Siesta AI uses it | Recommendation | | --- | --- | --- | | **Name** | Sends this exact model identifier with Chat Completions requests and makes it selectable by agents. | Copy the ID returned by the endpoint. Names must be non-blank and unique within the connection, ignoring letter case. | | **Context Window** | Defines the context size used by automatic conversation compaction. | Enter the provider's documented token limit. `0` means unknown and disables automatic compaction. | | **Supports Reasoning** | Enables best-effort reasoning options and recovery of reasoning content for the declared model. | Enable only when the model and gateway have been tested with the expected reasoning behavior. | | **Function Invocation** | Declares that the model supports function or tool invocation. | Disable it for models that cannot reliably produce compatible tool calls, and verify agent tools in a pilot. | Do not infer capabilities from a model name alone. Gateways can expose the same model ID with different context limits or feature support. When editing a connection, model names remain scoped to that connection. Siesta AI blocks removal of a declared model while one or more agents still use it; reassign those agents first. ## Verify the Connection Before production use: 1. Confirm that model discovery returns the expected model IDs, or enter the exact ID manually. 2. Create a test agent with the Custom LLM connection and declared model. 3. Run a short chat without tools. 4. If enabled, test reasoning and function invocation separately. 5. Test a conversation that approaches the configured context window and verify the expected compaction behavior. 6. Review provider-side logs, latency, rate limits, and error responses. Successful model discovery proves only that the models endpoint is reachable. It does not guarantee that Chat Completions, reasoning, tools, or the configured context window work correctly. ## Security and Operations - Siesta AI stores the API key through its backend secret store and does not treat it as a regular connection field. - Use a narrowly scoped key and separate credentials for development, staging, and production. - Use shared access only when the endpoint and credential are approved for the intended teams. - Restrict network access to trusted Siesta AI backend egress where the provider supports allowlisting. - Monitor endpoint availability, rate limits, latency, token usage, and provider cost independently of Siesta AI. - Rotate a compromised or expired key at the provider and update the connection before resuming agent use. ## Troubleshooting | Symptom | Likely cause | What to check | | --- | --- | --- | | Base URL is rejected | The value is not an absolute URL or points to the wrong API root. | Use an `https://` URL and include the provider's OpenAI-compatible version path, commonly `/v1`. | | Models cannot be loaded | `/models` is unavailable, blocked, or requires different authentication. | Test backend network access, TLS, the API key, and the provider's models endpoint. You can declare a known model ID manually where model controls are available. | | The agent reports that the model does not exist | The declared name differs from the ID accepted by the endpoint. | Copy the exact model ID, including punctuation and version suffixes. | | Chat starts but tool calls fail | The gateway or model does not implement compatible function invocation. | Disable **Function Invocation** or fix the provider's Chat Completions tool-call support. | | Reasoning is missing or malformed | Reasoning fields are not standardized across compatible gateways. | Disable **Supports Reasoning** or confirm the gateway's behavior with a pilot request. | | Long conversations fail unexpectedly | The declared context window is higher than the endpoint's real limit, or it is `0`. | Enter the documented limit and retest compaction before production use. | | A model cannot be removed | An agent still references it. | Reassign every affected agent to another model, then update the connection. | ## Technical Notes - Custom LLM uses the OpenAI-compatible **Chat Completions API**, not the OpenAI Responses API. - Model discovery uses the supplied base URL and can use the supplied API key. Model invocation requires both, and discovery can fail independently of chat. - Reasoning support is best-effort because compatible gateways do not expose it consistently. - Siesta AI does not confirm image generation, transcription, vision, or other OpenAI API features for Custom LLM connections. - Custom LLM has no catalog models of its own; every usable model is declared on the individual connection. ## Summary Custom LLM connects Siesta AI agents to an OpenAI-compatible model endpoint that you operate or choose. Configure the versioned base URL and API key, declare and test each model's capabilities, and treat discovery defaults as hints rather than proof of compatibility. --- # MCP

MCP

The MCP connection lets you connect any Model Context Protocol (MCP) server to Siesta AI. An MCP server exposes a set of tools (functions) over a standard protocol, and Siesta AI can call those tools from agents and workflows without a dedicated native connection. Use MCP when a system already ships an MCP server, or when you want to expose your own tools to agents through a single standard interface. For plain HTTP endpoints without MCP, use the [Rest API](#doc-connections-rest-api) connection instead. ## Overview Through an MCP connection, Siesta AI: - discovers the tools published by the MCP server, - calls those tools with arguments provided by the agent, - returns the results into the conversation or workflow. ## Requirements - A reachable MCP server endpoint (URL). - Any authentication the server requires (for example an API key or bearer token). - Knowledge of which tools the server exposes and their write behavior. ## 1. Add the Connection in Siesta AI 1. Open the **Connections** section. 2. Click **Add Connection**. 3. Search for and select **MCP**. 4. Fill in: - **Name**: a recognizable label for the server. - **Server URL**: the endpoint of the MCP server. - **Authentication**: the credential the server requires, if any. - **Access**: `Private` (visible only to you) or `Shared` (usable across the organization). 5. Save. Siesta AI connects to the server and loads the available tools. ## 2. Review and Govern Tools After connecting, review the tools the server exposes: - Confirm what each tool does and whether it reads or writes. - Put write-capable tools into confirmation mode where supported. - Assign the connection only to agents and workflows that need it. ## 3. Use MCP Tools 1. Open an **Agent** or **Workflow**. 2. Attach the **MCP** connection. 3. The agent can now call the server's tools during interactions or automatically in the background. ## Security & Governance - Treat MCP tool schemas, headers, and write behavior as production contracts. - Prefer `Private` access for servers with sensitive scope, and review shared access. - Function governance uses the strictest effective setting: enabled, enabled with confirmation, or disabled. - Tool executions record function status and approval state for audit. ## Technical Notes - **Implementation**: MCP tools are defined by the connected server rather than a fixed connection module. - **Authentication/scopes**: depends on the MCP server (API key, bearer token, or other headers). Limit credentials to what the tools actually need. - **Functions**: each tool published by the server maps to a callable function with its own parameters and write behavior. - **Write behavior**: tools that change external systems should require confirmation and narrow allowlists for production agents. ## Summary The MCP connection brings any Model Context Protocol server into Siesta AI as a set of callable tools for agents and workflows. It is the standard way to expose custom or third-party tools through one interface, with the same access, confirmation, and audit controls as other connections. --- # Rest API

Rest API

The Rest API connection allows you to connect any HTTP API to Siesta AI without the need for a special native connection. Within a single connection, you can define multiple functions (endpoints) and set parameters for each function. This page describes outbound integration: Siesta AI calls an external HTTP API. If you want your own system to call Siesta AI, use the [REST API](#doc-developers-rest-api-getting-started). ## 1. Adding a New Rest API Connection 1. Open the **Connections** section. 2. Click on **Add Connection**. 3. In the dialog, select the **Rest API** tile. ## 2. Basic Configuration of the Connection After selecting Rest API, fill in: - **Name**: the name of the integration in Siesta AI. - **Base URL**: the base URL of the API (e.g., `https://api.example.com`). - **Visibility**: determines the availability of the connection. - `Private` = the connection is visible only to you. - `Shared` = the connection can be used by multiple users in the organization. ![Rest API connection form and function definition](/img/connections/rest-api-connection-form.png) ## 3. Functions (Endpoints) In the **Functions** section, you define specific API calls: - **Add function** adds another endpoint. - **Function name**: internal name of the function for use in agents/workflows. - **Description**: a brief description of what the endpoint does. - **Endpoint**: combines the HTTP method (`GET`, `POST`, `PUT`, `DELETE`, ...) and the endpoint path (e.g., `/example`), which is composed with the `Base URL`. Practically, this means that: - `Base URL`: `https://api.example.com` - `Endpoint`: `/orders` - resulting call: `https://api.example.com/orders` ## 4. Function Parameters In the **Parameters** section, you can add multiple parameters for each function via **Add parameter**. Configurable items: - **Key**: the name of the parameter. - **Value type**: data type (e.g., `String`). - **Position**: where the parameter is written (`Query`, `Path`, `Header`, or `Body` depending on the endpoint). - **Required**: whether the parameter is mandatory. - **Description**: documentation description of the parameter. - **Static value**: optional fixed value that is always sent. ![Defining function parameters in Rest API connection](/img/connections/rest-api-function-parameters.png) ## 5. Recommendations for Use - Use consistent naming of functions according to business actions (e.g., `getOrders`, `createTicket`). - Set mandatory parameters as `Required = true` to avoid invalid calls. - Store sensitive values securely and do not pass them as plain text in the prompt. - For shared connections (`Shared`), regularly check who has access to the integration. ## Summary The Rest API connection is a universal way to connect external systems to Siesta AI via HTTP endpoints. It allows you to combine multiple functions in one integration and manage the parameters of each call in detail. ## Technical Notes - **Implementation**: custom REST/API tools are defined from endpoint configuration rather than a fixed connection module. - **Authentication/scopes**: depends on the configured API: API key, bearer token, OAuth, basic auth, or custom headers. Limit credentials to the endpoints and environments the agent actually needs. - **Functions**: each exposed function maps to an HTTP method, path, parameters, headers, and optional request body defined by the admin/developer. - **Write behavior**: POST, PUT, PATCH, and DELETE endpoints can change external systems. Use confirmations, staging endpoints, and narrow allowlists for production agents. --- # Airtable

Airtable

The **Airtable** connection allows agents to read the structure of bases, retrieve records from tables, and create or modify records. It is suitable for lightweight CRM, content planning, internal records, or operational tables maintained in Airtable. ## When to Use It Use it when an agent needs to work with data stored in Airtable and exporting to a file is not sufficient. Typical scenarios include searching for a record, adding a new item, updating a status, or deleting an incorrectly created record. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Airtable**. 3. Log in or enter the required access according to the organization's configuration. 4. Verify that the account has access to the correct base and tables. 5. In the connection details, enable only the functions that the agent will actually use. ## What the Tool Can Do - list available bases, - load the base schema including tables and fields, - list records from a table, - create new records, - modify existing records, - delete records. ## Security and Confirmation Creating, modifying, and deleting records changes data in Airtable. For these actions, enable confirmation if the agent is working with a production table, customer data, or operational records. ## Example Use > Find all new leads from this week in the Airtable Leads table and prepare a suggestion for which I should contact first. Do not modify anything without confirmation. Verify the result directly in Airtable, and any execution can be found in **Run Tools**. ## Technical Notes - **Implementation**: The connection exposes Airtable table and record operations. - **Authentication/scopes**: use an Airtable personal access token or OAuth credential with access to the selected bases. Record reads need data read permission; create, update, delete, table creation, and base creation require write/schema permissions on the relevant workspace or base. - **Functions**: list bases, inspect base schema, list records, create records, update records, delete records, create tables, and create bases. - **Write behavior**: record, table, and base changes modify Airtable directly, so production agents should use confirmations for create/update/delete actions. --- # Azure (Coming Soon)

Azure (Coming Soon)

Connecting Siesta AI with the Azure environment via service principal. ## Setup 1. In **Connections**, click **Add Connection** and select **Azure**. 2. Fill in **Tenant ID**, **Client ID**, **Client Secret**, and optionally **Subscription ID**. 3. Choose **Shared** or **Private** access and save. ## Usage - In workflows, you can read or trigger actions on Azure resources available in Connections (e.g., list resource groups, initiate deployment). - Store passwords in a secure vault and rotate the secret key regularly. ## Security - Limit the service principal's roles to the bare minimum necessary. - Monitor sign-ins and activity logs in Azure AD. ## Technical Notes - **Implementation**: The connection provides Azure operational lookup functions. - **Authentication/scopes**: uses Azure credentials that can request Azure Resource Manager tokens for the configured tenant/subscription. The connected identity must have access to the target resource group, resource, or Application Insights resource. - **Functions**: read current-month resource costs by resource group or resource and inspect Application Insights error counts and recent errors. - **Write behavior**: the current Azure Portal tool functions are read-only. Use least-privilege Reader/Monitoring Reader style roles unless a separate integration needs broader access. --- # Azure DevOps

Azure DevOps

The **Azure DevOps** connection gives agents controlled access to Azure DevOps projects, repositories, branches, files, diffs, and pull requests. Use it when an agent should inspect code, prepare documentation or release changes, open a branch for a proposed update, or help with pull-request workflow inside Azure DevOps. ## When to Use It Use Azure DevOps when an agent needs to: - search code across a project or repository, - list projects, repositories, branches, or pull requests, - read repository files or file segments, - compare two branches before documenting or reviewing a change, - create a branch, commit a file change, or open a pull request. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Azure DevOps**. 3. Create or use a **Personal Access Token (PAT)** in Azure DevOps with at least repository read access. 4. Enter the Azure DevOps **Organization URL** such as `https://dev.azure.com/your-org`. 5. Save the connection and assign it only to agents or workflows that should access repository content. If the agent must write to repositories, use a PAT with the minimum Git write scope required for the target project. ## What the Tool Can Do Read and inspection operations: - search code with Azure DevOps code-search syntax, - list projects and repositories, - list repository branches, - list pull requests by repository or by project, - inspect pull request details, commits, and reviewers, - read a file or a line segment from a branch, - list files and folders in a repository path, - compare branch diffs. Write-capable operations: - create a branch, - create, update, or delete repository files on a non-protected branch, - commit multiple file changes in one commit, - create or update a pull request. ## Search and File Reading The code search operation supports normal search text together with Azure DevOps-style filters such as: - `proj:` - `repo:` - `path:` - `file:` - `ext:` - `class:` - `def:` - `comment:` Use file reads when the agent should quote or summarize a precise source file. Use file-segment reads when the file is large and the agent only needs a bounded part of it around a matching anchor line. Use repository-path listing before a read when the agent is unsure about the exact folder or file name. Use diff inspection before documentation work so release notes or change summaries are based on the real branch delta rather than on a guessed commit range. ## Branch and Pull Request Workflow The safest write pattern is: 1. List repositories and branches. 2. Create or ensure a dedicated working branch. 3. Read the target file or diff first. 4. Upsert one file or commit several related file changes together. 5. Create a pull request back to `main`, `master`, or the team’s integration branch. This keeps agent-authored changes reviewable and avoids direct edits to protected branches. ## Protected Branches and Confirmation The released tool surface blocks direct commits to protected branch names such as: - `main` - `master` - `release/*` Even when the PAT can write, keep **Allowed with confirmation** on write-capable Azure DevOps functions: - create branch, - upsert file, - delete file, - commit multiple files, - create or update pull request. Ask the agent to show the intended diff, file content, or pull-request description before confirming a write. Read and inspection operations can usually stay enabled without confirmation if the repository audience is already approved for that codebase. ## Example Usage > Compare `main` and `feature/release-notes`, summarize the changed files, then draft a pull request description. > Read `/docs/api.md` from the `dev` branch and show only the section around `Authentication`. ## Technical Notes - **Implementation**: the connection exposes Azure DevOps repository, file, branch, diff, and pull-request operations. - **Authentication/scopes**: uses Azure DevOps PAT-based access against the configured organization URL. Project and repository permissions determine what the agent can read or modify. - **Functions**: code search, project/repository listing, branch listing, pull-request inspection, file reads, file listing, branch creation, file changes, multi-file commit, pull-request creation/update, and branch diff. - **Write behavior**: repository writes are real Git operations. Default to confirmation, prefer short-lived working branches, and treat pull requests as the normal merge path. --- # Azure Storage Account

Azure Storage Account

The Azure Storage Account serves as a central data repository for blob objects, files, queues, and tables. Applications access this storage using a **Connection String**, which contains all the necessary authentication and configuration information in a single string. This mechanism allows for quick integration without the need for manual management of individual connection parameters. ## Procedure for Creating a Data Source in the Application ### Creating a Data Source Collection In the application administration: 1. Open the **Data Sources** section. 2. Select **Create Data Source Collection**. 3. Fill in: - **Name**: for example, Azure Storage Blob. - **Description**: optional (recommended for documenting the purpose). Confirm by clicking **Create**. ![Creating a Data Source Collection](/img/connections/azure-storage-collection-create.png) ### Adding an Azure Storage Account After creating the collection: 1. Select the resource type **Azure Storage account**. 2. Fill in: - **Name**: any identifier (e.g., Production Storage). - **Connection String**: to be inserted in the next step. 3. Set access: - **Private** – recommended for production environments. - **Shared** – only if necessary. Proceed by clicking **Continue**. ![Setting Up Azure Storage Account](/img/connections/azure-storage-account-form.png) ## Obtaining the Connection String in the Azure Portal You can obtain the Connection String directly from the Azure Portal from the Storage Account configuration. Procedure: 1. Log in to the **Azure Portal**. 2. Open the desired **Storage Account**. 3. In the left menu, select **Security + networking → Access keys**. 4. Two active key sets will be displayed: - `key1` - `key2` 5. In the **Connection string** field, click **Show**. 6. Copy the entire string. Then paste it into the **Connection String** field in the application. ![Access Keys in Azure Portal](/img/connections/azure-storage-access-keys.png) ## What is a Connection String and How Does It Work A Connection String is a composite authentication string that contains: - The name of the Storage Account - The access key - The protocol type - The endpoint configuration Typical format: ``` DefaultEndpointsProtocol=https; AccountName=storageaccountname; AccountKey=BASE64KEY; EndpointSuffix=core.windows.net ``` What it means: | Element | Function | | --- | --- | | Protocol | Ensures encrypted communication (HTTPS) | | AccountName | Identification of the Storage Account | | AccountKey | Cryptographic access key | | EndpointSuffix | Azure regional infrastructure | The application uses this string to: - authenticate access, - identify the target account, - obtain full permissions based on the type of key. ## Separate the Uploader from the Siesta AI Reader An automated Azure File Share pipeline normally has two independent identities: | Access path | Purpose | Recommended access | | --- | --- | --- | | Local synchronization service | Writes approved documents and metadata to Azure File Share | Identity-based SMB authentication, `Storage File Data SMB Share Contributor`, and matching file/directory ACLs | | Siesta AI Connection | Reads the published share for ingestion | Read access required by the deployed Connection design | Do not reuse a broad uploader credential merely because both paths access the same share. The synchronization identity needs write access; Siesta AI normally does not. Identity-based SMB access combines share-level RBAC with file and directory ACLs. A user's RBAC assignment is effective only when the SMB session authenticates with that identity and the ACL also permits the operation. A mount made with a Storage Account key acts as the Storage Account identity, bypasses individual user authorization, and provides broad access. Use the account key only as a protected fallback and rotate it regularly. See [Azure Files share-level permissions](https://learn.microsoft.com/en-us/azure/storage/files/storage-files-identity-assign-share-level-permissions) and the [Windows Azure Files mount guide](https://learn.microsoft.com/en-gb/azure/storage/files/storage-how-to-use-files-windows). ## Summary The Azure Storage Account is a quick way to connect blobs, files, queues, and tables to Siesta AI. After obtaining the Connection String, simply add the data source to the collection and select the appropriate access. For a complete on-premises synchronization and ingestion design, continue with [Automated File Ingestion with Azure File Share](#doc-data-azure-file-share-ingestion). ## Technical Notes - **Implementation**: The connection exposes Azure Blob Storage operations. - **Authentication/scopes**: uses an Azure Storage connection string, account key, SAS, or equivalent credential configured for the storage account. Container management requires account-level permissions; blob operations require access to the selected container. - **Functions**: list containers, create containers, delete containers, get container properties, list blobs, upload blobs, download blobs, and delete blobs. - **Write behavior**: creating containers, uploading blobs, and deleting containers or blobs are destructive or state-changing operations and should be confirmed before execution. --- # Clockify

Clockify

The **Clockify** connection lets agents work with time-tracking data in a selected Clockify workspace. Use it when an agent should inspect workspaces, users, clients, projects, tasks, time entries, expenses, approvals, time off, or create and update operational records in Clockify. ## Recommended Setup 1. Open Clockify **Profile Settings** and go to **API Keys**. 2. Generate an API key for the intended workspace owner or service account. 3. Copy the **Workspace ID** for the workspace that Siesta AI should use. 4. Add the **Clockify** connection in Siesta AI. 5. Paste the API key into **Provide your ApiKey** and paste the workspace identifier into **Provide your Workspace ID**. 6. Leave **Provide your Subdomain** empty unless your Clockify setup uses a custom subdomain. 7. Leave **Provide your Region** empty unless your Clockify account requires an explicit region value. 8. Share the connection only with the teams that should read or change Clockify data. 9. Require confirmation for create, update, and delete functions before broad rollout. ![Clockify API keys screen with a Siesta AI API key example](/img/connections/clockify-api-keys-siesta-ai.png) Generate the key from **Profile Settings -> API Keys** and use a dedicated name so the token is easy to rotate or revoke later. ![Clockify connection form in Siesta AI with a placeholder workspace ID](/img/connections/clockify-connection-form-redacted.png) For most Cloud setups, only the **Workspace ID** and **ApiKey** fields are required. If you do not have a custom subdomain or region-specific requirement, leave **Subdomain** and **Region** empty. ## What Agents Can Do - validate the API key and list accessible workspaces, - select a workspace for later calls, - list users, clients, projects, tasks, time entries, expenses, approvals, and time off, - create clients, projects, tasks, and completed time entries, - update existing time entries, - delete time entries when the connection capability allows it, - request a detailed Clockify report. ## Governance Notes Clockify combines read-heavy reporting with write-capable operational functions. Use this baseline: - enable listing and reporting functions for agents that only need visibility, - require confirmation for creating clients, projects, tasks, or time entries, - require confirmation for deleting time entries, - scope the API key to the minimum workspace access that still supports the use case. If the connection uses capability flags, a function can still be unavailable even when it exists in the overall tool surface. ## Common Use Cases - summarize how a team spent time in the current week, - find open projects or tasks before creating a new time entry, - create a completed time entry from a task or conversation outcome, - review time off or approval records before follow-up, - prepare a reporting brief from Clockify data. --- # Confluence

Confluence

## Overview The Confluence connection allows for a secure integration of the Siesta AI platform with Atlassian Confluence via the official API. The integration provides controlled access to the content of the Confluence space and enables: - searching for pages, - listing pages in a space or page tree, - loading documentation content, - programmatically creating new pages, - updating existing pages. The connection is designed for enterprise use with an emphasis on permission management, auditability, and data access security. ## Requirements - An active **Confluence Cloud** site. - An Atlassian account that has access to the Confluence space/pages that the connection will work with. - A generated **API token** in the Atlassian account (`id.atlassian.com` → **Security** → **API tokens**). - Administrator permissions to manage the connection in Siesta AI. ## Supported Operations | Operation | Description | | --- | --- | | `SearchPagesAsync` | Full-text search of pages within the selected Confluence space | | `ListPagesAsync` | Listing pages in a selected space, parent page, or page tree segment | | `GetPageAsync` | Loading the content of a page including metadata | | `CreatePageAsync` | Creating new pages in Confluence | | `UpdatePageAsync` | Updating existing pages | ## Permission Management Each operation can be set individually: - **Allowed** – the operation is available without restrictions. - **Allowed with confirmation** – the operation requires manual approval. - **Denied** – the operation is not available. This model allows for precise definition of access scope, e.g., for: - read-only agents, - automated documentation processes, - controlled writes to Confluence. ## Configuration Parameters ### Required Parameters | Parameter | Description | | --- | --- | | **Name** | Internal designation of the connection | | **ApiKey** | API token generated in the Atlassian account | | **Confluence site URL** | URL of the Atlassian instance (e.g., `https://company.atlassian.net`) | | **Email or username of Atlassian account** | Email (or username) of the account under which the token was created | ## Steps to Add the Confluence Connection ### 1) Prepare Your Access Credentials Before you start creating the connection in Siesta AI, prepare all the values you will enter into the form. In your Atlassian account, open **Security** and the **API Tokens** section. ![Atlassian API Tokens](/img/connections/atlassian-api-tokens.png) Click on **Create API token** (without scopes), enter the token name and expiration, and confirm the creation. ![Creating Atlassian API Token](/img/connections/atlassian-create-api-token.png) After creating the token, copy it once and store it securely. ![Copying Atlassian API Token](/img/connections/atlassian-copy-api-token.png) Then prepare: - **Confluence site URL** (e.g., `https://company.atlassian.net`) - **Email or username** of the Atlassian account under which the token was created ### 2) Open Integration Management in Siesta AI In the Siesta AI administration, go to **Administration → Connected Apps**. ### 3) Select Confluence In the **Add Integration** dialog, select **Confluence** and proceed. ### 4) Fill Out the Confluence Form Fill in: - **Name** - **ApiKey** (token from Atlassian) - **Confluence site URL** (e.g., `https://company.atlassian.net`) - **Email / username** of the Atlassian account under which the token was created Confirm the creation of the integration. ![Configuring Confluence Integration](/img/connections/siesta-ai-confluence-form.png) ### 5) Set Operation Permissions After creating the integration, open **Permission Settings** and set the allowed operations. Recommendation: set write operations to **Allowed with confirmation**. ![Setting Operation Permissions](/img/connections/siesta-ai-confluence-permissions.png) ### Important Note on API Token and Permissions The API token is tied to a specific Atlassian account. The connection inherits the permissions of this account in Confluence (what the account cannot see or edit, the connection cannot either). For this reason, it is recommended: - that each user has their own token if the connection runs under their identity, - or to use a dedicated service account for shared/production automation, - to monitor the expiration of the token and perform regular rotation. ## Typical Use Cases ### Internal Knowledge Base - Searching internal documentation - Listing pages in a space before opening a specific document - Answering employee inquiries - Centralized access to current information ### Documentation Automation - Generating release notes - Creating meeting minutes - Updating standard operating procedures (SOP) - Listing a page tree before selecting the target page to summarize or update ### Process Integration - Synchronizing Jira → Confluence - Automatically generating reports - Documenting incidents and audit records ## Security Architecture The integration utilizes: - authorized access via the Atlassian API, - restrictions to specific Confluence spaces, - granular permission management for operations, - the ability to audit activities. There is no unauthorized downloading of content or bypassing of Atlassian platform security mechanisms. ## Recommended Operational Configuration - Allow reading without restrictions. - Set write operations to **Allowed with confirmation**. - Use separate spaces for automated documentation. - Regularly review connection permissions. ## Technical Notes - **Implementation**: The connection exposes Confluence page operations. - **Authentication/scopes**: uses Atlassian credentials/API token or equivalent connection credentials. The account must have space/page permissions matching the intended read or write operations. - **Functions**: search pages, list pages, get a page, create a page, and update a page. - **Write behavior**: create and update actions publish changes to Confluence, so require review/confirmation for production knowledge bases. --- # Email

Email

The **Email** connection allows you to connect your own email provider via IMAP/SMTP and perform email operations directly in Siesta AI (agents, workflows, automation). ## 1. Adding an Email Connection 1. Open the **Connections** section. 2. Click on **Add Connection**. 3. In the dialog, select the **Email** tile. 4. Continue by clicking the **Continue** button. ## 2. Configuring the Email Provider After selecting the connection, fill in the configuration details: - **Name**: internal name of the connection in Siesta AI. - **Provide your Username**: login name for the mailbox. - **Provide your Password**: password or app password. - **Provide your IMAP Host / IMAP Port**: server and port for reading mail. - **Provide your IMAP Encryption**: type of encryption (`SslOnConnect`, `StartTls`, `None`, `Auto`). - **Provide your SMTP Host / SMTP Port**: server and port for sending mail. - **Provide your SMTP Encryption**: type of encryption (`SslOnConnect`, `StartTls`, `None`, `Auto`). ![Email connection configuration form](/img/connections/email-connection-form.png) ## 3. Scopes and Permissions for Functions In the **Functions** section, you set the permissions for individual email actions (scopes/policies): - `Enabled` - the function is activated without further confirmation. - `Enabled with confirmation` - confirmation is required before execution. - `Disabled` - the function is disabled. Typically, read operations are allowed directly (e.g., `SearchEmailsAsync`, `GetEmailAsync`), while riskier write operations run with confirmation (e.g., `SendEmailAsync`, `DeleteEmailAsync`, `MoveEmailAsync`). ![Setting scopes for Email connection functions](/img/connections/email-function-scopes.png) ## 4. Recommendations - Use a separate service account or app password. - Set the minimum necessary permissions for functions (principle of least privilege). - For actions that modify data or send emails, prefer the `Enabled with confirmation` mode. - Regularly review which functions are `Enabled`. ## Summary The Email connection provides the ability to connect your own email provider via IMAP/SMTP, securely set scopes for individual functions, and control what actions agents and workflows can perform. ## Technical Notes - **Implementation**: The connection provides generic mailbox access over configured mail credentials. - **Authentication/scopes**: uses IMAP/SMTP style server settings and credentials rather than OAuth scopes. The mailbox account determines which folders and send permissions are available. - **Functions**: search emails, read a message, send email, create draft, delete email, update message flags, move messages, and copy messages. - **Write behavior**: sending, deleting, moving, copying, and flag changes alter the mailbox and should require user approval for shared or customer-facing accounts. --- # Firecrawl

Firecrawl

The **Firecrawl** connection allows you to connect the Firecrawl API to Siesta AI and use web crawling as a data source in agents, workflows, and data collections. ## 1. Obtaining an API Key in Firecrawl First, you need to obtain an API key in your Firecrawl account: - open the Firecrawl dashboard, - in the **API Key and Code Snippets** section, copy your API key, - prepare your API endpoint (typically `https://api.firecrawl.dev`). ![Firecrawl API key and code snippets](/img/connections/firecrawl-api-key-and-code-snippets.png) Example of filling in the API URL and API token: ![Firecrawl API credential setup example](/img/connections/firecrawl-api-key-page.png) ## 2. Adding Firecrawl Connection in Siesta AI 1. In the **Connections** section, click on **Add Connection**. 2. In the dialog, select the **Firecrawl** tile. 3. Proceed to the configuration details. ## 3. Configuring the Connection In the form, fill in: - **Name**: internal name of the connection. - **Provide your ApiKey**: API key from your Firecrawl account. - **Provide your Firecrawl api url**: API URL (e.g., `https://api.firecrawl.dev`). - **Visibility**: `Private` or `Shared`. After saving, the connection is available for use on the platform. ![Firecrawl connection form in Siesta AI](/img/connections/firecrawl-connection-form.png) ## 4. Using as a Data Source Firecrawl can also be used as a **data source** in data collections. The user adds Firecrawl when creating a source in the collection and sets up synchronization and source parameters. - Adding a source in the collection: [Data Collections - Adding a Data Source](#doc-data-collections) - Configuring Firecrawl source: [Data Collections - Firecrawl](#doc-data-collections) ## Summary The Firecrawl connection in Siesta AI provides a simple connection to the Firecrawl API via API key and API URL. After configuration, it can be used in automations as well as a data source. ## Technical Notes - **Implementation**: The connection wraps Firecrawl web extraction APIs. - **Authentication/scopes**: uses a Firecrawl API key. Access is limited by the Firecrawl plan, crawl limits, and target-site policies. - **Functions**: scrape a single page, crawl a site, map a site, and run web search through Firecrawl. - **Write behavior**: functions do not write to the target site, but they can fetch external content. Respect robots, customer data rules, and internal URL policies. --- # GitHub

GitHub

The **GitHub** connection lets agents inspect repositories, prepare branches, open pull requests, and track GitHub work safely. It uses a configured API token against the GitHub REST API. ## When to Use It Use it when an agent needs to read repository content, triage issues, create implementation branches, update files, open pull requests, inspect workflow runs, or manage repository Actions secrets. It is best for engineering agents that have a clear repository scope, naming convention, and review path. ## Setup 1. Create a fine-grained GitHub personal access token that can access only the repositories and operations the agent should use. Keep separate tokens for read-only work and write-capable automation. 2. In **Connections**, click **Add Integration** and select **GitHub**. Paste the PAT into `Provide your ApiKey`. For standard GitHub Cloud, keep `Provide your Api Base Url` set to `https://api.github.com`; only change it for GitHub Enterprise with a different REST API base URL. 3. Limit who can use write functions. Read functions can be broadly useful, but file updates, branch creation, pull request creation, comments, issues, and secret updates should require explicit approval for production repositories. 4. Attach the connection to selected engineering agents or workflows with a clear repository scope and review path. ![GitHub fine-grained personal access token with the token value redacted](/img/connections/github-pat-token-redacted.png) Use a fine-grained PAT that matches the repository scope and write surface you actually want to expose. After GitHub shows the token once, copy it immediately and store it only in Siesta. ![GitHub connection form in Siesta with Api Base Url and ApiKey fields](/img/connections/github-connection-form.png) In the connection form, enter the token into `Provide your ApiKey`. For GitHub Cloud, the `Provide your Api Base Url` value should stay `https://api.github.com`. ## What the Tool Can Do - **Inspect repository state.** Get the current GitHub user, list accessible repositories, load repository metadata, list branches, and browse files or folders. - **Read and change files.** Read text files from a branch, create a working branch, then create or update text files with a commit message. - **Manage issues and pull requests.** List and open issues, comment on issues or PRs, create pull requests, find an existing PR, and inspect changed files or commits. - **Review delivery signals.** List workflow runs, get one workflow run, list repository Actions secret metadata, and create or update an Actions secret value.
Full function surface | Area | Available functions | | --- | --- | | Identity and discovery | Get current GitHub user, list repositories, get repository metadata | | Repository content | List branches, create or ensure a branch, read text files, list files and folders, create or update text files, delete files | | Pull requests | List PRs, get PR details, create a PR, find an open PR by source and target branch, list PR files, list PR commits | | Issues | List issues, get an issue, create an issue, comment on an issue or pull request | | Actions and secrets | List workflow runs, get a workflow run, list repository secret metadata, create or update a repository secret, delete a repository secret |
## Security and Confirmation The GitHub implementation blocks direct writes to protected branch names such as `main`, `master`, and `release/*`. The safest pattern is still to make the agent work on a dedicated branch and ask for review before merging. Before you enable writes, confirm that: - The token has the smallest repository scope that still supports the use case. - Write-capable functions require confirmation or are limited to trusted engineering agents. - The agent prompt names the allowed owner, repository, branch pattern, and file paths. - Direct commits to production branches are not part of the workflow. - Secret updates are treated as high-risk and reviewed by an admin or repository owner. - Tool Runs and GitHub audit history are reviewed after automated changes. ## Example Usage ```text Use the GitHub connection for acme/portal only. Read the issue, inspect the relevant files, create branch ai/fix-login-copy from main, update only docs/login.md, and open a pull request. Do not commit directly to main. Summarize the diff before creating the PR. ``` Other common use cases: - **Triage bugs into issues.** Convert a conversation or task into a GitHub issue with labels, assignees, and a reproducible description. - **Prepare documentation changes.** Read current docs, update one or more text files on a feature branch, and open a pull request for review. - **Summarize pull requests.** List changed files and commits, then produce a review brief or release-note draft. - **Check failed deployments.** Inspect recent workflow runs by branch or status and link the relevant GitHub Actions run to the task owner. ## Technical Notes | Area | Detail | | --- | --- | | Tool name | GitHub | | Authentication | API key credential sent as Authorization: Bearer <token> | | Default API host | https://api.github.com | | Enterprise support | Set the connection field ApiBaseUrl to your GitHub Enterprise REST API base URL. | | API version header | The tool sends X-GitHub-Api-Version: 2026-03-10. | | Secret handling | Repository secret values are encrypted before upload and are never returned by GitHub. | | Connection fields | Use Provide your ApiKey for the PAT and keep Provide your Api Base Url on https://api.github.com unless your GitHub environment uses a different host. | ## Common Problems | Symptom | Likely cause | Fix | | --- | --- | --- | | Agent cannot see a repository | The token cannot access the owner or repository | Recreate or update the token with the correct repository access. | | Branch or file write fails | The target branch is protected, missing, or the token lacks contents permission | Create a working branch from the base branch and check token scopes. | | Pull request creation fails | Source branch does not exist or target branch is wrong | Ensure the branch first, then create the PR against the intended base. | | Workflow runs are missing | Token lacks Actions access or the branch/status filter is too narrow | Check token permissions and remove filters while debugging. | | Secret update fails | Token lacks secret administration permission or the repo public key request failed | Use a repository owner/admin token and retry the update. | --- # Gmail

Gmail

Siesta AI - Gmail allows secure work with a Gmail account through the official Gmail API. The integration provides reading, creating, and sending emails, which can be combined with GPT models and corporate workflows. ## Quick Connection To create, simply click on **Add Connection**, select **Gmail**, and the page will automatically redirect to Google sign-in. After signing in, the account is linked. ## Available Operations ### 1. CreateDraft Creates a new email draft in the Gmail inbox. | Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------| | body | String | Yes | Email text (plain) | | subject | String | Yes | Email subject | | to | String | Yes | Email address | Use cases: automated email generation by AI models, preparation for approval, templates/suggestions. ### 2. SendEmailAsync Sends an email directly from the Gmail account. | Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------| | body | String | Yes | Email text | | subject | String | Yes | Email subject | | to | String | Yes | Recipient address | Use cases: automatic notifications, sales/marketing sequences, follow-ups, AI-generated reports. ### 3. ListInboxAsync Retrieves a list of the most recent messages in the inbox. | Parameter | Type | Required | Description | |-----------------|------|----------|---------------------------| | includeSpamTrash| Bool | No | Include spam and trash | | maxResults | Int | No | Number of returned messages| Use cases: AI agents for email, inbox summarization, categorization and routing, detection of priority messages. ### 4. GetMessageAsync Retrieves the complete content of a specific message including metadata. | Parameter | Type | Required | Description | |-----------|--------|----------|------------------------| | messageId | String | Yes | Message ID in Gmail API| Use cases: content analysis using GPT, data extraction (orders, contacts, SLAs), thread reconstruction, context for automated replies. ## Capabilities Enabled by Gmail Integration - **AI-enhanced drafting**: generating email drafts from context and corporate data. - **AI inbox agent**: automatic replies, labeling, prioritization, summarization of threads. - **Automation workflows**: follow-ups, escalations, onboarding sequences, client communication. - **Data extraction**: structured data from emails, conversion to ticketing/CRM/ERP, links to internal systems. ## Requirements for Integration 1. **Google Cloud Project**: Gmail API enabled, OAuth 2.0 Client ID created, authorized redirect URL for Siesta AI. 2. **OAuth 2.0 Authorization**: user grants access; typical scopes: - https://www.googleapis.com/auth/gmail.readonly - https://www.googleapis.com/auth/gmail.modify - https://www.googleapis.com/auth/gmail.send 3. **Secure token storage**: tokens are encrypted, with automatic refresh token rotation. 4. **Google API quotas & rate limits**: minimize GetMessageAsync calls, batch inbox operations, cache metadata. 5. **Governance & controls**: validation of emails before sending, whitelisting addresses/domains, audit logs, approval workflows. ## Security Considerations - Emails and metadata are not stored without explicit purpose. - Access tokens are encrypted and regularly refreshed. - Each operation is auditable; Siesta AI does not send emails without approval or organizational policy. ## How to Connect (OAuth) 1) **Add Connection** -> select `Gmail` (same selection for Gmail/Google Calendar/Google Search). 2) **Sign in with Google** (OAuth login). 3) **Confirm integration name** (internal name in Siesta AI). 4) **Consent to permissions** (scopes according to Gmail integration). ## Summary The Gmail integration provides Siesta AI with a reliable and secure way to automate corporate communication. The combination of the Gmail API and AI orchestration speeds up email handling, enables analysis of incoming information, and automates routine tasks. ## Technical Notes - **Implementation**: The connection exposes Gmail mailbox actions. - **Authentication/scopes**: uses a Google OAuth token for the connected Gmail account. The token must allow the enabled Gmail read, send, label modification, and draft operations. - **Functions**: send email, list messages using Gmail search syntax, get message details, modify labels, and create drafts. - **Write behavior**: sending email, creating drafts, and changing labels are mailbox-changing operations and should be protected with confirmation for customer or shared inboxes. --- # Google Ads

Google Ads

## Overview The Google Ads Connection provides programmatic access to Google Ads accounts via the Google Ads API. It allows agents and applications to manage campaigns, obtain reports, set bidding strategies, targeting, ad creatives, assets, and conversions. The connection is divided into functional groups of tools, enabling secure management of both read-only analytics and change operations. Supported areas include: - reporting and analytics via GAQL, - account and MCC structure management, - campaign, ad group, and keyword management, - targeting, audiences, and negative keywords, - ad creation and asset management, - conversion management, - batch operations for large numbers of changes. ## How a user adds the Google Ads connection ### 1. The user opens Add Connection and selects GoogleAds 1. In the administration, go to the **Connections / Connected Apps** section. 2. Click on **Add Connection**. 3. Select the **GoogleAds** tile. ### 2. The user prepares the Customer ID The Customer ID is the identifier of the Google Ads account that you will fill in the connection. How to find it: 1. Log in to Google Ads. 2. In the account list or in the top bar, open the account you want to connect. 3. Copy the **Customer ID** of the manager account (usually in the format `123-456-7890`). ![Where to find Customer ID in Google Ads](/img/connections/google-ads-customer-id-location.png) ### 3. The user prepares the Developer Token You can obtain the Developer Token in Google Ads, but first, you need to have a manager account (Manager Account, MCC). First, create an MCC account: [Create a manager account](/img/connections/google-ads-connection-detail.png). How to obtain the Developer Token: 1. Log in to the **Manager Account (MCC)**. 2. Open the **Admin** section. 3. Go to the **API Center** (in the CZ interface *Centrum rozhraní API*). 4. Copy the **Developer token** value. ![Where to find Developer Token in the API Center](/img/connections/google-ads-developer-token-api-center.png) Video guide to the Developer Token: Direct link to the video: [YouTube](https://youtu.be/PodgQhJqW0M?si=m4hQoOLlqQRhx3s8). ### 4. The user fills in the connection details In the **Detail** form, fill in: - **Name**: internal name of the connection (e.g., `GoogleAds`). - **Provide your Customer Id**: Customer ID of the account. - **Provide your Developer Token**: Developer Token from the API Center. ![Detail configuration of the GoogleAds connection](/img/connections/google-ads-connection-detail.png) ### 5. The user saves the connection and sets function permissions After creating the connection, set the call mode for each function: - **Enabled**, - **Enabled with confirmation**, - **Disabled**. Recommendation: keep changing operations (e.g., creating campaigns, changing bids, deleting) at least on **Enabled with confirmation**. ## Functions ### 1. Reporting and Analytics | Tool | Description | | --- | --- | | `RunReportAsync` | Executes custom GAQL queries | | `RunReportStreamAsync` | Uses SearchStream for large reports | | `GetCampaignPerformanceAsync` | Returns campaign performance metrics for a given period | | `ListPolicyDiagnosticsAsync` | Returns diagnostics of advertising policies and ad approval status | GAQL (Google Ads Query Language) is used for structured querying of Google Ads data. `RunReportStreamAsync` is suitable for larger volumes of data. ### 2. Account and Customer Management | Tool | Description | | --- | --- | | `ListAccessibleCustomersAsync` | Returns a list of all accounts accessible to the logged-in user | | `ListManagedCustomersAsync` | Returns a list of client accounts under MCC | | `RunReportAcrossAccountsAsync` | Executes a GAQL report across multiple accounts | These tools are mainly used in the MCC environment, where an agency manages multiple accounts. ### 3. Campaign Management | Tool | Description | | --- | --- | | `ListCampaignsAsync` | Returns a list of campaigns excluding deleted ones | | `CreateCampaignAsync` | Creates a new campaign (default state `PAUSED`) | | `CreatePerformanceMaxCampaignAsync` | Creates a Performance Max campaign | | `UpdateCampaignStatusAsync` | Starts, pauses, or removes a campaign | | `UpdateCampaignBudgetAsync` | Updates the daily budget of the campaign | New campaigns are in the `PAUSED` state to prevent unintended ad launches. ### 4. Bidding Strategy Management | Tool | Description | | --- | --- | | `UpdateCampaignBiddingStrategyAsync` | Changes the bidding strategy of the campaign | Supported strategies: - `MANUAL_CPC`, - `Target CPA (tCPA)`, - `Target ROAS (tROAS)`, - `Maximize Conversions`, - `Maximize Conversion Value`. ### 5. Ad Group Management | Tool | Description | | --- | --- | | `ListAdGroupsAsync` | Returns a list of ad groups (can be filtered by campaign) | | `CreateAdGroupAsync` | Creates a new ad group in a campaign | | `UpdateAdGroupStatusAsync` | Starts, pauses, or removes an ad group | | `UpdateAdGroupBidAsync` | Updates the default CPC bid | ### 6. Keyword Management | Tool | Description | | --- | --- | | `ListKeywordsAsync` | Returns a list of keywords including match types and bids | | `AddKeywordsAsync` | Bulk adds keywords | | `UpdateKeywordStatusAsync` | Starts or pauses a keyword | | `UpdateKeywordBidAsync` | Updates the CPC bid | | `RemoveKeywordAsync` | Permanently removes a keyword | Supported match types: - `BROAD`, - `PHRASE`, - `EXACT`. ### 7. Targeting and Negative Keywords | Tool | Description | | --- | --- | | `AddCampaignNegativeKeywordsAsync` | Adds negative keywords at the campaign level | | `AddAdGroupNegativeKeywordsAsync` | Adds negative keywords at the ad group level | | `AddCampaignLocationTargetsAsync` | Adds geographic targeting via location constant ID | | `AddCampaignLanguageTargetsAsync` | Adds language targeting | | `AddCampaignDeviceTargetAsync` | Adds or excludes device targeting | | `AddCampaignAdScheduleTargetAsync` | Sets the ad display schedule | | `AddCampaignAudienceTargetsAsync` | Adds audience or user list targeting | | `UpdateCampaignCriterionStatusAsync` | Updates the targeting status | | `RemoveCampaignCriterionAsync` | Removes targeting at the campaign level | | `RemoveAdGroupCriterionAsync` | Removes targeting at the ad group level | ### 8. Ad Management | Tool | Description | | --- | --- | | `CreateResponsiveSearchAdAsync` | Creates a Responsive Search Ad | | `UpdateAdStatusAsync` | Starts or pauses an ad | Requirements for Responsive Search Ad: - headlines: `3-15`, - descriptions: `2-4`. ### 9. Asset Group Management | Tool | Description | | --- | --- | | `ListAssetGroupsAsync` | Returns a list of asset groups | | `CreateAssetGroupAsync` | Creates a new asset group | | `UpdateAssetGroupStatusAsync` | Updates the status of the asset group | This area is mainly used for Performance Max campaigns. ### 10. Ad Extensions (Assets) | Tool | Description | | --- | --- | | `CreateSitelinkAssetAsync` | Creates a sitelink extension | | `CreateCalloutAssetAsync` | Creates a callout extension | | `CreateStructuredSnippetAssetAsync` | Creates a structured snippet | | `LinkAssetToCampaignAsync` | Links an asset to a campaign | | `UpdateCampaignAssetStatusAsync` | Updates the status of the asset link | ### 11. Conversion Tracking | Tool | Description | | --- | --- | | `CreateConversionActionAsync` | Creates a conversion action (web or offline) | | `UpdateConversionActionStatusAsync` | Activates, hides, or removes a conversion action | | `RemoveConversionActionAsync` | Permanently removes a conversion action | | `UploadOfflineClickConversionAsync` | Uploads offline conversions using GCLID | Offline conversions require: - `GCLID`, - `conversion action`, - conversion time, - conversion value (optional). ### 12. Batch Operations | Tool | Description | | --- | --- | | `CreateBatchJobAsync` | Creates a batch job | | `AddKeywordOperationsToBatchJobAsync` | Adds keyword operations to the queue | | `RunBatchJobAsync` | Executes the batch job | | `ListBatchJobResultsAsync` | Returns the results of the batch operation | | `RemoveBatchJobAsync` | Removes the batch job | Typical use cases for batch operations: - importing a large number of keywords, - bulk bid adjustments, - updating campaigns on a large scale. ## Security and Best Practices To reduce the risk of unintended costs or errors: - create new campaigns in the `PAUSED` state, - perform large changes via Batch Jobs, - validate budgets, bidding strategies, and targeting before changes, - keep deletion operations in **Enabled with confirmation** mode. ## Typical Automation Scenarios The Google Ads Connection can be used for: - automatic generation of campaign performance reports, - creation and ongoing optimization of campaigns, - adjustments to bidding strategies based on performance data, - detection of issues with advertising policies, - expanding the list of keywords, - uploading offline conversions, - managing multiple accounts in the MCC environment. ## Technical Notes - **Implementation**: The connection exposes Google Ads reporting and management functions. - **Authentication/scopes**: uses Google Ads API access with OAuth and the configured developer/customer context. Account and MCC access are controlled by Google Ads permissions. - **Functions**: run GAQL reports, stream reports, list accessible customers, inspect campaigns/ad groups/keywords, manage campaigns, ad groups, keywords, negative keywords, audiences, schedules, responsive search ads, Performance Max assets, conversions, offline conversions, and batch jobs. - **Write behavior**: campaign, bidding, targeting, creative, conversion, and batch-job actions can materially affect spend and delivery. Require approval and use test accounts where possible. --- # Google Analytics

Google Analytics

Connecting **Google Analytics** allows you to link the Siesta AI platform with your analytics account for advanced tracking and data analysis. ## Supported Areas * **Real-time tracking:** Monitoring current user activity. * **Campaign performance:** Detailed reports on the success of your marketing campaigns. * **Behavior analysis:** Tracking specific interactions of users with AI agents. * **Policy diagnostics:** Checking compliance with advertising rules and approval status. ## Notice In its current state, the agent requires your **Customer ID**. It cannot be entered in the connection configuration; it must be written in each prompt or entered into Memory, which you then assign to the specific agent. We are working hard on a more convenient solution. ## How to Add Google Analytics Connection The connection is fully automated through Google authorization. 1. In the Siesta AI administration, go to the **Connections** section and click the **Add Connection** button in the top right corner. 2. Select the **Google Analytics** tile. 3. You will be redirected to the standard **Google Auth** login. 4. Log in to your Google account and **allow the Siesta AI application access** to your analytics data. 5. After returning to the platform, enter the **Name** of your connection. 6. For individual features (see the table below), set the permission level: * **Enabled**. * **Enabled with confirmation**. * **Disabled**. ![Google Analytics connection configuration details](/img/connections/google-analytics-settings.png) ## Connecting to an Agent To allow the agent to work with analytics data, you must assign the completed connection to a specific agent in the **Agent Configuration** section. Without this step, the agent will not have access to Google Analytics features. ## Features The connection provides the following tools for working with data: | Tool | Description | | --- | --- | | `ReadReportAsync` | Standard reading of reports for analyzing long-term trends and performance | | `ReadRealtimeReportAsync` | Monitoring current user activity in real-time for the last 30 minutes | | `RunPivotReportAsync` | Creating multidimensional reports using pivot tables for deeper analysis | | `BatchRunReportsAsync` | Bulk running multiple reports at once, speeding up data loading in dashboards | | `BatchRunPivotReportsAsync` | Bulk processing of complex analytical pivot queries | | `CheckCompatibilityAsync` | Checking if selected metrics and dimensions are mutually compatible to avoid errors | | `GetMetadataAsync` | Automatically loading the current list of available dimensions and metrics from your GA4 account | ## Disclaimer This version of the documentation is in beta and may contain inaccuracies or errors. ## Technical Notes - **Implementation**: The connection uses the GA4 Data API. - **Authentication/scopes**: requests `https://www.googleapis.com/auth/analytics.readonly`; the Google account must have access to the GA4 property. - **Functions**: run reports, realtime reports, pivot reports, batch reports, batch pivot reports, compatibility checks, and metadata lookup. - **Write behavior**: the tool is read-only and does not change GA4 properties. --- # Google Calendar

Google Calendar

Siesta AI - Google Calendar allows you to create and read events in Google Calendar through the official Google Calendar API. The agent setup and method of delegated access are the same as for Gmail integration, so the same screens and procedures (OAuth, access assignment, sharing) can be used. ## Quick Connection To create a connection, simply click on **Add Connection**, select **Google Calendar**, and the page will automatically redirect to Google login. After logging in, the account is linked. ## How to Connect (OAuth, like Gmail) 1) **Add Connection** -> select `GoogleCalendar`. 2) **Google OAuth Login** (access to Calendar). 3) **Confirm Integration Name** (internal name). 4) **Consent to Permissions** (Calendar scopes analogous to Gmail). ## Connection Overview - **Connection Name**: GoogleCalendar - **Type**: Google Calendar API (REST) - **Authentication**: Google OAuth (user delegated access) - details according to internal configuration (beyond the scope of this document) - **Scope/operations**: CreateEventAsync, ListEventsAsync ## General Principles ### 3.1 Time Formats DateTime parameters use ISO 8601. Recommendation: use explicit time zone (Z for UTC or offset +01:00, +02:00). Example: `2025-06-21T14:00:00Z` ### 3.2 Default Calendar If `calendarId` is not specified, the user's default calendar will be used: `primary`. ### 3.3 Recurring Events Listing events supports the `singleEvents` option, which determines whether the recurrence is expanded into individual instances. ## Detailed API Operations ### 4.1 CreateEventAsync **Description:** Creates an event in the user's Google calendar (under their Google/Gmail account). | Parameter | Type | Required | Description | |-------------------|----------|----------|----------------------------------------------| | summary | String | Yes | Title / subject of the event | | startTime | DateTime | Yes | Start of the event (ISO 8601) | | endTime | DateTime | Yes | End of the event (ISO 8601) | | description | String | No | Description of the event | | location | String | No | Location of the event | | sendNotifications | Bool | No | Whether to send notifications to participants/user | **Validation Notes** - `endTime` must be strictly after `startTime`. - Recommendation: use a consistent time zone for both times. ### 4.2 ListEventsAsync **Description:** Returns a list of events from the user's calendar within the specified time range. | Parameter | Type | Required | Description | |--------------|----------|----------|--------------------------------------------------| | calendarId | String | No | Calendar ID (default: `primary`) | | timeMin | DateTime | No | Start time for listing (inclusive) | | timeMax | DateTime | No | End time for listing (exclusive) | | maxResults | Int | No | Maximum number of events (default: 250) | | singleEvents | Bool | No | Expand recurrences into instances (default: true) | **Recommended Usage** - For stable results, always set `timeMin` and `timeMax`. - If processing recurring meetings in analytics, leave `singleEvents=true`. ## Security and Governance - Operations run in the context of the user (delegated access via OAuth). - The connection only works with calendar data within the granted permissions. - Recommendation: audit and log at least `calendarId`, time window (`timeMin`/`timeMax`) for listing, and parameters `summary`/`startTime`/`endTime` for created events. ## Technical Notes - **Implementation**: The connection exposes Google Calendar event operations. - **Authentication/scopes**: uses a Google OAuth token with Calendar access for the connected account/calendar. - **Functions**: list events for a date range, create calendar events, and update existing events including attendees. - **Write behavior**: event creation and updates notify or affect attendees and calendars, so confirm date/time, timezone, attendees, and recurrence before execution. --- # Google Docs

Google Docs

The connection is established in the same way as with other Google accounts in Siesta AI (OAuth 2.0). OAuth login and the consent screen in the Google account may vary depending on the account type, domain policy, and available permissions. ## Overview This document describes the integration of **GoogleDocs** for working with documents in Google Workspace. The integration is suitable for: - reading document content for agents and workflows, - automated document creation, - updating document content within internal processes. ## 1. Connecting Google Docs in Siesta AI 1. In the **Connections** section, click on **Add Connection**. 2. In the connection selection, choose the Google connection. 3. Log in with your Google account. 4. Confirm the required permissions (scopes) for Google Docs. 5. In the connection details, you can modify access and the range of allowed functions (scopes/policies). ![Connection Details and Scopes](/img/connections/connection-detail-scopes.png) ## 2. Google Docs Integration ### Service Name GoogleDocs ### Description The integration allows creating, retrieving, and updating Google documents through an authorized Google account. ### 2.1 CreateDocumentAsync **Description** Creates a new Google document. **Input Parameters** | Parameter | Type | Required | Description | |-----------|---------|----------|----------------------------------------| | title | String | Yes | The title of the document. | | content | String | No | The initial text content of the document. | **Behavior** - If `content` is provided, it will be written to the newly created document. - The output is the identifier and metadata of the new document. **Typical Use Cases** - Generating reports - Creating documents from templates ### 2.2 GetDocumentAsync **Description** Retrieves an existing Google document by ID. **Input Parameters** | Parameter | Type | Required | Description | |-------------|---------|----------|---------------------------------| | documentId | String | Yes | The ID of the target document. | **Behavior** - Returns metadata and content of the document according to the account's permissions. - If the document does not exist or is not accessible, the operation fails. ### 2.3 UpdateDocumentAsync **Description** Updates the content of an existing document. **Input Parameters** | Parameter | Type | Required | Description | |-------------|---------|----------|-------------------------------------------| | documentId | String | Yes | The ID of the document to be modified. | | content | String | Yes | The new content to be written. | **Behavior** - The update occurs on the existing document. - The scope and manner of changes are governed by the permissions of the connected Google account. **Typical Use Cases** - Updating operational documents - Appending outputs from workflows - Synchronizing content between systems ## Security Notes - The integration runs through the official Google API. - Access is controlled via OAuth 2.0 and scopes granted by the user. - It is recommended to use the principle of least privilege and regularly review scopes. ## Design Decisions - All operations are performed under a specific authorized Google account. - Permissions for documents inherit from Google Workspace sharing. - Missing permissions or a non-existent document return an error immediately (fail-fast). ## Summary - The GoogleDocs connection allows creating, reading, and editing documents in Google Docs. - The connection is based on OAuth and scope management. - The integration is suitable for automated documentation and reporting scenarios in agents and workflows. ## Technical Notes - **Implementation**: The connection exposes Google Docs and Drive-backed document operations. - **Authentication/scopes**: requests `https://www.googleapis.com/auth/documents` and `https://www.googleapis.com/auth/drive`; Drive permissions still control which documents are visible or editable. - **Functions**: create a document, find a document by name, get a document by ID, append text, replace document content, and list recent documents. - **Write behavior**: create, append, and replace operations change Google Docs directly. Use confirmation before overwriting shared documents. --- # Google Drive

Google Drive

The **Google Drive** connection lets agents read approved Google Drive files without broad workspace access. Use it when an agent needs source documents, folders, exports, sheets, PDFs, or shared-team files as context. It is OAuth-based and follows the connected Google account's Drive permissions. ## When to Use It Use it when an agent needs durable source material from Drive, such as product docs, support policies, contracts, proposals, or onboarding material, rather than a one-off chat attachment. It is a read-oriented knowledge source, best for document lookup, file retrieval, and data collections. ## Setup 1. In **Connections**, click **Add Integration** and choose **Google Drive** from the Google provider group. 2. Sign in with the account that can already access the folders or shared drives the agent should read. 3. Name the connection so it explains the source, such as Support Drive or Sales Enablement Docs, then choose private or shared access. 4. Attach the connection to a data collection, agent configuration, or workflow step that needs file context. ## What the Tool Can Do - **Answer from company documents.** Connect product docs, support policies, contracts, proposals, or onboarding material through a data collection. - **Summarize shared files.** Read files the connected account can access and return a concise summary, risks, owners, or next steps. - **Prepare repeatable research.** Use Drive folders as stable source material for recurring reports, customer review packs, or operational workflows. - **Keep access bounded.** Access is limited to what the Google account can already see, so scope the account before connecting it. ## Security and Confirmation Google Drive is a read-oriented connection, but it is still sensitive because retrieved file content becomes agent context. Use the smallest practical Google account or shared drive scope, review which agents can use the connection, and check Tool Runs or data-source status when access fails. Before you connect, confirm that: - The Google account has access to the exact files or folders the agent should read. - The source is not better handled as a one-off chat attachment. - The connection name tells users which Drive area it represents. - Shared access is intentional and approved for the team using it. - Sensitive folders are excluded or not shared with the connected account. - The agent or data collection using this source has a clear purpose. | Area | How to think about it | | --- | --- | | Authentication | OAuth with Google. Reauthorize if the token expires or scopes change. | | Permission boundary | The connected Google account and Drive sharing rules decide what can be read. | | Recommended access | Private for personal work; shared only for team-owned folders or shared drives. | | Write behavior | Treat this as read-only unless your released tool surface explicitly adds write functions. | | Audit | Review tool runs, data-source sync status, and admin audit logs when results look wrong. | ## Example Usage For durable source material, create a data collection from the Drive connection instead of asking users to upload the same file repeatedly. This gives agents a reusable knowledge surface and makes it easier to review processing status, failed files, and source ownership. ```text Use the Support Drive data collection only. Answer the customer question, cite the source document name, and say "not found" if the answer is not in the connected Drive files. ``` ## Technical Notes - **Implementation**: OAuth 2.0 source connection to Google Drive, exposed as a read-oriented knowledge source for data collections. - **Authentication/scopes**: OAuth with Google. The connected account's Drive sharing rules determine which files are visible; reauthorize when the token expires or scopes change. - **Write behavior**: read-only in this docs surface. Retrieved file content can become agent context, so scope the connected account to the minimum needed. ## Common Problems | Symptom | Likely cause | Fix | | --- | --- | --- | | Agent cannot find a file | The connected account cannot access it, or the file is not included in the data collection | Share the folder/file with the connected account and refresh the source. | | Authorization failed | OAuth token expired or the Google account changed security settings | Reconnect Google Drive from the connection detail. | | Wrong documents are used | The agent has multiple sources and picked the wrong one | Name the data collection explicitly in the prompt or attach only the intended source. | | Shared connection is missing | Access policy does not include your team or agent | Ask an admin to share the connection or use a personal connection. | --- # Google PageSpeed

Google PageSpeed

The **Google PageSpeed** connection runs an analysis of a URL through Google PageSpeed Insights and returns technical performance results for the page. It is suitable for a quick check of websites, landing pages, and changes after a release. ## When to Use It Use it when an agent needs to evaluate the performance of a specific page, identify key issues, and prepare recommendations for development or marketing. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Google PageSpeed**. 3. Fill in the required API key or authorization details according to your organization's settings. 4. Assign the connection to the agent that will analyze the web pages. ## What the Tool Can Do - analyze a single URL, - return raw output from Google PageSpeed Insights, - provide materials for a summary of performance, issues, and recommendations. ## Security and Confirmation The tool only reads publicly available URLs and does not make any changes. Confirmation is typically not needed. For internal or non-public URLs, ensure that the agent does not share sensitive content outside of the approved context. ## Example Usage > Measure PageSpeed for our pricing page and write down the three most important technical issues we need to address. Verify the result by running the same URL in PageSpeed Insights or in **Run Tools**. ## Technical Notes - **Implementation**: The connection calls Google PageSpeed Insights. - **Authentication/scopes**: uses a Google PageSpeed/API key; no end-user OAuth scope is required for public URL analysis. - **Functions**: analyze a URL and return PageSpeed/Lighthouse metrics and diagnostics. - **Write behavior**: read-only. Results are external diagnostics and should be interpreted together with real user monitoring or analytics when available. --- # Google Search API

Google Search API

Siesta AI - Google Search allows you to programmatically perform web searches via the Google Custom Search JSON API. The connection is read-only and returns structured JSON with results. ## 1. Setting up Google Search API (practical steps) 1. **Project in Google Cloud**: use an existing project or create a new one. 2. **Enable Custom Search API**: search for "Custom Search API" in the API Library and click **Enable**. ![Enabling Custom Search API in API Library](/img/connections/google-search-api-library.png) 3. **Create Programmable Search Engine**: go to https://programmablesearchengine.google.com/, open the list of search engines, and click **Add**. ![List of search engines in Programmable Search Engine](/img/connections/google-search-picker.png) ![Creating a new search engine](/img/connections/google-search-engine-create.png) 4. **Get Search Engine ID (`cx`)**: in the search engine details, open the **Basic** section and copy the **Search Engine ID**. ![Copying Search Engine ID (cx)](/img/connections/google-search-engine-id.png) 5. **Generate API Key**: in Google Cloud Console -> APIs & Services -> Credentials -> **Create credentials** -> **API key**. ![Creating API key in Credentials](/img/connections/google-search-api-key.png) 6. **Key restrictions (recommended)**: - Application restrictions: as needed (None/Websites/IP). - API restrictions: **Restrict key** -> **Custom Search API**. 7. **Settings in Siesta AI**: - Connection -> **Add Connection** -> **GoogleSearch**. - Fill in `Key` (API Key) and `Cx` (Search Engine ID) and choose **Shared/Private**. - Save via **Continue**. ![Setting up GoogleSearch Connection in Siesta AI](/img/connections/google-search-form.png) ## 2. Purpose of the document The goal is to enable programmatic access to web search results via the Google Custom Search JSON API. ## 3. Connection Overview - **Connection Name:** GoogleSearch - **Type:** REST API - Google Custom Search JSON API - **Authentication:** API Key (Google Cloud) + Search Engine ID (`cx`) (OAuth not required) - **Scope:** read/search only - **Output:** JSON object with search results - **Note:** There are no write operations; all calls are idempotent. The Google Custom Search JSON API allows you to programmatically retrieve search results from Google via the Programmable Search Engine, which must be created and configured before use. ## 4. General Principles ### 4.1 Configuration - **Search Engine ID (`cx`):** identifier for your custom search instance. - **API Key:** mandatory parameter for authorized calls to Google API. - **Output:** JSON contains search metadata and result set (title, snippet, URL, pagemap, etc.). ### 4.2 Query Syntax - The `query` parameter (alias `q`) specifies the search term. - Advanced operators such as `site:`, `intitle:` etc. can be used (standard Google query syntax). ## 5. API Operations ### 5.1 Search **Description:** Performs a web search via the Google Custom Search JSON API. **HTTP:** `GET https://www.googleapis.com/customsearch/v1?key={API_KEY}&cx={SEARCH_ENGINE_ID}&q={query}` | Parameter | Type | Required | Description | |-----------|--------|----------|---------------------------------------------| | query | String | Yes | Search term (e.g., "AI best practices"). | **Output** - List of results (title, URL, snippet) - Metadata about the number of results - Possible additional blocks (`pagemap`) **Behavior and Limits** - Standard response ~10 results per page; additional pages via `start` (outside the scope of Connection). **Typical Errors** - 400 Bad Request - invalid query - 401 Unauthorized - invalid API Key - 403 Quota Exceeded - daily quota exceeded ## 6. Security and Governance - Keep the API Key secure; prefer restrictions (domains/IP, limit to Custom Search API). - Monitor quotas and log for billing control. - Log at least: `query` string, call time, number of results, HTTP status. ## 7. Operational Recommendations - Set a rotation policy for the API Key (Rotate key in Google Cloud Console). - Keep `cx` and API Key in a secure secrets store; update Connection when changing the key. ## 8. Example Usage ```http GET https://www.googleapis.com/customsearch/v1 ?key=YOUR_API_KEY &cx=YOUR_SEARCH_ENGINE_ID &q=cloud+infrastructure+best+practices ``` Shortened JSON: ```json { "queries": { "request": [ { "query": "cloud infrastructure best practices" } ] }, "items": [ { "title": "...", "link": "...", "snippet": "..." } ] } ``` ## Technical Notes - **Implementation**: The connection provides search-result retrieval. - **Authentication/scopes**: uses the configured Google Search API credentials/search engine settings. No user mailbox or Drive scope is involved. - **Functions**: submit a search query and return ranked result metadata/snippets. - **Write behavior**: read-only. Treat results as external sources that need verification before being used for decisions. --- # Google Search Console

Google Search Console

The **Google Search Console** connection allows agents to read verified websites, evaluate search analytics, and check the indexing status of specific URLs. It is intended for SEO reporting, traffic drop checks, and technical indexing audits. ## When to Use It Use it when you need to find out how a website is performing in search, which queries are driving traffic, or why a specific URL is not being indexed correctly. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Google Search Console**. 3. Log in with a Google account that has access to the specified property. 4. Verify that the connected account sees the correct website. 5. Assign the connection to an agent or workflow. ## What the Tool Can Do - list verified properties, - retrieve search analytics for the website and date range, - check the indexing status of a specific URL. ## Security and Confirmation The functions are read-only. Nevertheless, they work with sensitive SEO and performance data, so share the connection only with agents who need it. ## Example Use Case > Compare clicks and impressions for the last 28 days against the previous period and find queries with the largest drop. Google Search Console has a delay for some data, usually a few days. Verify the results directly in Search Console or in **Run Tools**. ## Technical Notes - **Implementation**: The connection uses Google Search Console APIs. - **Authentication/scopes**: requests `https://www.googleapis.com/auth/webmasters.readonly`; the Google account must be verified on the Search Console property. - **Functions**: list verified sites, query search analytics, and inspect URL indexing status. - **Write behavior**: read-only. Data can lag by a few days, so avoid treating reports as realtime traffic numbers. --- # Google Sheets

Google Sheets

The connection is established in the same way as with other Google accounts in Siesta AI (OAuth). ## Overview This document describes the available integrations with Google services: - GoogleSheets (operations on spreadsheets) Integrations are designed as deterministic, stateless operations suitable for automation, reporting, and data pipelines. ## 1. Google Sheets Integration ### Service Name GoogleSheets ### Description The integration allows for the creation, retrieval, and updating of Google Spreadsheets. It is used as a lightweight data store or export target for automated processes. ### 1.1 CreateSheetAsync **Description** Creates a new Google Spreadsheet with specified columns. **Input Parameters** | Parameter | Type | Required | Description | |--------------|---------|----------|--------------------------------------------------| | name | String | Yes | The name of the Spreadsheet. | | columnNames | String | Yes | A comma-separated list of column names. | **Behavior** - If a spreadsheet with the given name does not exist, it is created. - Columns are initialized in the first row. **Typical Use Cases** - Initialization of reports - Preparation of data structure for subsequent writing ### 1.2 GetSheetAsync **Description** Retrieves an existing Google Spreadsheet by name. **Input Parameters** | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------| | name | String | Yes | The name of the Spreadsheet. | **Behavior** - Returns metadata of the spreadsheet. - If the spreadsheet does not exist, the operation fails. ### 1.3 UpdateSheetAsync **Description** Replaces the content of an existing Spreadsheet with data in CSV format. **Input Parameters** | Parameter | Type | Required | Description | |-------------|---------|----------|-----------------------------------------------------------------------------| | name | String | Yes | The name of the Spreadsheet. | | csvContent | String | Yes | CSV data to write. If the field contains a comma, it must be in quotes. | **Behavior** - Completely replaces existing content. - Does not perform data type validation. - The responsibility for the correct CSV format lies with the caller. **Typical Use Cases** - Data export - Report synchronization - Automatic rewriting of pipeline outputs ## Security Notes - The integration operates exclusively through the official Google API. - No direct login credentials are exposed. - Access rights are managed at the level of the Google account or service account. ## Design Decisions - Stateless operations without caching and shared state. - Explicit names: the spreadsheet is identified by name, not ID. - Fail-fast approach: inconsistent data leads to an error. ## Summary - GoogleSearch provides deterministic searching through the Google Custom Search JSON API. - GoogleSheets covers the creation, retrieval, and updating of spreadsheets. - Data format and permissions are fully the responsibility of the calling system. ## Technical Notes - **Implementation**: The connection exposes Sheets and Drive-backed spreadsheet operations. - **Authentication/scopes**: requests `https://www.googleapis.com/auth/spreadsheets` and `https://www.googleapis.com/auth/drive`; spreadsheet visibility and edit rights follow Drive permissions. - **Functions**: create a spreadsheet, find one by name, replace sheet content from CSV, and append a CSV row. - **Write behavior**: replacing sheet content and appending rows modify the spreadsheet directly. Confirm target file and tab assumptions before execution. --- # Google Tag Manager

Google Tag Manager

The **Google Tag Manager** connection allows agents to read and manage accounts, containers, workspaces, tags, triggers, variables, folders, versions, and environments in Google Tag Manager. It is a powerful tool that can change measurement and published settings on the website. ## When to Use It Use it for auditing GTM configuration, preparing changes in the workspace, checking tags, triggers, and variables, or for controlled changes in measurement settings. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Google Tag Manager**. 3. Log in with a Google account that has access to the appropriate GTM account and container. 4. In the connection details, enable only the necessary features. 5. For change features, enable confirmation. ## What the Tool Can Do - list accounts, containers, and workspaces, - read tags, triggers, variables, folders, and versions, - create, edit, delete, and revert GTM entities, - synchronize workspaces, - create versions and publish containers, - manage environments and clients. ## Security and Confirmation Publishing a container, editing tags, triggers, variables, and deleting entities can directly affect measurement, marketing campaigns, and the production website. In production, always require confirmation and ideally use a separate workspace for proposing changes. ## Example Usage > Review the GTM container and find tags that do not have a clear trigger or appear to be duplicated. Only propose changes, do not make any edits. Verify the results in Google Tag Manager in the specified workspace and in **Tool Execution**. ## Technical Notes - **Implementation**: The connection exposes a broad Google Tag Manager management surface. - **Authentication/scopes**: requests `https://www.googleapis.com/auth/tagmanager.edit.containers`; GTM account/container/workspace permissions determine what can be changed. - **Functions**: manage accounts, containers, workspaces, tags, triggers, variables, folders, versions, environments, clients, zones, templates, transformations, Google tag configs/destinations, and user permissions. - **Write behavior**: GTM changes can affect production tracking, consent, marketing pixels, and analytics. Require approvals and prefer workspace review/versioning before publishing. --- # Google Trends

Google Trends

## Overview The Google Trends Connection provides programmatic access to Google Trends data. It allows agents and applications to obtain information about the popularity of keywords, geographical distribution of interest, currently trending searches, related queries, and search suggestions. The connection primarily supports: - historical analysis of interest in keywords, - comparison of multiple keywords, - retrieval of currently trending searches, - analysis of related topics and queries, - search suggestions (autocomplete). All functions return structured data obtained from the Google Trends API. For trending search endpoints, a fallback to an RSS source is implemented if the primary API returns an error or incomplete data. ## User story: How a user adds the Google Trends connection ### 1. The user opens the Add Connection dialog and selects GoogleTrends 1. In the administration, navigate to the **Connections / Connected Apps** section. 2. Click on **Add Connection**. 3. In the list of connections, select the **GoogleTrends** tile. ### 2. The user fills in the connection details In the **Detail** form, the user fills in: - **Name**: internal name of the connection (e.g., `GoogleTrends`). - **Provide your ApiKey**: API key, not required in this deployment. - **Provide your Timezone**: timezone (e.g., `UTC`). - **Provide your Language**: response language (e.g., `EN, CS`). ![GoogleTrends connection configuration details](/img/connections/google-trends-connection-detail.png) ### 3. The user sets permissions for individual functions After creating the connection, the user sets the call mode for each operation: - **Enabled**, - **Enabled with confirmation**, - **Disabled**. Recommendation: set operations that may affect the execution of automations to at least **Enabled with confirmation**. ![Setting permissions for GoogleTrends connection functions](/img/connections/google-trends-function-permissions.png) ### 4. The user saves and uses the connection After saving, the connection is available for agents and workflow steps, where specific Google Trends functions can be called according to the set permissions. ## Connection configuration parameters | Parameter | Required | Description | | --- | --- | --- | | `Name` | Yes | Internal name of the connection in Siesta AI | | `ApiKey` | Depending on deployment | API key for accessing the service | | `Timezone` | Yes | Timezone for queries (e.g., `UTC`) | | `Language` | Yes | Language of results (e.g., `EN`, `en-US`) | ## Supported functions ### 1. `GetInterestOverTimeAsync` Returns the development of interest in one or more keywords over time. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keywords` | string | Yes | List of 1-5 keywords separated by commas | | `timeRange` | string | No | Time period for analysis | | `geo` | string | No | Geographical area (ISO country code) | | `category` | int | No | Google Trends category | Default values: - `timeRange`: `LastThreeMonths` - `geo`: globally (empty value) - `category`: `0` (all categories) ### 2. `GetInterestByRegionAsync` Returns the distribution of interest in a given keyword by regions. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keyword` | string | Yes | One keyword | | `timeRange` | string | No | Time period | | `resolution` | string | No | Level of geographical resolution | | `geo` | string | No | Country code | Default values: - `resolution`: `COUNTRY` - `geo`: `US` ### 3. `CompareKeywordsAsync` Compares the popularity of multiple keywords over time. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keywords` | string | Yes | List of 2-5 keywords separated by commas | | `timeRange` | string | No | Time period | | `geo` | string | No | Country code | ### 4. `GetTrendingSearchesAsync` Returns currently trending searches. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `country` | string | No | Country name | Default value: - `country`: `united_states` Behavior: 1. Primary attempt through Google Trends API. 2. On failure, fallback to RSS feed. ### 5. `GetTodaySearchesAsync` Returns searches trending today. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `country` | string | No | Country code | Default value: - `country`: `US` Behavior: - Primarily API, on failure fallback to RSS feed. ### 6. `GetAllTrendingSearchesAsync` Returns globally trending searches across multiple countries. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | - | - | - | Function does not require parameters | Behavior: - attempt to obtain data via API, - fallback to multi-country RSS feed. ### 7. `GetRelatedQueriesAsync` Returns queries related to a given keyword. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keyword` | string | Yes | Keyword | | `timeRange` | string | No | Time period | | `geo` | string | No | Country code | Output includes: - `Top queries` (most common related queries), - `Rising queries` (rapidly growing queries). ### 8. `GetRelatedTopicsAsync` Returns topics related to a given keyword. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keyword` | string | Yes | Keyword | | `timeRange` | string | No | Time period | | `geo` | string | No | Country code | Output includes: - `Top topics`, - `Rising topics`. ### 9. `GetSuggestionsAsync` Returns search suggestions (autocomplete) for the given keyword. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `keyword` | string | Yes | Partial or full keyword | ### 10. `GetCategoriesAsync` Returns the complete list of Google Trends categories. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | - | - | - | Function does not require parameters | ## Supported values for `timeRange` `timeRange` is case-insensitive and supports the following values: | Value | Description | | --- | --- | | `LastHour` | last hour | | `LastFourHours` | last 4 hours | | `LastDay` | last 24 hours | | `LastWeek` | last 7 days | | `LastMonth` | last 30 days | | `LastThreeMonths` | last 90 days | | `LastYear` | last 12 months | | `LastFiveYears` | last 5 years | | `FromStart` | all available historical data | If the value is invalid or missing, the default value `LastThreeMonths` will be used. ## Invocation Context The behavior of the connection can be influenced by the invocation context: | Field | Default value | Description | | --- | --- | --- | | `Language` | `en-US` | Language of results | | `Timezone` | `300` | Timezone offset in minutes | Example: ```yaml Language: en-US Timezone: 300 ``` ## Data Source Strategy For endpoints working with trending searches, data retrieval occurs in two steps: 1. Attempt to obtain data from the Google Trends API. 2. If the API does not respond or returns incomplete data, the system automatically uses the Google Trends RSS feed. This mechanism ensures higher data availability. ## Limits | Limitation | Value | | --- | --- | | Number of keywords in a query | 1-5 | | Comparison of keywords | 2-5 | | Default time period | `LastThreeMonths` | ## Summary The Google Trends connection is suitable for analytical use cases, topic monitoring, marketing workflows, and comparing trends over time. It provides a unified interface for working with Google Trends data, including a fallback strategy for trending searches. ## Technical Notes - **Implementation**: The connection exposes Google Trends research functions. - **Authentication/scopes**: uses configured Trends access; no customer account OAuth scope is required for public trend data. - **Functions**: interest over time, interest by region, keyword comparison, trending searches, today/all trends, related queries/topics, keyword suggestions, and categories. - **Write behavior**: read-only. Trend data is directional and should not be treated as exact search volume. --- # HubSpot

HubSpot

## Connecting HubSpot with Siesta AI 1. In **Connections**, select **Add Connection** and choose **HubSpot**. 2. Enter the **Private App token** (API key) and set it to **Shared** or **Private**. ![Setting Up HubSpot Connection in Siesta AI](/img/connections/hubspot-connection.png) 3. In HubSpot, open **Settings -> Integrations -> Private Apps** and create a new app. ![List of Private Apps in HubSpot](/img/connections/hubspot-private-apps.png) 4. Fill in the basic information for the app. ![Basic Information for Private App](/img/connections/hubspot-app-basic-info.png) 5. Set the required scopes for CRM objects. ![Scopes for Private App](/img/connections/hubspot-app-scopes.png) 6. In the **Auth** tab, copy the **Access token** and use it in Siesta AI. ![Access token in HubSpot Auth](/img/connections/hubspot-app-auth.png) ## Overview This Connection provides a standardized interface for working with HubSpot CRM. It allows for the creation and reading of basic CRM entities: Companies, Contacts, Deals, and Pipelines. The integration is designed to be stateless, deterministic, and fail-fast, suitable for: - CRM automation - Lead synchronization - Sales and revenue pipeline orchestration - Auditable enterprise workflows ## Authentication and Security - The connection communicates exclusively through the official HubSpot API. - Authentication is handled at the HubSpot account level (OAuth / Private App token). - No sensitive data is logged or cached. - All operations run with permissions assigned in HubSpot. Access rights (scopes) directly affect the availability of operations. Incorrect scopes result in failure. ## Supported Entities - Company - Contact - Deal - Pipeline Each operation works with internal HubSpot IDs, not names. ## 1. Company Operations ### 1.1 CreateCompany **Description** Creates a new company in HubSpot CRM. **Input Parameters** | Parameter | Type | Required | Description | |-----------|---------|----------|-----------------------------------------| | name | String | Yes | The name of the company. | | domain | String | Yes | The company's domain (must be unique). | **Behavior** - If the domain already exists, the operation fails. - Does not perform fuzzy matching or domain normalization. **Typical Use Cases** - Onboarding new customers - Synchronizing companies from external systems ## 2. Contact Operations ### 2.1 CreateContact **Description** Creates a new contact in HubSpot CRM. **Input Parameters** | Parameter | Type | Required | Description | |------------|---------|----------|-----------------------------------------| | email | String | Yes | The contact's email (must be unique). | | firstName | String | Yes | First name. | | lastName | String | Yes | Last name. | **Behavior** - Email serves as a unique identifier. - Duplicate email = hard error. ### 2.2 GetContactByEmail **Description** Returns a contact based on the email address. **Input Parameters** | Parameter | Type | Required | |-----------|---------|----------| | email | String | Yes | ### 2.3 GetContactById **Description** Returns a contact by its unique HubSpot ID. **Input Parameters** | Parameter | Type | Required | |------------|--------|----------| | contactId | Int64 | Yes | ### 2.4 GetAllContacts **Description** Returns a list of contacts in HubSpot CRM. **Input Parameters** | Parameter | Type | Required | Description | |-----------|------|----------|-----------------------------------------| | limit | Int | No | Maximum number of returned records. | ## 3. Deal Operations ### 3.1 CreateDeal **Description** Creates a new deal and assigns it to a specific contact. **Input Parameters** | Parameter | Type | Required | Description | |-------------|---------|----------|---------------------------------------| | dealName | String | Yes | The name of the deal. | | contactId | String | Yes | Existing Contact ID. | | pipelineId | Int64 | Yes | Pipeline ID (not name). | | stageId | Int64 | Yes | Stage ID (not name). | | amount | Int | No | The value of the deal. | **Behavior** - Both pipeline and stage must exist. - Does not perform automatic mapping of names to IDs. - Incorrect relationship = fail. ### 3.2 GetDealById **Description** Returns deal details by ID. **Input Parameters** | Parameter | Type | Required | |-----------|--------|----------| | dealId | Int64 | Yes | ### 3.3 GetAllDeals **Description** Returns a list of deals. **Input Parameters** | Parameter | Type | Required | |-----------|------|----------| | limit | Int | No | ## 4. Pipeline Operations ### 4.1 ListAllPipelines **Description** Returns all pipelines including their stages and corresponding IDs. **Input Parameters** None. **Note** This step is mandatory if you do not want to create deals blindly. ## 5. Search Operations ### 5.1 SearchCompanies **Description** Searches for companies by name. **Input Parameters** | Parameter | Type | Required | Description | |-----------|---------|----------|-----------------------------------------| | name | String | No | The name of the company (without domain). | **Restrictions** - Do not use domains, URLs, or emails. - The search is textual, without fuzzy matching. ## Technical Notes - **Implementation**: The connection exposes CRM object operations. - **Authentication/scopes**: uses a HubSpot private app token/API credential. The token must include object scopes for contacts, companies, deals, and pipelines matching enabled functions. - **Functions**: create contacts, companies, and deals; get contacts, companies, and deals; list contacts, deals, and pipelines; and search companies. - **Write behavior**: creating CRM records affects sales/customer data. Confirm deduplication rules and required properties before enabling write actions. --- # Jira

Jira

## Overview The Jira connection allows for a secure integration of the Siesta AI platform with Atlassian Jira via the official API. The integration provides controlled access to Jira projects and issues and enables: - creating issues, - searching and loading issues, - updating existing issues, - assigning issues to users, - searching users before assignment, - reviewing and updating fix versions on released work. Designed for: - incident and ops automation, - engineering workflows orchestration, - synchronization of external systems (CRM, monitoring, AI agents), - auditable ticket-based processes. ## Requirements - An active **Jira Cloud** site. - An Atlassian account that has access to the Jira projects the connection will work with. - A generated **API token** in the Atlassian account (`id.atlassian.com` → **Security** → **API tokens**). - Administrator permissions to manage the connection in Siesta AI. ## Supported Operations | Operation area | What it covers | | --- | --- | | Ticket creation | Create a new issue in a selected project and issue type. | | Ticket retrieval and search | Get one issue, list issues by project, list issues by user helper flows, and search with JQL. | | Ticket updates | Update existing issues, including summary, description, and fix-version fields where available. | | Assignee resolution | Search Atlassian users and load user details so the correct `AccountId` can be used for assignment. | | Ticket assignment | Assign an issue to a resolved Atlassian account. | | Project listing | List Jira projects available to the connected account. | ## Configuration Parameters ### Required Parameters | Parameter | Description | | --- | --- | | **Name** | Internal designation of the connection | | **ApiKey** | API token generated in the Atlassian account | | **Email or username of Atlassian account** | Email (or username) of the account under which the token was created | | **URL** | URL of the Jira/Atlassian instance (e.g., `https://company.atlassian.net`) | ## Steps to Add the Jira Connection ### 1) Prepare Your Access Credentials Before you start creating the connection in Siesta AI, prepare all the values you will enter into the form. In your Atlassian account, open **Security** and the **API Tokens** section. ![Atlassian API Tokens](/img/connections/atlassian-api-tokens.png) Click on **Create API token** (without scopes), enter the token name and expiration, and confirm the creation. ![Creating Atlassian API token](/img/connections/atlassian-create-api-token.png) After creating the token, copy it once and store it securely. ![Copying Atlassian API token](/img/connections/atlassian-copy-api-token.png) Then prepare: - **Email or username** of the Atlassian account under which the token was created - **URL of the Jira/Atlassian instance** (e.g., `https://company.atlassian.net`) ### 2) Open Integration Management in Siesta AI In the Siesta AI administration, go to **Administration → Connected Apps**. ### 3) Select Jira In the **Add Connection** dialog, select **Jira** and proceed. ### 4) Fill Out the Jira Form Fill in: - **Name** - **ApiKey** (token from Atlassian) - **Email / username** of the Atlassian account under which the token was created - **URL** (e.g., `https://company.atlassian.net`) Confirm the creation of the integration. ![Configuring Jira integration](/img/connections/siesta-ai-jira-form.png) ### 5) Set Operation Permissions After creating the integration, open **Permission Settings** and set the allowed operations. Recommendation: set write operations to **Allowed with confirmation**. ![Setting Jira operation permissions](/img/connections/jira-operations.png) ### Important Note on API Token and Permissions The API token is tied to a specific Atlassian account. The connection then inherits the permissions of this account in Jira (what the account cannot see or modify, the connection cannot either). For this reason, it is recommended: - that each user has their own token if the connection runs under their identity, - or to use a dedicated service account for shared/production automation, - to monitor the token's expiration and perform regular rotation. ## Authentication and Security - The connection uses the official Jira REST API. - Authentication of the connection occurs via the Atlassian account and API token (entered in the `ApiKey` field). - Permissions are managed directly at the Jira instance level. - For working with assignees, the Jira API uses `AccountId` (not email), so user-search or user-detail lookups should be used before assignment when the correct account ID is not already known. If a user does not have the right to see an issue, the connection will not see it either. ## Basic Terms - **IssueKey**: Ticket ID (e.g., `PROJ-123`). - **ProjectKey**: Key of the Jira project (e.g., `PROJ`). - **AccountId**: Unique identifier of a user in the Atlassian ecosystem. - **JQL**: Jira Query Language. ## 1. Ticket Creation ### 1.1 CreateTicketAsync **Description** Creates a new Jira issue in the specified project. **Input Parameters** | Parameter | Type | Required | Description | |-------------|--------|---------|------------------------------------| | projectKey | String | Yes | Key of the Jira project. | | issueType | String | Yes | Type of issue (Task, Bug, Story, ...). | | summary | String | Yes | Short title of the issue. | | description | String | No | Detailed description. | | assigneeId | String | No | Atlassian Account ID of the user. | **Behavior** - IssueType must exist in the project. - No fallback or type mapping is performed. - Incorrect combination = fail. ## 2. Ticket Assignment ### 2.1 AssignTicketAsync **Description** Assigns an existing issue to a specific user. **Input Parameters** | Parameter | Type | Required | |--------------------|--------|---------| | issueKey | String | Yes | | assigneeAccountId | String | Yes | **Note** Jira ignores emails. Account ID is the only reliable identifier. ## 3. Ticket Retrieval ### 3.1 GetTicketAsync **Description** Returns the details of an issue by `issueKey`. **Input Parameters** | Parameter | Type | Required | |----------|--------|---------| | issueKey | String | Yes | ### 3.2 GetTicketsByProjectAsync **Description** Returns issues belonging to a specific project. **Input Parameters** | Parameter | Type | Required | |------------|-----|---------| | projectKey | String | Yes | | maxResults | Int | No | ### 3.3 GetTicketsByUserAsync **Description** Returns issues assigned to a specific user helper input. **Input Parameters** | Parameter | Type | Required | |---------------|-----|---------| | assigneeEmail | String | Yes | | maxResults | Int | No | **Usage note** - Prefer `SearchUsersAsync` and `GetUserAsync` when the workflow needs a reliable Atlassian identity for assignment or cross-checking. - Treat email-based helper flows as a convenience for search/listing, not as the source of truth for assignment. ## 4. Ticket Update ### 4.1 UpdateTicketAsync **Description** Updates the summary, description, labels, priority, and fix versions of an existing issue. **Input Parameters** | Parameter | Type | Required | |-------------|--------|---------| | issueKey | String | Yes | | summary | String | No | | description | String | No | | fixVersions | String | No | **Behavior** - Only provided fields are updated. - No validation of workflow status is performed. ## 5. Search and Query ### 5.1 SearchTicketsAsync **Description** Searches for issues using a JQL query. **Input Parameters** | Parameter | Type | Required | |------------|--------|---------| | jql | String | Yes | | maxResults | Int | No | **Example JQL** ``` project = PROJ AND status = "To Do" ``` Incorrect JQL returns an immediate error. ## 6. Project and User Operations ### 6.1 GetAllProjectsAsync **Description** Returns a list of projects available to the current user. **Input Parameters** | Parameter | Type | Required | |------------|-----|---------| | maxResults | Int | No | ### 6.2 GetUserAsync **Description** Returns information about a user by Account ID. **Input Parameters** | Parameter | Type | Required | |-----------|--------|---------| | accountId | String | Yes | ### 6.3 SearchUsersAsync **Description** Searches Atlassian users so the correct assignee can be selected before ticket creation or reassignment. **When to use it** - when the agent only knows part of a person name or email, - when you need the correct Atlassian `AccountId`, - before calling create or assign operations that require account-based identity. ## Design Principles - Account ID > email (GDPR and Atlassian reality). - Explicit inputs without assumptions. - Fail-fast behavior on erroneous requests. - Respect for Jira workflow rules. ## Summary The Jira Connection provides direct, secure, and auditable access to Jira issues and projects. It is suitable for automated ticketing, incident agents, engineering productivity tooling, and enterprise workflows integration. ## Technical Notes - **Implementation**: The connection exposes Jira issue and project operations. - **Authentication/scopes**: uses Atlassian site URL, username, and API token/basic auth. Jira project permissions determine issue visibility, assignment, creation, and editing rights. - **Functions**: create issues, update issues, search with JQL, get issue details and changelog, list project/user issues, search users, assign issues, get user details, and list projects. - **Write behavior**: issue creation, edits, fix-version changes, and assignment can trigger workflows or release notifications. Confirm project, issue type, assignee, and version fields before execution. --- # LinkedIn

LinkedIn

The **LinkedIn** connection allows agents to work with LinkedIn advertising accounts, campaign groups, campaigns, creatives, and reporting. It is suitable for marketing teams that want to analyze or manage LinkedIn Ads through agents and workflows. ## When to Use It Use it to find advertising accounts, get an overview of campaigns, check budgets, prepare reports, or manage changes in campaigns. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **LinkedIn**. 3. Log in to the account that has access to the correct LinkedIn Ads account. 4. Verify that the agent sees the correct ad account. 5. For change functions, enable confirmation. ## What the Tool Can Do - list available advertising accounts, - read campaign groups and campaigns, - create and edit campaign groups, - work with campaigns and creatives, - obtain performance data for reporting. ## Security and Confirmation Changes to campaigns and budgets can affect spend. Always require confirmation for creating and editing campaigns, creatives, or campaign groups. ## Example Usage > Find LinkedIn campaigns with low CTR over the last 14 days and suggest adjustments. Do not make any changes without confirmation. Verify the result in the LinkedIn Campaign Manager and in **Launch Tools**. ## Technical Notes - **Implementation**: The connection exposes LinkedIn Ads account, campaign, creative, and conversion functions. - **Authentication/scopes**: uses LinkedIn OAuth. Reporting functions require ads reporting access; management/conversion functions require ads or conversion write permissions such as `r_ads_reporting`, `r_ads`/`rw_ads`, and `rw_conversions` depending on the enabled action. - **Functions**: list ad accounts, inspect campaigns and creatives, read analytics, and manage campaign/conversion-related resources exposed by the tool. - **Write behavior**: campaign and conversion changes can affect paid media delivery and measurement, so restrict write access to marketing admins or power users. --- # Microsoft Fabric

Microsoft Fabric

The **Microsoft Fabric** connection lets agents work with your Fabric workspace: items, artifacts, and platform metadata exposed by Fabric's own tools. It is added through the standard [MCP](#doc-connections-mcp) connection and authorized with Microsoft OAuth, so there is no dedicated native module. ## When to Use It Use it when an agent needs to inspect or operate on Fabric content (workspaces and items) directly, or feed Fabric context into an agent or workflow, rather than exporting to a file first. ## Setup Microsoft Fabric is added as an [MCP](#doc-connections-mcp) connection. 1. In **Connections**, click **Add Connection** and select **MCP**. 2. Fill in: - **Name**: for example `Fabric`. - **Server URL**: `https://api.fabric.microsoft.com/v1/mcp/core` 3. Click **Continue** and complete the Microsoft login to create the connection. ![Fabric MCP connection setup with the server URL field](/img/connections/microsoft-fabric-connection-setup.png) After the login completes, use **Load methods** to fetch the tools published by the Fabric MCP server. ## What the Tool Can Do The functions are published by the Fabric MCP server rather than by a fixed module, so the exact set depends on your tenant. After connecting, load the methods and review each one to confirm what it does and whether it reads or writes. ## Security and Confirmation The connection operates with the permissions of the account that completed the OAuth login: it can only reach the workspaces and items that account can. Governing individual functions works the same as for any [MCP](#doc-connections-mcp) connection. ## Example Use > List the items in my Fabric workspace and summarize what each one is for. Do not modify anything without confirmation. Any execution can be reviewed in **Run Tools**. ## Technical Notes - **Implementation**: exposed through the standard [MCP](#doc-connections-mcp) connection; the tool set is served at `https://api.fabric.microsoft.com/v1/mcp/core`. - **Authentication/scopes**: OAuth through the Microsoft provider using auto-discovery, so the OAuth definition is provided by the tool. The connection uses the permissions of the signed-in account. - **Functions**: defined by the Fabric MCP server; each published tool maps to a callable function with its own parameters and write behavior. --- # Microsoft Outlook

Microsoft Outlook

The **Microsoft Outlook** connection uses Microsoft OAuth and Graph to work with the connected user's mailbox. It lets agents read inbox context, create drafts, and send mail from the connected account, with confirmation on writes. ## When to Use It Use it when an agent needs to read recent inbox context, inspect a specific message, create a draft, or send an approved email through a governed Microsoft account. ## Setup 1. In **Connections**, click **Add Integration** and choose **Microsoft Outlook** from the Microsoft provider group. 2. Sign in with the Microsoft account that should read, draft, or send messages. The tool uses Microsoft Graph through OAuth. 3. Decide private or shared access. Use private access for personal mailboxes, and shared access only for team-owned mailboxes or approved operational accounts. 4. Require review for writes. Sending email and creating drafts are data-modifying functions, so keep confirmation enabled for production and customer-facing workflows. ## What the Tool Can Do - **List inbox messages.** Returns the most recent messages from the inbox, with an optional setting to include junk and deleted items. - **Get message details.** Retrieves the full content of a specific email by Microsoft Graph message ID. - **Create an email draft.** Creates a draft with recipient, subject, and body. Use this for review-first workflows before anything is sent. - **Send email.** Sends an email from the connected Outlook account and saves it to sent items. Treat this as a write action. ## Security and Confirmation Sending email and creating drafts modify the connected mailbox, so keep confirmation enabled for customer-facing workflows. Before you enable sending, confirm that: - The connected account is the mailbox that should appear as sender. - Shared access is limited to team-owned or approved operational mailboxes. - Send email requires human approval for customer-facing workflows. - Draft creation is preferred when the user should review wording first. - The agent prompt states tone, audience, recipient, and source context. - Tool Runs are reviewed when a send, draft, or inbox read behaves unexpectedly. ## Example Usage ```text Find the latest email from acme@example.com, summarize the request, and draft a reply. Do not send it until I approve the subject and body. ``` ```text Create a polite follow-up draft for this customer. Use the attached context, keep it under 120 words, and show me the draft before saving it. ``` ```text List my last 10 inbox messages and identify anything that looks like a renewal, support escalation, or meeting follow-up. ``` ## Technical Notes | Area | Details | | --- | --- | | Tool | `MicrosoftOutlook` in `Siesta.AI.Tools.Outlook` | | Auth | Microsoft OAuth token resolved through the common OAuth service | | API | Microsoft Graph `Me` mailbox endpoints | | Read functions | List recent inbox messages, get a specific message by ID | | Write functions | Create draft, send email with `SaveToSentItems = true` | | Body handling | Plain text input is converted to HTML before Graph sends or saves the message | ## Common Problems | Symptom | Likely cause | Fix | | --- | --- | --- | | Agent cannot read inbox | OAuth token expired or mailbox permission changed | Reconnect Microsoft Outlook from the connection detail. | | Email sent from wrong account | The wrong Microsoft account was authorized | Recreate or reconnect the connection with the intended mailbox. | | Send is blocked | Function policy requires approval or disables sending | Approve the pending action or ask an admin to review governance. | | Message details fail | The message ID is stale or belongs to a mailbox the connection cannot access | Ask the agent to list current inbox messages again and retry with the returned ID. | --- # Money S3

Money S3

The Money S3 connection allows agents and workflows to work with selected accounting and ERP data from Money S3. It is typically used for reading directories, orders, and invoices or for creating selected documents according to the settings of the customer installation. ## Prerequisites Money S3 is not a standard purely cloud service. Before connecting, the customer's Money S3 environment must be prepared: - active Money S3 API module, - installed and available S3Api service, - configured API domain or local API endpoint, - created API key with Client ID and Client Secret, - Money S3 user assigned to the API key if using Client Credentials mode, - configured XML import queue for processing entries. Without a properly set up queue, entries may be accepted into the queue but will never actually be created in the accounting system. ## Quick Connection 1. In the **Connections** section, click on **Add Connection**. 2. Select **Money S3**. 3. Enter the Money S3 API domain or endpoint. 4. Insert the Client ID, Client Secret, and other required information according to your Money S3 settings. 5. Name the connection and save it. ## What the Connection Can Do - Read selected accounting and business data, such as directories, orders, or issued invoices. - Create selected documents if the connection has the necessary permissions. - Support automation over ERP data, such as order verification, customer synchronization, or document preparation. ## Important Principles - Money S3 API uses GraphQL over HTTP. - Entries are asynchronous. A successful response means the request has been accepted into the queue, not a guarantee that the document has already been created in Money S3. - When writing, save the operation identifier to verify the processing result later. - Errors may occur during later queue processing, for example, due to number series, accounting configuration, VAT, or validation rules. ## Security and Permissions Use a separate API key for Siesta AI and assign it only the necessary permissions. Production and testing Money S3 environments should have separate accesses. Regularly rotate the Client Secret and recreate the connection if there is suspicion of a leak. ## Recommended Use The Money S3 connection is suitable for automating invoices, orders, synchronizing business partners, and auditable workflows over ERP data. For accounting entries, we recommend using a clear approval step or control workflow. ## Technical Notes - **Implementation**: Money S3 is documented as a configured accounting/API integration; exact implementation depends on the customer setup. - **Authentication/scopes**: depends on the Money S3/API credentials and the accounting permissions assigned to the integration account. - **Functions**: expected functions depend on the configured API surface, such as reading accounting documents, contacts, invoices, orders, or creating/updating records where enabled. - **Write behavior**: accounting writes can have financial and audit impact. Use read-only credentials by default and require confirmation for any mutation. --- # Office 365 Excel

Office 365 Excel

The **Office 365 Excel** connection allows agents to create Excel files in OneDrive, read existing spreadsheets, and append or replace their content with CSV data. ## When to Use It Use it for simple reports, exports, spreadsheet summaries, and workflows where an agent needs to create or supplement an Excel file. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Office 365 Excel**. 3. Sign in with a Microsoft account that has access to OneDrive. 4. Review the permission scope and save the connection. 5. Assign the connection to an agent or workflow. ## What the Tool Can Do - create a new Excel spreadsheet, - find a spreadsheet by name, - load a spreadsheet by OneDrive item ID, - add rows to an existing file, - replace the content of an existing file with CSV data. ## Security and Confirmation Creating, appending, and replacing content modifies files in OneDrive. Enable confirmation for actions that write data, especially for shared reports and production materials. ## Example Usage > Create an Excel report from these orders and save it to my OneDrive. Show me the file name and columns before creating it. Verify the result in OneDrive or in **Run Tools**. ## Technical Notes - **Implementation**: The connection exposes Excel workbook operations through Microsoft 365/Graph. - **Authentication/scopes**: uses Microsoft OAuth/Graph file access. The connected account must have permission to read or edit the target workbook. - **Functions**: create spreadsheets, find spreadsheets by name or ID, append rows by ID, update spreadsheet content by ID, and list spreadsheets. - **Write behavior**: create, append, and update actions modify files in Microsoft 365. Confirm workbook identity before editing shared files. --- # Office 365 Word

Office 365 Word

The **Office 365 Word** connection allows agents to create Word documents in OneDrive, read existing documents, and supplement or replace their content. ## When to Use It Use it for generating minutes, briefs, contract proposals, reports, or documents that need to be created directly in the Microsoft 365 environment. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Office 365 Word**. 3. Sign in with a Microsoft account that has access to OneDrive. 4. Check whether the agent should work with a private or shared connection. 5. Save the connection and assign it to an agent or workflow. ## What the Tool Can Do - create a new Word document, - find a document by name, - load a document by OneDrive item ID, - add text to an existing document, - replace the content of an existing document. ## Security and Confirmation Writing to documents can overwrite important content. Always enable confirmation for content replacement and prompt the agent to show a draft of the change beforehand. ## Example Usage > Prepare a Word minute from the meeting and show me the outline and proposed document title before saving. Verify the result in OneDrive or in **Run Tools**. ## Technical Notes - **Implementation**: The connection exposes Word document operations through Microsoft 365/Graph. - **Authentication/scopes**: uses Microsoft OAuth/Graph file access. The connected account must have permission to read or edit the target document. - **Functions**: create documents, find documents by name or ID, append content, update document content, and list documents. - **Write behavior**: document creation and updates modify Microsoft 365 files directly. Confirm target document before replacing or appending content. --- # OneDrive

OneDrive

The **OneDrive** connection lets agents search for files and read their content from the connected user’s OneDrive. Use it when an agent should look up an existing document, read a shared Microsoft file by URL, or summarize stored material without creating or editing files. ## When to Use It Use it when an agent needs to: - find a file by name, - browse files inside a folder, - read a file by OneDrive-relative path, - read a file from a full Microsoft sharing URL, - summarize or extract information from an existing document. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **OneDrive**. 3. Sign in with a Microsoft account that has access to the intended OneDrive files. 4. Review whether the connection should stay private or be shared. 5. Save the connection and attach it only where OneDrive access is actually needed. ## What the Tool Can Do - list accessible files from OneDrive root or from a selected folder, - search files by file name, - read a file by exact or partial file name, - read a file by a OneDrive-relative path such as `Documents/Finance/Q2-report.docx`, - read a file by a full Microsoft URL. ## Read-Only Behavior The released OneDrive tool surface is **read-only**. It does not create, update, rename, or delete files in this release. Use this connection when the job is document discovery and reading. Use these related connections when the agent must write files: - [Office 365 Word](#doc-connections-office365-word) - [Office 365 Excel](#doc-connections-office365-excel) If the content lives in a team site rather than in a user drive, consider [SharePoint](#doc-connections-sharepoint) instead. In practice: - use **OneDrive** to find and read existing files, - use **Office 365 Word** when the agent should create or rewrite Word documents, - use **Office 365 Excel** when the agent should create, append, or replace spreadsheet-style content. ## Path and URL Examples Typical file-path input: - `Documents/Onboarding/Welcome-pack.docx` - `Shared/Reports/Customer-summary.pdf` Typical URL input: - full `onedrive.live.com` or Microsoft file URLs, - `sharepoint.com` document URLs shared by a user, - file links copied directly from Microsoft 365. If the agent already has the exact document URL, using the URL form is usually more reliable than searching by a broad file name. Use file-name search when the user knows roughly what the document is called. Use path input when the folder structure is known. Use URL input when a copied Microsoft 365 link is already available and you want to avoid ambiguity. ## Security and Confirmation The connection is read-only, but it can still expose sensitive business content. Keep it scoped to the same audience that could already open those files in Microsoft 365. Recommended rules: - avoid attaching OneDrive broadly to public-facing agents, - use a dedicated account when the files represent a shared business source, - verify the returned file identity before trusting a summary based on a partial file name match. ## Example Usage > Find the latest customer onboarding deck in my OneDrive and summarize the sections that explain implementation timing. > Read this Microsoft document URL and extract only the action items and due dates. ## Technical Notes - **Implementation**: the connection exposes OneDrive search and file-reading operations through Microsoft Graph. - **Authentication/scopes**: uses Microsoft OAuth/Graph access. The connected account must already have permission to the target file. - **Functions**: list files, read file by name or path, and read file by full Microsoft URL. - **Write behavior**: none in this release. If the use case requires file creation or editing, use an appropriate Microsoft 365 writing connection instead. --- # Power BI

Power BI

The **Power BI** connection lets agents query your Power BI datasets through Power BI's own tools. It is added through the standard [MCP](#doc-connections-mcp) connection and authorized with Microsoft OAuth, so there is no dedicated native module. ## When to Use It Use it when an agent needs to run queries against Power BI datasets or bring Power BI results into a conversation or workflow, rather than exporting data to a file first. ## Setup Power BI is added as an [MCP](#doc-connections-mcp) connection. 1. In **Connections**, click **Add Connection** and select **MCP**. 2. Fill in: - **Name**: for example `PowerBI`. - **Server URL**: `https://api.fabric.microsoft.com/v1/mcp/powerbi` 3. Click **Continue** and complete the Microsoft login to create the connection. :::warning Recommended: disable GenerateQuery After creating the connection, open its details and set the **GenerateQuery** function to **Disabled**. This function requires a **Copilot licence**, so if you do not have one, disabling it avoids confusing agents. Leave **ExecuteQuery** enabled. ::: ![Power BI MCP connection with the GenerateQuery function disabled](/img/connections/power-bi-disable-generatequery.png) ## What the Tool Can Do The functions are published by the Power BI MCP server: - **ExecuteQuery**: run a query against a dataset the connected account can access. - **GenerateQuery**: generate a query from natural language. This requires a **Copilot licence** and is recommended to disable if you do not have one. ## Security and Confirmation Queries run with the permissions of the account that completed the OAuth login: the connection can only reach the workspaces and datasets that account can. Governing individual functions works the same as for any [MCP](#doc-connections-mcp) connection. ## Example Use > Run a query against the Sales dataset in Power BI and summarize revenue by region for this quarter. Any execution can be reviewed in **Run Tools**. ## Technical Notes - **Implementation**: exposed through the standard [MCP](#doc-connections-mcp) connection; the tool set is served at `https://api.fabric.microsoft.com/v1/mcp/powerbi`. - **Authentication/scopes**: OAuth through the Microsoft provider using auto-discovery, so the OAuth definition is provided by the tool. The connection uses the permissions of the signed-in account. - **Functions**: `ExecuteQuery`, and `GenerateQuery` (requires a Copilot licence; recommended to disable if unavailable). --- # Seznam Sklik

Seznam Sklik

The **Seznam Sklik** connection allows agents to read and manage Sklik accounts, campaigns, ad groups, ads, keywords, targeting, bidding, and performance data. It is designed for PPC teams that want to analyze campaigns or make controlled changes through agents. ## When to Use It Use it for reporting, performance monitoring, troubleshooting campaign issues, proposing optimizations, or making cautious changes to campaigns, ad groups, and ads. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **Seznam Sklik**. 3. Fill in the login or API details according to your organization's settings. 4. Verify that the account sees the correct Sklik accounts. 5. Enable confirmation for all change functions. ## What the Tool Can Do - load account, credit, and statistics information, - list campaigns, ad groups, ads, keywords, and targeting, - create and edit campaigns, ad groups, and ads, - work with bidding and campaign status, - prepare performance reports. ## Security and Confirmation Sklik functions can affect spend and running ads. Require confirmation for all changes to campaigns, budgets, bids, ads, and targeting. For analysis, use a read-only prompt: the agent should propose changes, not execute them directly. ## Example Usage > Review Sklik campaigns from the last 30 days, find ad groups with high spend and low conversion, and suggest changes without implementing them. Verify the results in the Sklik administration and in **Run Tools**. ## Technical Notes - **Implementation**: The connection provides Sklik advertising API access. - **Authentication/scopes**: uses Sklik API credentials/token and the connected advertising account permissions. - **Functions**: exposes Sklik account, campaign, ad group, keyword, reporting, or management operations available through the configured tool surface. - **Write behavior**: advertising changes can affect delivery and spend. Require confirmation for campaign, bid, budget, targeting, or creative changes. --- # SharePoint

SharePoint

The **SharePoint** connection allows agents to search for files by name and read their content from SharePoint. It is useful for working with internal documentation, project materials, and shared files. ## When to Use It Use it when an agent needs to respond based on files stored in SharePoint, find the correct document, or summarize the content of internal materials. ## Setup 1. In **Connections**, click on **Add Integration**. 2. Select **SharePoint**. 3. Sign in with a Microsoft account that has access to the desired SharePoint space. 4. Check permissions and access scope. 5. Assign the connection to an agent or workflow. ## What the Tool Can Do - search for files by name, - load the content of the selected file. ## Security and Confirmation The functions are read-only, but they can expose sensitive internal documents. Share the connection only with agents and users who should have access to the same content. ## Example Usage > Find the latest version of the onboarding document in SharePoint and summarize the steps that the new team member should complete in their first week. Verify the result in SharePoint and in **Run Tools**. ## Technical Notes - **Implementation**: The connection exposes SharePoint file discovery and reading. - **Authentication/scopes**: uses Microsoft OAuth/Graph access. Site, library, and file permissions determine what the connected account can read. - **Functions**: list files, search files, and read file content. - **Write behavior**: the current SharePoint tool surface is read-only, but file contents can be sensitive and should only be attached to agents with an explicit use case. --- # Shopify

Shopify

The Shopify connection allows agents and workflows to work with data from the Shopify store. Siesta AI can read products, orders, customers, and inventory according to the granted permissions, and can also create or modify selected records. ## Quick Connection 1. In the **Connections** section, click on **Add Connection**. 2. Select **Shopify**. 3. Enter the access details for your Shopify store according to the chosen authentication method. 4. Enable the necessary scopes, such as reading products, orders, or customers. 5. Name the connection and save it. ## What the Connection Can Do - List products and load product details. - Create, modify, or delete a product if the connection has write permissions. - List orders and load order details. - List customers and load customer details. - Work with articles or store content if the corresponding scopes are available. ## Important Principles - Shopify resources have stable numeric IDs. In automations, use IDs instead of names or handles, as names may change. - The Shopify API is versioned. Production connections should use a specific API version and regularly update it before support ends. - List operations use pagination. For larger stores, expect that the agent or workflow must go through multiple pages of results. - Shopify limits the number of API calls. If the service returns a rate limit, repeat the action later or slow down the workflow. ## Security and Permissions Assign only the scopes that correspond to the intended use. Write permissions are not needed for reading the catalog. For operations that change products, orders, or store content, we recommend human confirmation or clearly limited workflows. ## Recommended Use The Shopify connection is suitable for synchronizing e-commerce data, analyzing the catalog, preparing marketing materials, checking orders, and automating processes related to products or customers. ## Technical Notes - **Implementation**: Shopify is documented as a configured Shopify Admin API integration; exact implementation depends on the customer setup. - **Authentication/scopes**: depends on the Shopify app/private token scopes granted by the store admin, typically separated across products, orders, customers, inventory, and write operations. - **Functions**: expected functions depend on the configured API surface, such as reading products/orders/customers and, where enabled, creating or updating store records. - **Write behavior**: order, product, customer, and inventory writes affect the live store. Use least privilege and confirmations for any state-changing function. --- # Shoptet

Shoptet

The Shoptet connection allows agents and workflows to work with data from the Shoptet e-shop. Siesta AI can read products, orders, customers, stock information, and invoices, and can create or modify selected records according to the connection permissions. ## Quick Connection 1. In the **Connections** section, click on **Add Connection**. 2. Select **Shoptet**. 3. Choose the available authentication method for your e-shop. 4. Grant the required permissions or insert a private API token. 5. Name the connection and save it. ## What the Connection Can Do - Load information about the e-shop, currency, language, and configuration. - List products, load product details, and work with the catalog. - Create, modify, or delete a product if the connection has write permissions. - List orders, load order details, and change the order status. - Work with customers, stock items, and other e-commerce data according to available permissions. ## Important Principles - Use products by GUID, and orders by order code. Treat the order code as text, even if it looks like a number. - OAuth connections use a short-lived API access token. If it expires, Siesta AI must obtain a new token. - The private API token is a static token created in the e-shop administration. Treat it as sensitive information. - List operations are paginated. For larger e-shops, loading all data may require multiple API calls. - Shoptet uses rate limits. If the limit is exceeded or concurrent writes occur, the service may return an error, and the workflow should retry the action later. ## Security and Permissions For typical analytical scenarios, use only read permissions. Enable write permissions only where the agent or workflow actually creates or modifies products and orders. For deletions or bulk changes, human confirmation is recommended. ## Recommended Use The Shoptet connection is suitable for e-commerce reporting, order synchronization, catalog control, automated order processing, and working with customer data within the allowed permissions. ## Technical Notes - **Implementation**: Shoptet is documented as a configured API integration; exact implementation depends on the customer setup. - **Authentication/scopes**: depends on the Shoptet API token/app permissions granted for the e-shop. - **Functions**: expected functions depend on the configured API surface, such as reading products, orders, customers, stock, and creating or updating records where enabled. - **Write behavior**: e-commerce writes can affect storefront data and fulfillment, so restrict write actions and require confirmation. --- # Slack

Slack

Slack connects Siesta AI with team conversations so agents can help prepare updates, summarize channel context, and support operational workflows that depend on Slack messages. ## When to Use It Use the Slack connection when teams need to: - summarize recent channel activity before a meeting, - draft replies or announcements from existing context, - route action items from conversations into tasks or workflows, - keep project updates consistent across teams. ## Setup 1. Open **Connections** in Siesta AI. 2. Select **Add Connection** and choose **Slack**. 3. Start Slack authorization from the Siesta AI connection flow. 4. Complete the Slack OAuth flow for the workspace you want to connect. 5. Review the requested scopes and confirm only the permissions needed for your use case. 6. Save the connection and assign it to the relevant agents or workflows. Do not start by installing the Slack app directly from Slack Marketplace or from a standalone **Add to Slack** button. Creating the Slack connection in Siesta AI first keeps the Slack app installation linked to the correct Siesta AI connection. ## What the Connection Can Do Depending on the enabled scopes, Slack can support reading channel or thread context, preparing message drafts, and posting approved messages. Use narrower permissions for read-only analysis and broader permissions only when an agent must send messages. ## Security and Confirmation Slack messages may contain customer, employee, or commercial information. Require confirmation before an agent posts or updates a message, and limit channel access to the teams that actually need it. ## Recommended Use Start with read-only summarization for a limited set of channels. After the workflow is validated, enable message drafting or posting for trusted agents with clearly defined approval rules. ## Technical Notes - **Implementation**: The connection exposes Slack messaging. - **Authentication/scopes**: uses Slack bot/user token access. The token must be allowed to post into the target channels and the app must be installed in the workspace. - **Functions**: send a message to a Slack channel. - **Write behavior**: Slack sends are visible to users immediately. Confirm channel, audience, and message content before posting. --- # Web Plugin Use the Web Plugin when a Siesta AI agent should live on a website, customer portal, documentation site, or internal tool. This page gives developers the runtime contract, safe test flow, and rollout checks needed to embed the widget without exposing API keys or breaking an existing page. The product settings for the agent live in [Agents > Interfaces](#doc-agents-interfaces). Developers use this page after the agent is configured and the embed needs to be added, tested, or handed to a customer. If the goal is an end-user browsing companion inside Chrome or Edge rather than a website embed, use the [Chrome Extension](#doc-chrome-extension) instead. The extension is a user-facing side-panel surface; the Web Plugin is a developer-facing website integration surface. ## Runtime Contract The widget has a small browser contract: - Load `chat-widget.js` from the Siesta app environment. - Mount one `` custom element. - Pass the public or authenticated agent ID as `data-chatbot-id`. - Pass the matching app host as `data-base-url`. - Use `data-environment="dev"` only for dev or preview agents. - Keep API keys and organization secrets out of browser code. The widget can run on a normal website without the External API. It uses the selected agent's public or authenticated widget configuration from Siesta AI. ## Playground Flow Use the [Widget Playground](#doc-developers-web-plugin-playground) when you want a dedicated docs-hosted sandbox for one widget bubble without colliding with the support widget that runs across the rest of the docs site. ## Quick Embed Production embed: ```html ``` Development preview embed: ```html ``` Use the dev agent for internal checks. Use the production agent only after prompts, allowed origins, privacy links, feedback settings, file upload settings, and public access rules have been reviewed. ## Where To Get Values | Value | Source | Notes | | --- | --- | --- | | `data-chatbot-id` | [Agents > Interfaces](#doc-agents-interfaces) | Copy the agent ID from the agent that should answer visitors. | | `data-base-url` | Siesta app environment | Use `https://app.siesta.ai` for production and `https://app-dev.siesta.ai` for dev. | | `data-environment` | Deployment target | Omit for production. Use `dev` for the dev widget bundle. | | Auth client ID | Agents > Interfaces authenticated widget settings | Required only when the widget should force Google sign-in. | | Privacy link | Public chat settings | Must be set before using the widget on public pages. | ## Test Flow Do not mount a second live test widget directly inside this documentation page. The docs site already runs a Siesta support widget, and two widgets on the same page can make validation misleading. Use this flow instead: 1. Configure the agent in **Agents > Interfaces**. 2. Copy the generated snippet or build one from the contract above. 3. Test the snippet on the [Widget Playground](#doc-developers-web-plugin-playground), a neutral local HTML page, staging website, or another dedicated widget preview surface. 4. If the target website blocks iframe previews, open the real target page and use the DevTools injector below. 5. Confirm the widget opens, sends a message, receives a useful answer, respects allowed files/feedback/realtime settings, and shows the correct privacy link. ## DevTools Injector Use this snippet when a customer website blocks iframe previews or when you need to validate the widget on the real DOM before code is deployed. Paste it into the browser DevTools Console on the target page. ```js (() => { const botId = '06b4e39c-56b7-47e1-2a91-08de539d8b24'; const env = 'prod'; const baseUrl = 'https://app.siesta.ai'; const scriptSrc = baseUrl + '/chat-widget/chat-widget.js'; const mountWidget = () => { document .querySelectorAll('siestaai-chat-widget[data-siesta-preview="true"]') .forEach((el) => el.remove()); const widget = document.createElement('siestaai-chat-widget'); widget.setAttribute('data-chatbot-id', botId); widget.setAttribute('data-base-url', baseUrl); widget.setAttribute('data-environment', env); widget.setAttribute('data-siesta-preview', 'true'); document.body.appendChild(widget); }; if (customElements.get('siestaai-chat-widget')) { mountWidget(); return; } const existingScript = Array.from(document.scripts).find((script) => script.src === scriptSrc); if (existingScript) { customElements.whenDefined('siestaai-chat-widget').then(mountWidget); return; } const script = document.createElement('script'); script.src = scriptSrc; script.defer = true; script.onload = () => customElements.whenDefined('siestaai-chat-widget').then(mountWidget); script.onerror = () => console.error('Siesta widget script failed to load:', scriptSrc); document.head.appendChild(script); })(); ``` Change `botId`, `env`, and `baseUrl` before sharing the snippet with another developer. ## Page Context Injection The widget can be paired with lightweight public page context when the assistant should understand where the visitor is. Keep this context safe: do not include cookies, tokens, hidden form values, account IDs, or private user data. ```html ``` Use page context for lightweight page assistance, documentation support, onboarding, or lead qualification. For reliable answers across a full website, use a data collection, scraper-backed source, or connected knowledge tool instead of relying only on the current DOM. ## Authenticated Widget Use authenticated widget mode for customer portals, intranets, or partner areas where the agent should avoid anonymous access. Configure the authenticated widget in **Agents > Interfaces**, then use the generated script from the product UI. The current developer playground focuses on the manifest-backed public widget contract, so authenticated widget validation should still happen in a dedicated customer or internal test surface. Authenticated deployments should verify: - the Google OAuth client ID belongs to the correct customer or environment, - allowed origins include the target website, - the agent prompt explains what user identity means in this portal, - public access is disabled when anonymous visitors should not use the agent, - privacy and retention settings match the customer's policy. ## Runtime Options | Attribute | Required | Use | | --- | --- | --- | | `data-chatbot-id` | Yes | Selects the Siesta AI agent. | | `data-base-url` | Recommended | Pins the widget to the intended Siesta app host. | | `data-environment` | Dev only | Marks preview widgets that use the dev environment. | | `data-siesta-preview` | Test only | Makes injected preview widgets easy to remove. | | Auth-specific attributes | When enabled | Use the generated authenticated widget snippet from Agents > Interfaces. | ## Rollout Checklist Before customer handoff: - The widget loads without console errors. - The launcher appears in the intended position on desktop and mobile. - The first answer matches the selected agent, not another environment. - Public chat settings allow only the intended capabilities. - File upload, feedback, reasoning visibility, and realtime audio match the product decision. - The privacy link opens the correct customer policy. - The page is not sending secrets through `window.siestaWidgetContext`. - The target site CSP allows `chat-widget.js` from the selected Siesta app host. - The support team knows which agent ID and environment were deployed. --- # Playground import WebPluginPlayground from '@site/src/components/WebPluginPlayground'; # Web Plugin Playground Use this page to validate the current manifest-backed Web Plugin contract without mounting a second live widget into the standard docs layout. The playground only covers the browser-safe widget surface: - `data-chatbot-id` - `data-base-url` - `data-environment` - optional safe `window.siestaWidgetContext` It does not use `X-Api-Key`, `X-Org-Id`, External API calls, realtime sessions, or authenticated-widget OAuth flow. --- # Roles The **Roles** section is used to manage permissions in the organization. Roles define which parts of the platform a user can access and which actions they can perform. > Documentation status: **admin**. In the current application version, Roles is available as an internal route, but it is not shown in the regular left application menu. This page is therefore treated as administrator documentation and is marked as admin in the documentation sidebar. ## Role Overview The main view contains a roles table. The table supports search, pagination, and actions on individual roles. The most important visible column is: - **Name** - the role name. Clicking a role name opens permission editing for that role. ![Role overview](/img/roles/roles-overview.png) ## Creating a Role Create a new role with the **Add role** button. In the form, fill in: - role **name**, - permission set. After submission, the role is saved and can be used when managing users. ![Creating a Role](/img/roles/role-create.png) ## Editing Permissions Open a role from the roles table to review the role name and permission set before changing it. From the role detail or action menu, open the **Edit role permissions** modal. Permissions are grouped by platform area. Current permission groups include, for example: - **Users** - create, edit, and delete users. - **Roles** - create, edit, and delete roles. - **Agents** - create, edit, and delete agents. - **Feedback** - access agent feedback. After editing permissions, confirm the changes with **Submit**. Permission changes can affect every user assigned to the role. Before changing a shared role, check which users have it and whether a narrower role would be safer. ## Deleting a Role Roles can be deleted from the action menu on a specific row. Before deleting a role, verify that it is not used by users who need it to access the platform. ## Recommendations - Create roles based on work responsibilities, not individual people. - Grant administrator permissions only to users who truly need them. - After larger permission changes, verify access with a test account. --- # Security The Security section provides an overview of the organization's security status within the Siesta AI platform. It serves to identify risky configurations and recommends steps that enhance the security of the environment. The Security page includes: - A list of security recommendations - The category of each recommendation - Severity level - Information on whether the configuration complies with the recommendation - Recommended remediation steps ![Overview of security recommendations](/img/security/security-recommendations-table.png) Security checks focus on the following areas: ## 1. Content Sharing - Checking conversation sharing - Checking record sharing - Limiting public access to data The goal is to prevent unintentional leaks of internal information. ## 2. Authentication - Verification of user login methods - Recommendation to use federated login (Microsoft / Google) - Limiting weak or local access mechanisms The goal is to minimize the risk of account compromise. ## 3. AI Limits and Resource Management - Checking rate limit settings - Checking usage quotas The goal is to prevent system abuse and uncontrolled cost growth. ## 4. External Connections - Overview of active integrations - Checking permissions of connected systems The goal is to ensure that only necessary and approved integrations are allowed. Each recommendation is marked with a severity level: - **Medium** – recommended improvement - **High** – significant security risk It is recommended to address items with higher severity as a priority. ![Detail of security recommendation](/img/security/security-recommendation-detail.png) ## Recommended Procedure 1. Regularly check the Security section. 2. Address high severity items without delay. 3. Limit public data sharing. 4. Utilize federated login. 5. Actively manage connections and access permissions. The Security section helps the organization maintain a secure, controlled, and auditable environment when working with AI and corporate data. ## Design and Operations Guidance The Security page reports product findings. Use the [Security and Governance](/security-and-governance) section when you need to design or review the wider operating controls around: - [AI-specific threats](#doc-security-and-governance-ai-threat-model) and [prompt injection](#doc-security-and-governance-prompt-injection), - [data access and RAG](#doc-security-and-governance-data-access-and-rag), - [tool governance](#doc-security-and-governance-tool-governance) and [human approval](#doc-security-and-governance-human-approval), - [auditability](#doc-security-and-governance-auditability) and [incident response](#doc-security-and-governance-incident-response), - [model governance](#doc-security-and-governance-model-governance), data residency, and production readiness.