Integrations

Integrations give an agent access to apps like Gmail, Slack, Notion and GitHub through Pipedream. You connect the accounts once on the agent's Tools page and set an Allow, Ask or Deny rule for each app or action. Enabled managed turns reach the same apps through one built-in MCP server, brainbase-apps, and Brainbase enforces your rules on its side, not inside the agent.

Connect apps

Connecting accounts is a manager's job. Agent managers (the agent's owner and the team's owners and admins) connect, disconnect and add apps. Other members can see the agent's apps and rules but cannot change them. Connect accounts from your own session. Brainbase keeps account credentials on the server.

An agent can hold more than one account for the same app. When an action could use several, the agent has to name the account it wants. Brainbase never picks one for it and never switches accounts silently. With exactly one healthy account, that account is used.

Connections belong to the agent, not to a task. You can set them up before the agent has ever run, and every task the agent runs uses the same accounts.

Allow, Ask and Deny

• A rule can cover a whole app or one action. A rule on a single action takes precedence over the app's rule, and a rule saved on a task takes precedence over the agent's rule for that task.
• An action that uses more than one app needs every one of those apps to allow it. Any Deny refuses it, and any Ask makes it wait.
• When a task was started by another task, the rules of the task that started it also apply. Any Deny in the chain refuses the action, and any Ask in the chain makes it wait.
• Looking up options for a form field or refreshing an action's fields checks your rules, but it never uses up an approval. Running an action, sending a proxy request or uploading a file uses it up.
• Brainbase checks rules before app execution. Changing a rule affects later calls, even in a running task; it cannot undo an action already sent to the app.

Which runtimes get integrations

The canary supports Claude Code (claude_code), Codex (codex), Qwen Code (qwen), OpenCode (opencode), Pi (pi) and Kafka Cloud (kafka_cloud). You don't add the server to the agent's MCP list. Brainbase adds it to each enabled turn. Cursor (cursor), Factory (factory) and Qoder (qoder) are deferred. Kafka Cloud is enabled only within the canary while its full compatibility checks continue. Outside the canary, its existing AppFactory path continues; the older kafka runtime is unchanged. See AppFactory for the connection restrictions during enabled managed execution, including synchronous code and workflow app nodes on a compatible runner.

Integrations are turned on one runtime at a time, and at first only for selected agents or organizations. Until then, agents on that runtime do not get the brainbase-apps tools. Once a runtime is enabled for an agent, new tasks get the tools. A task that started before that point does not; start a new task. A task whose sandbox runs an older Brainbase runner gets them once its sandbox is upgraded, and the task view says so in the meantime.

A selected agent, including a new agent in a configured organization, has rule controls on the Tools page for its enabled runtime. Other non-Kafka agents may still see "Integration permission controls are only available for Kafka runtime agents." Kafka agents keep their existing controls. Seeing controls does not by itself mean the new execution path is enabled.

To call your apps from your own code instead of a hosted task, see Integrations from your code.

Organization-scoped rollout

A selected organization covers its current and newly created agents on enabled runtimes, without manual enrollment. These agents get the same integration tools and rule controls as explicitly selected agents. Moving an agent out of the organization or withdrawing organization scope removes org-based eligibility, unless the agent is also explicitly selected. Existing AppFactory grandfather connections remain protected; new agents use the built-in MCP server instead.

What the agent sees

The agent sees one MCP server named brainbase-apps. The name is reserved: on a task that has integrations, an MCP server of your own with that name is replaced by the built-in one. The server's tools are the same on every runtime.

run_action, proxy_request and upload_file take an optional operation_id. If the agent leaves it out, one is generated and returned. Calling again with the same operation_id and the same input never runs the action twice. A call that already succeeded returns success with data.replayed: true (the original data is not returned again), and one that failed returns an error saying the operation ran and failed. Reusing an operation_id with different input is refused with invalid_input. These receipts belong to the task's shared context; a new independent task does not share them.

Results and errors

Every tool returns the same result shape. status tells the agent what happened. The matching field carries the result, approval, denial or error; an error can also include supporting data, and files can contain file information.

{
  "contract": "brainbase.integrations/v1",
  "status": "error",
  "operation_id": "6f0c2a4e-2b1d-4c47-9a63-0d1f5c2e8b11",
  "data": null,
  "result_ref": null,
  "files": [],
  "pending": null,
  "denied": null,
  "error": {
    "code": "needs_connection",
    "message": "This agent has no connected gmail account. An agent manager connects one in the agent's Tools page.",
    "retryable": false,
    "dispatched": "no",
    "action_required": { "kind": "connect_account", "app_slug": "gmail" }
  }
}

When the outcome is unknown

outcome_unknown means the request left Brainbase but no answer came back from the app, for example after a timeout. The message may have been sent, the record may have been created, or neither. Brainbase never sends it again on its own, because doing so could send it twice.

Until someone resolves it, other app execution in the same context answers busy. This includes tasks that share a parent context. Stopping the task does not clear it. A manager checks the app to see whether the action happened, then acknowledges it in the task view (see Integrations in the task view). Acknowledging only unblocks the task and records what the manager found. It never sends the action again, and calling again with the same operation_id still returns outcome_unknown. If it did not happen, ask the agent to do it again.

