budibase Documentation

AI agents, automations and apps that run your operations. Model agnostic.

28,199 stars TypeScript TypeScript 1 file · ~8,848 tokens #ai-app-builder#ai-applications#crud-app#crud-application#data-application#data-apps#internal-tools#it-workflows
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy budibase on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name budibase -p 4000:4000 --restart always budibase/proxy
Configured Services & Ports
⚙️ app-service
image: build locally
⚙️ worker-service
image: build locally
⚙️ proxy-service-docker
image: budibase/proxy
🔌 Ports: ${MAIN_PORT}:10000
⚙️ litellm-service
image: docker.io/litellm/litellm:main-v1.83.10-stable.patch.3
🔌 Ports: ${LITELLM_PORT:-4000}:4000
⚙️ litellm-db
image: postgres:16
docker-compose.yml
yaml (docker-compose.yml) 
# optional ports are specified throughout for more advanced use cases.

services:
  app-service:
    build:
      context: ..
      dockerfile: packages/server/Dockerfile
      args:
        - BUDIBASE_VERSION=0.0.0+dev-docker
    container_name: build-bbapps
    environment:
      SELF_HOSTED: 1
      COUCH_DB_URL: http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984
      WORKER_URL: http://worker-service:4003
      MINIO_URL: http://minio-service:9000
      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
      INTERNAL_API_KEY: ${INTERNAL_API_KEY}
      BUDIBASE_ENVIRONMENT: ${BUDIBASE_ENVIRONMENT}
      PORT: 4002
      API_ENCRYPTION_KEY: ${API_ENCRYPTION_KEY}
      JWT_SECRET: ${JWT_SECRET}
      LOG_LEVEL: info
      ENABLE_ANALYTICS: "true"
      REDIS_URL: redis-service:6379
      REDIS_PASSWORD: ${REDIS_PASSWORD}
      LITELLM_URL: http://litellm-service:4000
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      BB_ADMIN_USER_EMAIL: ${BB_ADMIN_USER_EMAIL}
      BB_ADMIN_USER_PASSWORD: ${BB_ADMIN_USER_PASSWORD}
      PASSWORD_MIN_LENGTH: ${PASSWORD_MIN_LENGTH:-12}
      PASSWORD_MAX_LENGTH: ${PASSWORD_MAX_LENGTH:-512}
      PASSWORD_REGEX: ${PASSWORD_REGEX:-}
      PASSWORD_REGEX_ERROR_MESSAGE: ${PASSWORD_REGEX_ERROR_MESSAGE:-}
      PLUGINS_DIR: ${PLUGINS_DIR}
      TENANT_FEATURE_FLAGS: "*:SQS"
    depends_on:
      - worker-service
      - redis-service
      - litellm-service

  worker-service:
    build:
      context: ..
      dockerfile: packages/worker/Dockerfile
      args:
        - BUDIBASE_VERSION=0.0.0+dev-docker
    container_name: build-bbworker
    environment:
      SELF_HOSTED: 1
      PORT: 4003
      CLUSTER_PORT: ${MAIN_PORT}
      API_ENCRYPTION_KEY: ${API_ENCRYPTION_KEY}
      JWT_SECRET: ${JWT_SECRET}
      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
      MINIO_URL: http://minio-service:9000
      APPS_URL: http://app-service:4002
      COUCH_DB_USERNAME: ${COUCH_DB_USER}
      COUCH_DB_PASSWORD: ${COUCH_DB_PASSWORD}
      COUCH_DB_URL: http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984
      INTERNAL_API_KEY: ${INTERNAL_API_KEY}
      REDIS_URL: redis-service:6379
      REDIS_PASSWORD: ${REDIS_PASSWORD}
      LITELLM_URL: http://litellm-service:4000
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      TENANT_FEATURE_FLAGS: "*:SQS"
      PASSWORD_MIN_LENGTH: ${PASSWORD_MIN_LENGTH:-12}
      PASSWORD_MAX_LENGTH: ${PASSWORD_MAX_LENGTH:-512}
      PASSWORD_REGEX: ${PASSWORD_REGEX:-}
      PASSWORD_REGEX_ERROR_MESSAGE: ${PASSWORD_REGEX_ERROR_MESSAGE:-}
    depends_on:
      - redis-service
      - minio-service
      - litellm-service

  proxy-service-docker:
    build:
      context: ./proxy
    ports:
      - "${MAIN_PORT}:10000"
    container_name: build-bbproxy
    image: budibase/proxy
    environment:
      - PROXY_RATE_LIMIT_WEBHOOKS_PER_SECOND=10
      - PROXY_RATE_LIMIT_API_PER_SECOND=50
      - APPS_UPSTREAM_URL=http://app-service:4002
      - WORKER_UPSTREAM_URL=http://worker-service:4003
      - MINIO_UPSTREAM_URL=http://minio-service:9000
      - COUCHDB_UPSTREAM_URL=http://couchdb-service:5984
      - RESOLVER=127.0.0.11
    depends_on:
      - minio-service
      - worker-service
      - app-service
      - couchdb-service

  litellm-service:
    image: docker.io/litellm/litellm:main-v1.83.10-stable.patch.3
    ports:
      - "${LITELLM_PORT:-4000}:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml
    environment:
      DATABASE_URL: "postgresql://${LITELLM_DB_USER}:${LITELLM_DB_PASSWORD}@litellm-db:5432/${LITELLM_DB_NAME}"
      STORE_MODEL_IN_DB: "True"
      LITELLM_REASONING_AUTO_SUMMARY: "true"
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY}
    command: ["--config", "/app/config.yaml"]
    depends_on:
      - litellm-db
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')\"",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  litellm-db:
    image: postgres:16
    environment:
      POSTGRES_DB: ${LITELLM_DB_NAME}
      POSTGRES_USER: ${LITELLM_DB_USER}
      POSTGRES_PASSWORD: ${LITELLM_DB_PASSWORD}
    volumes:
      - litellm_data:/var/lib/postgresql/data
    healthcheck:
      test:
        ["CMD-SHELL", "pg_isready -d ${LITELLM_DB_NAME} -U ${LITELLM_DB_USER}"]
      interval: 1s
      timeout: 5s
      retries: 10

