AppFactory (legacy)
AppFactory is the Python client Kafka agents use to call connected apps from notebook code, with from integrations import AppFactory. During managed turns and synchronous code operations on enabled Kafka Cloud (kafka_cloud) canary agents, AppFactory calls the new integration service through a compatibility layer. Other agents keep the existing integration path.
Current availability
The older kafka runtime is unchanged. Its AppFactory copy in kafka-lite-vm and the legacy /pipedream/* routes remain available. The Kafka Cloud connection list does not apply to that runtime: both new and existing legacy Kafka agents can still use AppFactory, including for apps they connect later.
Enabled Kafka Cloud connections
During managed execution with integrations enabled, AppFactory uses the new integration service as a temporary compatibility layer. Brainbase records which agent, app and exact connected account may keep using it. An existing connection is covered only if it is on that list. AppFactory stays in the Kafka image; the switch does not require changing imports in saved code for those connections.
| During enabled managed execution | What to expect |
|---|---|
| A recorded app and account | AppFactory can keep using that connection, subject to its Allow, Ask and Deny rules. |
| The recorded account is disconnected and replaced by a new account | The replacement must use the brainbase-apps tools. The old connection is retired from AppFactory when the compatibility layer detects the change. |
| An app or account is not on the list | Use the brainbase-apps tools for it. Having another listed connection does not add this one. |
| A second account is connected while the recorded account remains connected | Only the recorded account is eligible for AppFactory. Use the brainbase-apps tools for the new account. |
| No recorded connection remains usable, or the agent has no recorded connections | Integration calls through the AppFactory compatibility layer are refused. Use the brainbase-apps tools. |
A refused compatibility call is stopped before it reaches the app. Report the refusal when running a saved program unchanged; do not silently rewrite it, reconnect the account or switch tools. Use the new tools when separately preparing code for that connection. Refusal does not disconnect accounts or change permission rules. Once a connection is retired from AppFactory, adding it to the list again does not restore it.
factory.get_auth_link() keeps its existing behavior: it returns a connection link when available, or None. It continues to use the legacy connection-link route before and after the switch. Connecting an account does not make it eligible for the new AppFactory compatibility layer.
Running saved programs
Run a supplied AppFactory program through Python in the notebook. Keep its variables, API calls, arguments and result expressions. Native MCP tools with similar names are not substitutes for those Python calls. app.action(slug) validates the supplied slug against the app catalogue itself; an extra discovery call is unnecessary. Use discovery when choosing a new or unknown action.
Existing statements may be split into notebook cells, in order, to inspect access and permission results. Do not add probes or output wrappers. Stop if inspection requires changing the program, an input or account is missing, approval is pending, or access is denied. Saved code does not establish eligibility for compatibility or grant approval; the recorded connection and permission checks still apply.
Synchronous code and workflow operations
On enabled Kafka Cloud agents with a compatible runner, synchronous task code and workflow app nodes use the same connection restrictions, permission rules and integration accounting as managed turns. Saved AppFactory imports and configured inputs do not need to change. Missing inputs remain missing; enabling this path does not fill them or approve an action. An incompatible runner refuses managed execution rather than sending integration calls through the legacy path.
When an app action needs approval, Brainbase stops that code operation and shows the approval in the task view. While an answer is pending, the task-code response includes pending; its continuation is "new_code_operation_required". Answering the approval does not rerun code automatically. After Allow once, explicitly submit a new code operation with the same action inputs; the approval can be used only once. Stop cancels pending approval.
Retrying the same outer code operation ID returns its stored result; it does not execute the code again. If an action's outcome is unknown, check what happened in the app before submitting new work. Agents where the managed path is disabled keep the existing legacy behavior.
Preparing code for the app tools
These replacements apply to Kafka Cloud agents with the new tools enabled. Keep using the current path until Brainbase enables them for your agent. The tools use the same connected accounts and permission rules; account connections remain managed on the agent's Tools page.
| AppFactory | Use instead |
|---|---|
factory.list_apps(), factory.get_connected_accounts() | list_apps |
app.list_actions(), app.search_actions() | search_actions |
print(action) | get_action |
action.get_options_for_prop(), action.configure() | configure_prop, reload_props |
app(...).action(...).run() | run_action |
factory.proxy_get() and the other proxy_* methods, factory.custom_request() | proxy_request |
factory.proxy_upload_file() | upload_file with source: {"kind": "workspace_path", "path": "/workspace/..."} |
factory.proxy_upload_from_url() | upload_file with source: {"kind": "public_url", "url": "..."} |
factory.get_auth_link() | None. An agent manager connects accounts on the agent's Tools page. |
| A Python loop over app data | The bb-apps command, from the shell or from Python |
# Once the new tools are enabled for this hosted agent:
bb-apps list_apps --json '{"include":"connected"}'
Use the mapping above when preparing instructions and playbooks for the new tools. A copy of an agent does not inherit its recorded AppFactory connections.
Notebook restart recovery
Kafka Cloud notebooks save Python values between worker restarts. A file handle is an open or closed Python file object, not the file itself. On runtimes with the notebook checkpoint fix, disk handles are omitted from that saved state. A list, object or function that captures a handle is omitted too. The cell reports the affected variable names as "checkpoint skipped unsafe or unpicklable names". Those variables remain usable in the current worker; unrelated checkpointable values and cell numbers survive a restart.
Keep the file path and the data you need, rather than relying on a file handle to survive a restart. Reopen an existing output in read mode when inspecting it. Do not rerun an app action or recreate an export just to rebuild notebook variables: the original operation may already have completed.
Healthy saved notebooks keep their existing values, imports, functions and cell numbers after an upgrade. When an older saved notebook contains a file handle, recovery skips that handle and any values that cannot be restored safely. It keeps unrelated recoverable values and the cell number. The warning "restore skipped unsafe or unsupported names" lists omitted variables. Custom objects or functions depending on an omitted value may need to be recreated explicitly.