When an action is cancelled

cancelled always means nothing was sent. It happens when the task was stopped or redirected while the action was waiting, when the approval the action was waiting on was already used by another action, or when a request from your own code expired before anyone answered it. The same operation_id keeps returning cancelled; call again with a new one, which asks for a new approval if one is needed.

Approving an Ask

When an action has an Ask rule, the call returns pending and nothing is sent to the app. Brainbase stops the task's current run, and the approval request appears in the task view in the console. The task waits there until someone answers. It does not depend on the agent noticing anything.

On Kafka Cloud, a task paused for its current integration approval shows Needs info with the summary Awaiting integration approval. This also applies when the agent called the action through bb-apps. Answer the pending request to continue in a new turn. Choosing Stop cancels that request; a failed action still reports its failure.

1. The agent calls the action. The call returns pending, and the agent is told to stop and wait.
2. Brainbase stops the run. The task view shows a card naming the action the agent asked to run, for example slack.slack-send-message.
3. Someone with access to the task answers it.
4. Brainbase starts a new turn and tells the agent the answer. The agent calls the action again, and it runs, or it gets denied.

• Each request is answered once. A second answer, or an answer from an old or expired card, is refused and changes nothing.
• If the task's run cannot be stopped cleanly, the card stays in the task view and can still be answered, and the task view says the stop is being retried. The agent continues only after that run has stopped, and the action never runs before someone approves it.
• If the task was started by another task whose rules also ask for this action, the card says so. Allow once covers both. Allow for this task and Always allow save your rule, but the other task's rule still asks, so the task keeps waiting.
• Stopping the task, or sending it a new message that redirects it, cancels the waiting request. The action does not run and returns cancelled.

Integrations in the task view

For a task using the new integration path, the task view shows whether it can use your apps. It describes that task only. Connecting accounts, adding apps and setting rules on the Tools page never depend on a task: they work for an agent with no tasks, and one old or blocked task never stops them.

A task that started before integrations were enabled for its agent shows none of these. Whether the runner is ready is shown once the task's sandbox has started at least once.

• Only managers of the context's agent (its owner or the team's owners and admins) can acknowledge, from their own signed-in session. For delegated tasks, this can be the parent agent's manager. API keys, personal access tokens, task keys and integration grants are refused. Other members see the card without the choices.
• Each acknowledgement is recorded with who made it, when, and what they found. Acknowledging the same action again changes nothing.

Large results

By default, successful result data bigger than 32 KiB is saved instead of being returned inline. It is written as JSON to a file in the task's workspace under /workspace/.brainbase/integration-results/, named after the operation_id (or a generated name for tools without one). The call returns result_ref instead of data, with the file path, its size, the number of items, where the main list of items sits in the JSON, and up to three sample items. The agent can read the file, or process it with a script, without loading every row into its context.

{
  "status": "success",
  "data": null,
  "result_ref": {
    "path": "/workspace/.brainbase/integration-results/6f0c2a4e-2b1d-4c47-9a63-0d1f5c2e8b11.json",
    "format": "json",
    "bytes": 912340,
    "sha256": "9b1c…",
    "items": 500,
    "item_path": "ret.values",
    "summary": "A JSON object whose largest array, ret.values, has 500 items, each an array.",
    "sample": [["2026-10-01", "Acme", 1200], ["2026-10-01", "Globex", 940], ["2026-10-02", "Initech", 310]]
  }
}

To keep results small in the first place, pass output to run_action. Within the action's ret result, fields selects the listed paths and filter keeps matching items when ret is a list. A filter tests whether the value at a path equals or contains a value. These options do not shrink exports or summary. max_inline_bytes sets the inline limit for one call, up to 256 KiB.

Scripting with bb-apps

Enabled hosted tasks on the current runner have a bb-apps command on their path. It runs one brainbase-apps tool and prints the result as JSON, so the agent can loop over rows in a shell script or any language. It goes through the same rules, approvals and accounts as the MCP tools and has no other credentials.

# bb-apps <tool> [--json '<input>' | --input <file> | --input -] [--output <file>] [--wait]
bb-apps list_apps
bb-apps search_actions --json '{"app_slug": "slack", "query": "send message"}'
bb-apps run_action --input message.json

# A loop that stops at the first action that does not succeed,
# and cleanly when one needs approval
while IFS= read -r row || [ -n "$row" ]; do
  bb-apps run_action --json "$row"
  code=$?
  if [ "$code" -eq 10 ]; then
    echo "Waiting for approval; this run is stopping." >&2
    exit 10
  elif [ "$code" -ne 0 ]; then
    exit "$code"
  fi
done < rows.jsonl

• --output <file> saves a successful result to a new file in the workspace (never overwriting one) and prints result_ref in place of data.
• In a hosted task, an approval stops the run, so bb-apps exits with 10 even with --wait. For standalone approval waiting, use the SDK or a plain MCP client. Local CLI harness setup is deferred.

For loops that write to an app, give each item its own fixed operation_id in the input. If the script is stopped part way and runs again in the next turn, items that already ran return success with data.replayed: true instead of running twice.

Troubleshooting