volumes:
  litellm_data:
    driver: local

1. Project Overview & Quickstart (Budibase/budibase)

Budibase

AI Agents that run your operations

🤖 🎨 🚀

[Get started - we host (Budibase Cloud)](https://account.budibase.app/register) · [Get started - you host (Docker, K8s, DO)](https://docs.budibase.com/docs/hosting-methods) · [Docs](https://docs.budibase.com/docs) · [Feature request](https://github.com/Budibase/budibase/discussions?discussions_q=category%3AIdeas) · [Report a bug](https://github.com/Budibase/budibase/issues) · Support: [Discussions](https://github.com/Budibase/budibase/discussions)

✨ Features

Run your operations on one platform

Handle requests, automate workflows, manage processes, and connect your business systems - without stitching together multiple tools.

Employees ask questions, request approvals, and report issues every day. Budibase agents understand these requests and handle the work automatically.

Operations your team can run with AI agents

Employees ask questions, request approvals, and report issues every day. Budibase agents understand these requests and handle the work automatically.

Agents that take action

Budibase agents don’t just answer questions. They run workflows across your business - creating records, routing approvals, updating apps, and notifying teams automatically.

Connect the tools your business runs on

Integrate with databases, AI models, and business apps so agents and automations can take action across your operations.

Deploy with confidence and security

Budibase is open-source and is made to scale. With Budibase, you can self-host on your own infrastructure and globally manage users, onboarding, SMTP, apps, groups, theming and more. You can also provide users/groups with a portal and disseminate user management to the group manager.

Budibase Public API

As with anything that we build in Budibase, our public API is simple to use, flexible, and introduces new extensibility. To summarize, the Budibase API enables:

  • Budibase as a backend
  • Interoperability

Docs

You can learn more about the Budibase API at the following places:

🏁 Get started

Deploy Budibase using Docker, Kubernetes, and Digital Ocean on your existing infrastructure. Or use Budibase Cloud if you don't need to self-host and would like to get started quickly.

[Get started with self-hosting Budibase](https://docs.budibase.com/docs/hosting-methods)

[Get started with Budibase Cloud](https://budibase.com)

🎓 Learning Budibase

The Budibase documentation lives here.

💬 Community

If you have a question or would like to talk with other Budibase users and join our community, please hop over to Github discussions

❗ Code of conduct

Budibase is dedicated to providing everyone a welcoming, diverse, and harassment-free experience. We expect everyone in the Budibase community to abide by our Code of Conduct. Please read it.

🙌 Contributing to Budibase

From opening a bug report to creating a pull request: every contribution is appreciated and welcomed. If you're planning to implement a new feature or change the API, please create an issue first. This way, we can ensure your work is not in vain.
Environment setup instructions are available here.

Not Sure Where to Start?

A good place to start contributing is by looking for the good first issue tag.

How the repository is organized

Budibase is a monorepo managed by lerna. Lerna manages the building and publishing of the budibase packages. At a high level, here are the packages that make up Budibase.

  • packages/builder - contains code for the budibase builder client-side svelte application.

  • packages/client - A module that runs in the browser responsible for reading JSON definition and creating living, breathing web apps from it.

  • packages/server - The budibase server. This Koa app is responsible for serving the JS for the builder and budibase apps, as well as providing the API for interaction with the database and file system.

For more information, see CONTRIBUTING.md

📝 License

Budibase is open-source, licensed as GPL v3. The client and component libraries are licensed as MPL - so the apps you build can be licensed however you like. Budibase paid features are licensed under the Business Source License,

⭐ Stargazers over time

If you are having issues between updates of the builder, please use the guide here to clear down your environment.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Made with contrib.rocks.

2. Official Technical Reference & Guides (Budibase/docs)

File: docs/AI/messaging-channels/index.md

title: Messaging channels deprecated: false hidden: false metadata: robots: index

Use this page to deploy an agent to external messaging channels where your users already work.

Slack and Microsoft Teams are the primary deployment paths for live agent conversations.

Before you start

Make sure you have:

  • A working Agents config
  • A saved agent with a connected AI model
  • An agent set live (status Live)

Before a user can chat with an agent in Slack or Microsoft Teams, they must link their messaging identity to a Budibase account.

Use /link (Teams also accepts link) in the channel conversation to start linking.

If a user sends a normal message before linking, Budibase sends a private link prompt and guides them through account linking.

  1. Configure one channel first
  2. Run end-to-end tests in that channel
  3. Add additional channels only after the first is stable
  4. Standardize account linking and support runbooks for each channel

Available channel guides

Important endpoint note

Budibase channel webhooks are validated against the production workspace route. Use the endpoint URL generated in the deployment UI, and do not replace the workspace segment manually.

File: docs/AI/messaging-channels/messaging-channels-discord.md

title: Discord messaging channel deprecated: true hidden: true metadata: robots: noindex

⚠️

Discord integration has been removed. Support for Discord as a messaging channel is no longer available in Budibase.

File: docs/AI/messaging-channels/messaging-channels-microsoft-teams.md

title: Microsoft Teams messaging channel deprecated: false hidden: false metadata: robots: index

Use this guide to deploy an agent to Microsoft Teams.

Before you start

Make sure you have:

  • A Microsoft 365 tenant with Teams access
  • An Azure app registration for your bot
  • A live agent with an AI model connected
  • Access to Agents -> your agent -> Deployment

Configure Microsoft Teams in Budibase

  1. Open your agent in Agents
  2. Go to Deployment
  3. In Messaging channels, click Manage for Microsoft Teams
  4. Enter:
    • App ID (client ID) - This must be a valid UUID provided by Azure.
    • Client secret (value)
    • Directory (tenant) ID (Azure AD tenant ID)
    • Idle timeout (minutes) (optional)
  5. Click Save channel
  6. Copy the generated Messaging endpoint URL
  7. Click Download app package to download a zip file containing the manifest and icons for your Teams bot. This package can be sideloaded into Microsoft Teams.

Configure your Teams bot endpoint

In your Azure bot configuration, set the bot messaging endpoint to the Budibase Messaging endpoint URL.

Use a single-tenant setup that matches your tenant ID.

Enable and verify

  1. In Budibase Deployment, toggle Microsoft Teams to Enabled
  2. Open Teams and message the bot
  3. Run link or /link, then complete the Budibase account linking flow
  4. Test commands:
    • ask <message> to continue the current conversation
    • new <message> to start a new conversation
    • unlink or /unlink to disconnect your Budibase account

Plain text messages are treated as ask.
If you send a normal message before linking, Budibase sends a private link prompt. Similarly, if you respond to an approval request (escalation) before linking, your response won't be counted until you complete the linking flow.

Working with documents (RAG)

When your agent uses documents to answer questions (Retrieval-Augmented Generation), Budibase can provide direct download links to those sources within Teams.

Source citations

In personal conversations, your agent will automatically provide the specific document sources it used to generate its reply as a set of interactive buttons below the message. Each button includes a direct, authenticated link to download the file.

To ensure privacy and security, source download links are not provided when the agent is chatting in a channel or group conversation.

Disabling source downloads

You can control whether users are allowed to download knowledge sources through the agent's operation settings:

  1. Open your agent in Agents
  2. Select the Operations tab
  3. Locate your live operation and click the settings icon
  4. Toggle Allow knowledge source download off if you want to prevent download links from being generated in personal chats.

Troubleshooting

  • Not configured in Budibase: confirm App ID, Client secret, and Tenant ID are saved.
  • Teams cannot deliver messages: verify the bot messaging endpoint matches the Budibase URL exactly.
  • Authentication failures from Teams: check bot credentials and tenant alignment.
  • Teams prompts to link before answering: run link or /link and complete the account link handoff.
  • Webhook route errors: use the exact Budibase-generated endpoint URL from Deployment.
  • Invalid Microsoft Teams service URL: Budibase validates that all Teams interactions use trusted Microsoft service origins. If you are using a region-specific or custom Microsoft Teams environment, you may need to configure the TEAMS_API_URL environment variable on your Budibase server (e.g., TEAMS_API_URL=https://smba.trafficmanager.net/apis/) to match your environment.

File: docs/AI/messaging-channels/messaging-channels-slack.md

title: Slack messaging channel deprecated: false hidden: false metadata: robots: index

Use this guide to deploy an agent to Slack.

Before you start

Make sure you have:

  • A Slack workspace where you can create apps
  • A live agent with an AI model connected
  • Access to Agents -> your agent -> Deployment

Configure Slack in Budibase

  1. Open your agent in Agents
  2. Go to Deployment
  3. In Messaging channels, click Manage for Slack
  4. Enter:
    • Bot token
    • Signing secret
    • Idle timeout (minutes) (optional)
  5. Click Save channel
  6. Copy the generated Messaging endpoint URL
  7. (Optional) Toggle File attachments to Enabled. This requires a GEMINI_API_KEY to be set in your Budibase server environment.

Configure your Slack app

1. Create or update app

Create a Slack app for your workspace, or use an existing one.

2. Add bot scopes

In OAuth & Permissions, add:

  • chat:write
  • app_mentions:read
  • im:history
  • channels:history
  • groups:history
  • mpim:history
  • users:read
  • files:read

3. Configure event subscriptions

  1. Open Event Subscriptions
  2. Enable events
  3. Set Request URL to the Budibase Messaging endpoint URL
  4. Subscribe to bot events:
    • app_mention
    • message.im
    • message.channels
    • message.groups
    • message.mpim

4. Reinstall app

Reinstall the app to your workspace after changing scopes or events.

5. Invite bot

Invite the bot to channels you want it to serve, for example:

/invite @your-bot

Enable and verify

  1. In Budibase Deployment, toggle Slack to Enabled
  2. In Slack, mention the bot in a channel or send a DM
  3. Run /link and complete the Budibase account linking flow
  4. Run /unlink to disconnect your Budibase account
  5. Send a message and confirm the agent responds

Slack threads are used as conversation boundaries. In a channel thread, you must mention the agent in each message you want it to process. In direct messages (DMs), the agent will respond to every message automatically.

If you send a message before linking, Budibase prompts you privately to complete account linking first. Similarly, if you respond to an approval request (escalation) before linking, your response won't be counted until you complete the linking flow.

Slash commands

  • /ask <message>: Continue the current conversation.
  • /new <message>: Start a new conversation, clearing the message and file history for the current thread.
  • /link: Link your Slack user to your Budibase account.
  • /unlink: Unlink your accounts.

Working with documents (RAG)

When your agent uses documents to answer questions (Retrieval-Augmented Generation), Budibase can provide direct download links to those sources within Slack.

Source citations

In personal conversations (DMs), your agent will automatically append a list of the specific document sources it used to generate its reply. Each source includes a direct, authenticated link to download the file.

To ensure privacy and security, source download links are not provided when the agent is chatting in a channel or group conversation.

Conversation attachments

If File attachments is enabled in the agent deployment settings, users can upload files directly in Slack conversations. The agent will process these files and use their content to answer subsequent questions in that thread.

  • Supported formats: PDF, CSV, TXT, Markdown, JSON, YAML, and XML.
  • Limits: Up to 3 files per conversation, maximum 20MB per file.
  • Cleaning files: Use the /new command to clear attached files and start a fresh conversation.

Troubleshooting

  • Not configured in Budibase: confirm both Bot token and Signing secret are saved.
  • Slack events not reaching Budibase: re-check Request URL and reinstall the app after scope/event changes.
  • Bot does not respond in channels: confirm the bot was invited to that channel.
  • Bot prompts to link before answering: run /link in Slack and complete the link handoff.
  • Webhook route errors: use the exact Budibase-generated endpoint URL from Deployment.
  • File processing fails: ensure GEMINI_API_KEY is correctly configured and the Slack app has the files:read scope.

File: docs/AI/agent-activity.md

title: Agent activity excerpt: Monitor and track interactions with your AI agents. deprecated: false hidden: false metadata: robots: index

Agent activity allows you to monitor all interactions with your AI agents across different channels. It provides a centralized view of requests, their statuses, and the specific operations triggered by your agents.

Accessing activity

You can find the Activity section in the side navigation of your Budibase builder workspace. This view is available for all applications containing agents and provides a history of agent actions in your production environment.

Monitoring agent actions

The Activity page displays a list of recent requests tracked by your agents. Each entry includes critical operational metadata:

  • Requests: A descriptive title generated based on the user's prompt and the triggered operation.
  • Source: Indicates which agent handled the request.
  • Status: Shows the current state of the request (e.g., Completed).
  • Updated: A relative timestamp showing when the request was last active.

Metrics overview

At the top of the Activity page, summary metrics provide a high-level view of your agent's performance:

  • All actions: The total number of tracked interactions.
  • Completed: Requests that successfully finished processing.
  • Processing: Active requests currently being handled by the agent.
  • Needs input: Requests waiting for user clarification or additional data.
  • Failed: Requests that encountered errors during execution.

Request details and timeline

Clicking on any request in the table opens a side panel with detailed information and an interaction timeline.

Details

The details section provides granular data about a specific interaction:

  • Status: The final or current status of the request.
  • Error: The specific error message if the request has a Failed status.
  • Source: The specific agent used.
  • Operation: The names of the tools or automation workflows the agent utilized to fulfill the request.
  • Created by: The user who initiated the prompt.
  • Channel: The communication channel where the request originated (e.g., Slack, MS Teams, Discord, or Portal Chat).
  • Created at: The exact timestamp of the initial prompt.

Timeline

The timeline tracks the lifecycle of a request, from its creation through various operation stages. This is useful for debugging multi-step agent interactions or verifying that the correct logic was executed in response to a user prompt.

If an operation fails, the timeline provides detailed error feedback to help you understand what went wrong during execution.

File: docs/AI/agent-building-101.md

title: Agent building 101 deprecated: false hidden: false metadata: robots: index

In Budibase, Agents enable AI to interact with the data, tools, and automations in your Workspace.

In this guide, we’ll build a simple AI Service Desk Agent that can:

  • Answer questions about tickets
  • Categorise and summarise new tickets
  • Update ticket statuses

Along the way, we’ll learn how to:

  • Configure an Agent’s instructions
  • Connect Workspace data as tools
  • Define structured outputs
  • Trigger automations from Agent actions
  • Test and iterate safely

Let’s jump in.

Before you start

Make sure you have:

  • A model provider configured in Agents config
  • A Tickets table in your Workspace
  • Permission to create Agents and Automations

What is an agent?

An agent is:

  • An LLM configured with:
    • Instructions
    • Tools
    • Memory
    • Structured outputs
  • That can:
    • Read data
    • Write data
    • Trigger automations

Setting up our data layer

In Budibase, Agents can interact with any tables, API calls, or automations within your Workspace, as long as they’re explicitly given access.

Before creating an Agent, it’s important to understand the data it will work with and define what actions it should be allowed to perform.

Take a look at our Introduction to Data documentation to learn more about how data works in Budibase.

Our tickets table

For this guide, we’ll use a Budibase DB table called Tickets.

This contains the following columns:

Name Field Type
Title Text
Description Long form text
Status Single select
Priority Single select
Time Created Date
Resolution Notes Long form text
Created By Single user
Category Single select

Creating our agent

Onto creating our first Agent. Make sure you have done the initial setup of selecting a provider and configuring a model before doing this. You can find out how to do this here.

  1. Click on the Agents link on the left side of the screen
  2. Click the + New Agent button at the top right of your screen
  3. Provide a name. We're going with Service Desk Agent
  4. This will redirect you to the Agent configuration screen.

Configuring instructions

Agents perform tasks through Operations. An Agent can have one or many operations, each with its own set of instructions and tools. To get started, we need to create our first operation:

  1. In the Operations section of the Agent configuration, click Add operation.
  2. Give your operation a name (e.g., "Support Triage") and click Create.
  3. You will be navigated to the operation detail page.

By default, Budibase provides a structured instruction template to help you define your operation clearly. More information on this can be found here.

For now we will use the below instructions:

markdown instructions
**Operation role**
You are a Service Desk AI Agent responsible for managing support tickets.

**Inputs**
You receive ticket data, including Title, Description, Status, and Priority.

**Actions**
- Categorise new tickets.
- Suggest a priority level (Low, Medium, High)
- Answer questions about ticket status
- Use available tools when reading or updating tickets

**Output**
Respond clearly and concisely.
When categorising or prioritising, return structured JSON:
{
  "category": "string",
  "priority": "Low | Medium | High"
}

**Rules**
- Do not modify tickets unless explicitly instructed
- Be concise and professional
- Use British English where possible

After configuring and adding the above instructions, run a test and confirm that everything is working.

Adding tools

Tools allow an Agent to retrieve and modify real data inside your Workspace. You must explicitly enable each tool an operation needs.

For this example, we’ll give our Agent access to three tools from the Tickets table:

  • Budibase: Tickets.List Rows - Retrieves multiple tickets
  • Budibase: Tickets.Get Row - Retrieves a specific ticket
  • Budibase: Tickets.Update Row - Updates fields on an existing ticket

To add these tools:

  1. In the instructions editor, type {{ to open the autocomplete menu.
  2. Select Add tool.
  3. Search for and select the required tool (e.g., Tickets.List Rows).
  4. Configure the Execution principal (use Requester for this guide) and click Add tool.

Together, these allow the Agent to:

  • Look up tickets when answering questions
  • Retrieve specific ticket details
  • Update ticket status, priority, or resolution notes when required

As a best practice, only enable the minimum set of tools required. Limiting tool access helps ensure predictable and safe behaviour.

Adding Knowledge

In addition to tools, Agents can use Knowledge Sources to answer questions based on external documents or sites. This is commonly referred to as RAG (Retrieval-Augmented Generation).

📘 NOTE

Knowledge features require the GEMINI_API_KEY to be configured in your Budibase environment. If this key is missing, knowledge actions will be disabled in the builder.

Connecting SharePoint Knowledge

You can quickly add SharePoint sites as a knowledge source without manually configuring a REST connector:

  1. In the operation detail page, go to the Knowledge tab in the settings rail on the right.
  2. Click Add source and select SharePoint.
  3. If you don't have an existing connection, enter your Directory (tenant) ID, Application (client) ID, and Client secret.
  4. Budibase will automatically create the connection and allow you to select the SharePoint sites you wish to sync.

For more complex configurations, you can use the Advanced setup option within the connection modal to go directly to the SharePoint REST connector settings.

Updating our instructions

Once these tools and knowledge sources are enabled, we need to guide the Agent on when to use them.

Here is our updated instruction prompt:

markdown instructions
**Operation role**
You are a Service Desk AI Agent responsible for managing support tickets.

**Inputs**
You receive ticket data, including Title, Description, Status, and Priority.

**Available tools**
{{ budibase.Tickets.list_rows }}
{{ budibase.Tickets.get_row }}
{{ budibase.Tickets.update_row }}

**Actions**
- Categorise new tickets.
- Suggest a priority level (Low, Medium, High)
- Answer questions about ticket status
- Use the appropriate tool when retrieving or updating ticket data

**Output**
Respond clearly and concisely.
When categorising or prioritising, return structured JSON:
{
  "category": "string",
  "priority": "Low | Medium | High"
}

**Rules**
- Always use the provided tools when accessing ticket data
- Do not fabricate ticket information
- Do not modify tickets unless explicitly instructed
- Be concise and professional
- Use British English

Optionally, test again with some data and see how it handles the process.

Managing multiple operations

As your agent grows more complex, you can define multiple Operations, each with its own dedicated detail page containing its own instructions, tools, and knowledge.

When an agent has multiple live operations, Budibase uses an internal router to detect the intent of the user's request. It will:

  • Select a specific operation if the request clearly matches one operation's focus.
  • Summarize capabilities if the user asks broad questions like "What can you help me with?" or requests an overview of the agent's tasks.
  • Proceed without an operation if the request is unrelated to any defined capability.

You do not need to manually configure this routing; it is handled automatically based on the names and instructions you provide for each operation.

Testing the agent

Now that our Agent has instructions and tools, we can test whether it behaves safely and predictably.

Start with a few representative prompts:

  • What tickets are currently open and high priority?
  • Summarise ticket "Printer access broken for Finance" and suggest category + priority.
  • Update ticket "VPN issue for remote user" to In Progress and add a short resolution note.

For each test, check:

  • Tool usage: The Agent should use list/get tools to retrieve live data, and only use update when explicitly asked.
  • Output format: Classification responses should follow the JSON schema we defined.
  • Data accuracy: Values returned should match the row data in your Tickets table.
  • Safety rules: The Agent should refuse to update unless your prompt asks it to.

If behaviour is inconsistent, tighten your instructions. For example:

  • Clarify when updates are allowed.
  • Add examples of valid and invalid requests.

Small prompt edits and frequent tests are the quickest path to reliable behaviour.

Triggering the agent automatically

Once manual testing looks good, you can run this workflow automatically when new tickets are created.

In this example, we’ll use an Automation to classify and prioritise tickets as they arrive:

  1. Create an Automation with a Row Created trigger on the Tickets table.
  2. Add an LLM Prompt action to process Title and Description and return:
    • category
    • priority
  3. Add an Update Row action to write the generated Category and Priority back to the created ticket.
  4. Add a Condition step:
    • If priority is High, trigger your notification path (for example, send an external notification).
  5. Test with multiple sample tickets to confirm the full flow.

This gives you a practical split of responsibilities:

  • Messaging channels handle interactive support tasks, Q&A, and guided updates
  • Automations handle repeatable, event-driven triage in the background

Together, these provide a reliable service desk workflow with both human-in-the-loop and fully automatic paths.

Next steps

Once this foundation is working, use these guides to improve quality and safety:

File: docs/AI/agent-chat.md

title: Agent chat deprecated: true hidden: false metadata: robots: index

Agent chat is deprecated.

Budibase is moving to channel-first agent access in tools where users already work day-to-day:

Use Messaging channels as the primary deployment path.

What this means

If you are currently using Agent Chat:

Migration checklist

  1. Confirm your agent has a connected AI model in Agents config.
  2. Ensure the agent is set to Live.
  3. Pick one primary channel (Slack, Teams, or Discord).
  4. Configure the channel in Agents -> Deployment -> Messaging channels.
  5. Validate account linking (/link, or link in Teams).
  6. Run end-to-end tests for conversation continuity and tool actions.
  7. Add additional channels only after the first channel is stable.

File: docs/AI/agent-embedding-models.md

title: Agent embedding models deprecated: false hidden: false metadata: robots: index

Embedding models convert text into vectors so your Agent can retrieve relevant knowledge chunks during responses.

In Budibase, embedding model configuration is managed in Workspace Settings > Connections > Knowledge bases and used from an Agent's Operations panel.

Configure an embedding model

  1. Open Workspace Settings
  2. Go to Connections > Knowledge bases
  3. Scroll to Embedding models
  4. Click + Embedding model
  5. Provide the required provider credentials and model details
  6. Save and verify the configuration appears in the list

Attach an embedding model to an Agent

  1. Open your Agent
  2. Open the Operations panel and select the operation you want to configure
  3. In the Knowledge area, select an Embedding model
  4. Save the Agent

When both embedding model and vector database are configured, additional retrieval settings are available:

  • Minimum similarity
  • Chunks to retrieve

Practical guidance

  • Start with default retrieval settings, and tune only after testing
  • Once you choose an embedding model, use it consistently for all documents and queries in that knowledge base
  • Re-test retrieval quality whenever you change the model or provider configuration

File: docs/AI/agent-instructions-guide.md

title: Agent instructions guide deprecated: false hidden: false metadata: robots: index

Instructions are the most important control for Agent behaviour.

This page shows how to write prompts that are clear, testable, and safe.

Core structure

Use this structure for production Agents:

  1. Role: What the Agent is responsible for
  2. Inputs: What data it receives
  3. Tools: Which tools it can use
  4. Actions: What it should do
  5. Output: Expected format and tone
  6. Rules: Hard constraints and refusal criteria
markdown instructions
**Agent role**
You are a [role] for [team or process].

**Inputs**
You receive [fields/data sources].

**Available tools**
{{ tool_1 }}
{{ tool_2 }}

**Actions**
- [action 1]
- [action 2]

**Output**
Return [plain text / JSON schema / markdown].

**Rules**
- Use tools for all live data access
- Never invent missing values
- Only perform write actions when explicitly requested
- Refuse requests outside your scope

Output design

If downstream automations use the Agent response, prefer structured outputs.

Example:

json
{
  "category": "string",
  "priority": "Low | Medium | High",
  "requiresEscalation": true
}

Keep field names stable. Changing response shape can break automations and scripts.

Instruction quality checklist

Before publishing, ensure that:

  • Scope is explicit and narrow
  • Tool usage expectations are explicit
  • Write permissions are tightly constrained
  • Escalation and refusal rules are clear
  • Output format is deterministic

Common issues

  • Vague goals: Agent gives inconsistent answers
  • Missing tool rules: Agent hallucinates data
  • No refusal criteria: Agent attempts unsupported tasks
  • Free-form output where JSON is required: automation parsing fails

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai-app-builder Browse ai-app-builder catalog → #ai-applications Browse ai-applications catalog → #crud-app Browse crud-app catalog → #crud-application Browse crud-application catalog → #data-application Browse data-application catalog → #data-apps Browse data-apps catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →