Apps and Agents
Let agents use an App through its App connection, and build and deploy Apps with the App Builder tools.
Agents work with Apps in two ways, granted separately:
| Activity | Granted by | What the agent can do |
|---|---|---|
| Use an App | The App connection | Call the App's functions, and show the App. |
| Build an App | The App Builder Product Tools | Create Apps, check and build commits, deploy, and try the App. |
Using an App never grants source, build, or deploy access, and the builder tools never bypass the App's roles.
Use an App from a chat or Workspace
The environment must be shared, and the person needs access to its App connection.
- In a Workspace chat, select Connections in the composer and switch on the App connection, such as Purchase Requests (development).
- Ask for it: "Show me the Purchase Requests app."
To give it to an agent instead, add it to the agent's connections.
The agent gets the tools the App connection offers, and its calls run as the person, with their roles.
show_apptakes two optional inputs:mode:inlineshows the App in the chat.fullscreenopens it next to the chat: a Workspace tab, or a new window from an embedded chat. Without it, an App that declaresfullscreeninui.displayModesopens fullscreen, and any other App opens inline.route: the App page to open, such as/projects/PRJ-0001. A route that matches no page the App lists returns an error that lists them.
- If the App is already open in a Workspace tab, a fullscreen
show_appwith a route moves it there without reloading. - If the browser blocks the new window from an embedded chat, the App stays in the chat with an Open App button.
- While the App is open, the agent can also use tools the App's UI offers.
People also open Apps from Apps in their Workspace. See Use BotDojo Apps.
Use an App from Claude or ChatGPT
An App connection exported to external clients works in clients that show an interface in the conversation, such as Claude and ChatGPT. Add the connection's server URL to the client and sign in. The App runs with the roles of the BotDojo user who signed in. Claude interactive connectors · ChatGPT MCP Apps support
show_appshows the App in the conversation. The client decides where, somodechanges nothing there.- To offer the functions without the interface, turn off
show_appin the connection's tool settings. - A new release reaches an open conversation within five minutes, or when the client reconnects.
- Tools the open App offers with
registerToolswork in Claude, which asks before each call. - Not available: permission requests for the App's own connections (set them in BotDojo first), and the chat beside the App.
Build Apps with a Workspace agent
The App Builder tools let a Workspace agent take an App from idea to a tested deployment in a non-production environment. An account administrator enables them in BotDojo Product Tools; they are off by default.
| Product Tool | What it includes |
|---|---|
| Apps | List and describe the project's Apps, and create one from the starter. |
| App Builder | One App's builds, deploys, environments, env vars, data, and previews. Can be limited to one App. |
| Building Apps Skill | Guidance on building a BotDojo App. |
The agent changes code through Git: it clones the App's repo, edits, and pushes a branch. Then it uses:
app_statusto see each environment's branch and what is building.app_checkto build a commit and run its tests without deploying.app_deploy_latestto build and deploy an environment's latest commit.- Other tools call functions, query tables, load seed data, and preview the UI in non-production environments.
What asks first
Reading, checking, and building run without asking. Every change asks the user first: creating an App or environment, deploying, changing a branch, setting or removing env vars, loading seed data, and creating an App connection. Administrators can change these defaults in the tool settings.
In production:
- Data, function, seed, setting, and preview tools refuse to run.
- Only
app_deploy_productionandapp_deploy_latest_productiondeploy, and both ask first. - The agent cannot turn on automatic deploys.
Secrets
The agent cannot set secret env vars. The user enters them in the deploy
dialog or with botdojo-app env set.