feat(appkit): supervisor API adapter for agents plugin

[hubertzub-db]

Adds a fourth AgentAdapter targeting the Databricks AI Gateway Responses API, so AppKit apps can host server-side-orchestrated agents (Genie, Knowledge Assistants, UC functions, apps, UC connections) without running the tool loop locally.

import { createApp, createAgent } from "@databricks/appkit";
import { agents, DatabricksAdapter, supervisorTools } from "@databricks/appkit/beta";

const supervisor = createAgent({
  instructions: "You are an assistant powered by the Databricks Supervisor API.",
  model: DatabricksAdapter.fromSupervisorApi({ model: "databricks-claude-sonnet-4-5" }),
  tools: () => ({
    nyc: supervisorTools.genieSpace({ id: "01ABCDEF12345678", description: "NYC taxi trip records and zones" }),
    add: supervisorTools.ucFunction({ name: "main.default.add", description: "Adds two integers and returns the sum." }),
  }),
});

await createApp({ plugins: [agents({ agents: { supervisor } })] });

Hosted tools are declared on the agent (same place as function tools), not on the adapter — the plugin routes them to the Supervisor API. Try it via the supervisor agent in the dev-playground Agent Chat dropdown.

---

Address structural feedback from Mario Cadenas' review of PR #345 (sections 1-8). Stacked on top of the §9 defensive fixes commit.

API changes (BETA surface only):

• Add DatabricksAdapter.fromSupervisorApi static factory for discoverability
  alongside .fromChatCompletions.
• Shrink SupervisorApiAdapterOptions to { model, workspaceClient? }; tools no longer live on the adapter.
• Hosted tools (supervisorTools.*) now return tagged HostedSupervisorTool records and accept named options instead of positional args.
• Declare hosted tools on the agent's tools map (same place as function tools / sub-agents); the agents plugin and runAgent route them to the adapter via the new AgentInput.extensions[SUPERVISOR_EXTENSION_KEY].
• Add capability-negotiation fields to AgentAdapter: acceptsExtensions? + consumesInputTools?. The agents plugin and runAgent warn at registration when adapter capabilities don't match declared tools.

Internals:

• Extend ResolvedToolEntry / StandaloneEntry with a hosted-supervisor branch; classifyTool matches it before MCP hosted-tool rejection so standalone runAgent supports supervisor tools.
• Defense-in-depth: both indexers throw if a hosted-supervisor entry is ever dispatched as a callable function.
• DatabricksAdapter.fromSupervisorApi uses a dynamic import to avoid load-time cycles.

Docs:

• Rewrite supervisor-API section in docs/plugins/agents.md for the new shape.
• Add cross-adapter sub-agent composition note (one-directional: chat parents can call supervisor children, not vice-versa, until SA's function-call events are routed back through context.executeTool).

Playground:

• Update dev-playground supervisor agent to the new shape (DatabricksAdapter.fromSupervisorApi(...) + tools on createAgent).

Tests:

• Rewrite supervisor-api.test.ts factory + adapter tests for the new shape.
• Add isSupervisorTool and DatabricksAdapter.fromSupervisorApi tests.
• New regression tests in run-agent.test.ts covering the hosted-supervisor extension-routing path and both capability-mismatch warnings.
• New agents-plugin tests covering the same warning paths and the new hosted-supervisor tool-index branch.

[pkosiec]

Thank you @hubertzub-db for your contribution! I'd like to merge that shortly after #345
to avoid breaking changes in the API. Could you please take a look at some final comments? Thanks!

PR #400 (agent/v2/sa/1-adapter-fixes) — Fixes

Inherited from PR #345 (fix on #345, picked up via rebase)

All 9 issues from PR #345 apply identically — the code is carried over. Fix on #345 first.

#	File:Line	Issue	Fix
1	supervisor-api.ts:356	readSseEvents throws on oversized blocks but for await loop has no try/catch — unhandled rejection tears down the request	Wrap the for await loop in try/catch. On signal?.aborted return silently, otherwise yield emitError("transport", err). Add test.
2	supervisor-api.ts:397	Empty stream (zero SSE events) returns without terminal status — consumer stuck in "running"	When eventCounts.size === 0, yield emitError("transport", "stream closed without events") before returning. Add test.
3	supervisor-api.ts:428	incomplete_details != null treated as fatal even for benign max_output_tokens truncation	Only treat as fatal when co-occurring with status === "failed" or error != null. Yield recovered text + complete when it's just truncation. Add test.
4	supervisor-api.ts:33	emitError uses %O at warn level, dumping full objects to logs (CWE-532)	Replace logger.warn("... detail=%O", ...) with logger.warn("... detail=%s", code, summariseErrorPayload(detail)). Add logger.debug for full dump.
5	supervisor-api.ts:371	parsed.type as string — missing field produces "undefined" string	Replace with typeof parsed.type === "string" ? parsed.type : ""
6	supervisor-api.ts:544	(data.delta as string) ?? "" — fragile cast	Replace with typeof data.delta === "string" ? data.delta : ""
7	supervisor-api.ts:542	`data.item_id as string	undefined` — non-strings pass through
8	sse-reader.ts:30	maxLineChars name says "line" but guards a "block"	Rename to maxBlockChars (not yet public, safe to rename)
9	supervisor-api.ts:48	summariseErrorPayload — British spelling, codebase uses American	Rename to summarizeErrorPayload

PR #400-specific fixes

P1 — Must fix

#	File:Line	Issue	Fix
10	supervisor-api.ts:650	fromSupervisorApi returns Promise<SupervisorApiAdapter> not Promise<AgentAdapter> — binds consumers to concrete class	Narrow return type to Promise<AgentAdapter>
11	supervisor-api.ts:315	No timeout on streamBody or SSE stream — hangs indefinitely if upstream stalls	Verify TimeoutInterceptor wraps run(). If not, compose AbortSignal.timeout(ms) with context signal.

P2 — Should fix

#	File:Line	Issue	Fix
12	beta.ts:23	SupervisorApiAdapterCtorOptions exported — internal type leaks as stable contract	Remove from beta.ts exports
13	supervisor-api.ts:85	WorkspaceClientLike duplicated across adapters, not exported but used in exported type	Export it, or use ApiClientLike & { config: ... }
14	supervisor-api.ts:654	Double-cast as unknown as WorkspaceClientLike signals structural mismatch	Verify SDK's WorkspaceClient satisfies WorkspaceClientLike structurally; widen the type or narrow the cast
15	supervisor-api.ts:75	StreamBody type duplicated in both adapters	Extract to connectors/serving/client.ts

P3 — Nice to have

#	File:Line	Issue	Fix
16	supervisor-api.ts:101	SupervisorTool closed union — new upstream tool type = breaking change	Consider `

Gap — Mario's Section 6

• Frontmatter-referenced supervisor tools: The mechanism works (tool-index routing composes via agents({ tools: { nyc: supervisorTools.genieSpace(...) } }) + frontmatter tools: [nyc]), but no doc example or test demonstrates this path. Add a doc example and test.

Tests to add

• fromSupervisorApi dynamic-import fallback (no workspaceClient supplied)
• Capability-mismatch warning paths (partially present already)
• Frontmatter-referenced supervisor tool resolution

Mario's Review Status

• Section 9 (15 items): All addressed on PR #345
• Sections 1-8 (structural): 7/8 fully addressed on PR #400, 1 partially (section 6 — frontmatter doc/test gap)
• Section 10 (follow-ups): Acknowledged as non-blocking

[github-actions]

This pull request has had no activity for 23 days and has been marked as stale. It will be closed in 7 days if there is no further activity. Add a comment, push a commit, or apply the no-stale label to keep it open.

[pkosiec]

Tested and it works well!

We need to merge either #400 PR alone, or #345 + #400 very shortly one after another, as #400 has breaking changes in the API and we want to avoid an AppKit release between them.

Please see my last minor comments and we are good to go 👍 Thanks again for your patience and contribution!

[pkosiec]

Can we uncomment this, add the impert, set the Genie space ID as env in dev-playground app (.env.dist, still pointing to the ID you provided here), and ensure we always have a supervisor example in dev playground?

For now, from what I can see it, it's API only example, but we could add the agent: "supervisor" as an option in agent.route.tsx (it currently hardcodes the agent name at lines 78/209). Small edit - add a selector to make it easier to test it 👍

[pkosiec]

🚀 🚀 🚀 Thanks a ton for the pull request!

[pkosiec]

Repushed the PR to verify CI here: #492 (our CI doesn't work with forks currently)

All checks green: https://github.com/databricks/appkit/actions/runs/30355377147/job/90262264986?pr=492

That means the PR is ready to merge 👍