feat(appkit): add the omnigent plugin on managed Omnigent (1/3)

Gives the app's users Omnigent agent sessions (Claude Agent SDK, Pi,
OpenAI Agents SDK) on the workspace's managed Omnigent server. Every call
carries the signed-in user's token, so each session belongs to that user,
runs on a Databricks Sandbox host and calls models through Unity Gateway.

- Session routes under /api/omnigent relay to /api/2.0/omnigent and are
  limited to sessions this app created.
- Harnesses are offered the UC system.ai models whose API types they
  speak.
- A clear setup error when the app's user token lacks all-apis, which
  managed Omnigent requires and an account admin adds to the app's OAuth
  integration.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: Noah Solomon <noah@databricks.com>

Author: noah-databricks

docs/docs/plugins/omnigent.md

@@ -0,0 +1,80 @@
+# Omnigent
+
+<!-- AUTO-GENERATED: stability-banner-start -->
+:::warning Beta plugin
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md).
+:::
+<!-- AUTO-GENERATED: stability-banner-end -->
+
+The `omnigent` plugin gives your app's users [Omnigent](https://docs.databricks.com/aws/en/omnigent/) agent sessions: Claude Agent SDK, Pi and OpenAI Agents SDK, on the workspace's managed Omnigent.
+
+- **Sessions belong to the signed-in user.** Every call carries the user's token, so a session is theirs, appears in `<workspace>/omnigent`, and is private to them until they share it.
+- **Each session runs on a Databricks Sandbox**, so agent-written code runs in an isolated, Databricks-managed box with the user's own permissions.
+- **Model calls go through Unity Gateway**, with its governance, limits and usage tracking.
+
+Omnigent owns the agent loop: sessions, history, approvals. Use the [`agents`](./agents.md) plugin when you want AppKit to own the loop against one serving endpoint. Use `omnigent` when you want the harnesses themselves.
+
+## Install
+
+```ts
+import { createApp, server } from "@databricks/appkit";
+import { omnigent } from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [
+    server(),
+    omnigent({ instructions: "You help the team explore order data." }),
+  ],
+});
+```
+
+## Workspace setup
+
+- **Previews.** Enable the **Omnigent** and **Databricks Sandbox** previews in the workspace. Omnigent needs a region that supports Unity Gateway; Sandbox hosts are in select AWS regions.
+- **The `all-apis` scope on the app.** Managed Omnigent only accepts tokens with the `all-apis` scope, which an app's user authorization cannot request itself. An account admin adds it to the app's OAuth integration once, keeping the app's existing scopes:
+
+  ```bash
+  databricks apps get <app-name> -o json   # oauth2_app_integration_id, effective_user_api_scopes
+  databricks account custom-app-integration update <oauth2_app_integration_id> \
+    --json '{"scopes": ["<existing scopes>", "all-apis"]}'
+  ```
+
+  The update replaces the whole scope list. New scopes can take up to an hour to reach users' tokens. A bundle deploy, or a change to the app's user API scopes, sets the scopes back to the declared list, so repeat the update after either.
+
+`GET /api/omnigent/status` reports whether the user can reach managed Omnigent, and why not.
+
+## Configuration
+
+| Option | Default | |
+|---|---|---|
+| `instructions` | a generic assistant prompt | System instructions for every session |
+| `harnesses` | `claude-sdk`, `pi`, `openai-agents` | Harnesses users may pick |
+| `defaultHarness`, `defaultModel` | first available | |
+
+Each harness is offered the Unity Gateway `system.ai` models whose API it speaks: Claude Agent SDK the Anthropic Messages API, Pi the Codex Responses API, OpenAI Agents SDK the OpenAI Responses API.
+
+## Routes
+
+All routes are under `/api/omnigent` and act as the signed-in user. Sessions are limited to the ones this app created.
+
+| Route | |
+|---|---|
+| `GET /status` | Whether managed Omnigent and Sandbox hosts are usable |
+| `GET /harnesses` | Harnesses available to the user, each with the models it can drive |
+| `GET /sessions`, `POST /sessions` | List, create (`harness`, `model`, `message`, `title`) |
+| `GET /sessions/:id`, `DELETE /sessions/:id` | Snapshot (items, status), delete |
+| `POST /sessions/:id/messages` | `{ "text": "..." }` |
+| `GET /sessions/:id/stream` | Server-sent events (Omnigent's session stream, which replays from `Last-Event-ID`) |
+| `POST /sessions/:id/interrupt` | Stop the current turn |
+
+Creating a session returns once its Sandbox host is up, about 30 seconds on a cold start.
+
+## Local development
+
+With `NODE_ENV=development` and no forwarded token, the plugin calls Omnigent as the developer, with the token of the app's local Databricks CLI profile.
+
+## Limits
+
+- **Beta, in Omnigent's regions.** The plugin needs the workspace's managed Omnigent; it does not run Omnigent itself.
+- **Only gateway harnesses.** Harnesses that sign in with their vendor (Cursor, Copilot, Gemini and others) are not offered. Codex is not offered yet: on a Sandbox host, its brokered sign-in rejects the Codex CLI version the Sandbox ships.
+- **Broad app scope.** The `all-apis` scope lets the app call any API the user can, on the user's behalf.

packages/appkit/src/plugins/beta-exports.generated.ts

@@ -0,0 +1,60 @@
+import { gzipSync } from "node:zlib";
+
+interface BundleSpec {
+  name: string;
+  description?: string;
+  harness: string;
+  model: string;
+  instructions: string;
+}
+
+/**
+ * An Omnigent agent bundle: `config.yaml` (the agent spec) and `AGENTS.md`
+ * (the instructions), as a tar.gz. The YAML is written as JSON, which is
+ * valid YAML.
+ */
+export function buildBundle(spec: BundleSpec): Buffer {
+  const config = {
+    spec_version: 1,
+    name: spec.name,
+    description: spec.description ?? spec.name,
+    executor: {
+      type: "omnigent",
+      model: spec.model,
+      config: { harness: spec.harness },
+    },
+    instructions: "AGENTS.md",
+  };
+  const files: Record<string, string> = {
+    "config.yaml": `${JSON.stringify(config, null, 2)}\n`,
+    "AGENTS.md": spec.instructions,
+  };
+  return gzipSync(tar(files));
+}
+
+/** Minimal ustar writer: regular files only, names under 100 bytes. */
+function tar(files: Record<string, string | Buffer>): Buffer {
+  const blocks: Buffer[] = [];
+  const mtime = Math.floor(Date.now() / 1000);
+  for (const [name, content] of Object.entries(files)) {
+    if (Buffer.byteLength(name) >= 100)
+      throw new Error(`tar: name too long: ${name}`);
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const header = Buffer.alloc(512);
+    header.write(name, 0, 100);
+    header.write("0000644\0", 100);
+    header.write("0000000\0", 108);
+    header.write("0000000\0", 116);
+    header.write(`${data.length.toString(8).padStart(11, "0")}\0`, 124);
+    header.write(`${mtime.toString(8).padStart(11, "0")}\0`, 136);
+    header.write("        ", 148); // checksum placeholder
+    header.write("0", 156);
+    header.write("ustar\u000000", 257);
+    let sum = 0;
+    for (const b of header) sum += b;
+    header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
+    blocks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+  }
+  blocks.push(Buffer.alloc(1024));
+  return Buffer.concat(blocks);
+}

packages/appkit/src/plugins/omnigent/bundle.ts

@@ -0,0 +1,57 @@
+/**
+ * Calls the workspace's managed Omnigent server (`/api/2.0/omnigent`) with
+ * the signed-in user's token, so sessions, Sandbox hosts and model calls are
+ * the user's own.
+ */
+export class ManagedOmnigent {
+  constructor(private readonly host: () => Promise<string>) {}
+
+  async request(
+    token: string,
+    method: string,
+    path: string,
+    init: {
+      json?: unknown;
+      body?: RequestInit["body"];
+      headers?: Record<string, string>;
+      signal?: AbortSignal;
+    } = {},
+  ): Promise<Response> {
+    const r = await fetch(`${await this.host()}/api/2.0/omnigent${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...(init.json !== undefined
+          ? { "content-type": "application/json" }
+          : {}),
+        ...init.headers,
+      },
+      body: init.json !== undefined ? JSON.stringify(init.json) : init.body,
+      signal: init.signal,
+      redirect: "manual",
+    });
+    if (r.status === 403) {
+      const text = await r.clone().text();
+      if (text.includes("required scopes: all-apis")) {
+        throw new OmnigentScopeError();
+      }
+    }
+    return r;
+  }
+}
+
+/**
+ * Managed Omnigent only accepts tokens with the `all-apis` scope, which a
+ * Databricks App's user authorization cannot request itself.
+ */
+export class OmnigentScopeError extends Error {
+  readonly status = 403;
+  constructor() {
+    super(
+      "Omnigent needs this app's user token to carry the all-apis scope. " +
+        "An account admin adds it to the app's OAuth integration: " +
+        "databricks account custom-app-integration update <app oauth2_app_integration_id> " +
+        "with the app's current scopes plus all-apis. It can take up to an hour to reach users' tokens.",
+    );
+  }
+}

packages/appkit/src/plugins/omnigent/client.ts

@@ -0,0 +1,78 @@
+interface HarnessInfo {
+  label: string;
+  /**
+   * Unity Gateway API types it calls (a UC model service's
+   * `supported_api_types`); a model must support one of them.
+   */
+  apis: string[];
+  /** Default models, best first, when the workspace has them. */
+  preferred: string[];
+}
+
+/**
+ * Harnesses whose model calls a Databricks Sandbox routes through Unity
+ * Gateway. The other harnesses Omnigent supports sign in with their vendor,
+ * so they are not offered. Codex is left out for now: on a Sandbox host its
+ * brokered sign-in rejects the Codex CLI version the Sandbox ships.
+ */
+const GATEWAY_HARNESSES: Readonly<Record<string, HarnessInfo>> = {
+  "claude-sdk": {
+    label: "Claude Agent SDK",
+    apis: ["anthropic/v1/messages"],
+    preferred: ["system.ai.claude-sonnet-5", "system.ai.claude-opus-5-5"],
+  },
+  pi: {
+    label: "Pi",
+    // Pi reaches Databricks models through the Codex responses API; on the
+    // chat-completions path Gemini fails with an empty 400 (tested).
+    apis: ["codex/v1/responses"],
+    preferred: ["system.ai.gpt-5-5"],
+  },
+  "openai-agents": {
+    label: "OpenAI Agents SDK",
+    apis: ["openai/v1/responses"],
+    preferred: ["system.ai.gpt-5-5"],
+  },
+};
+
+export const DEFAULT_HARNESSES = Object.keys(GATEWAY_HARNESSES);
+
+/** A Unity Gateway model, e.g. `system.ai.claude-sonnet-5`. */
+export interface GatewayModel {
+  name: string;
+  /** The model service's `supported_api_types`. */
+  apiTypes: string[];
+}
+
+/** A harness the user can pick, with the models it can drive. */
+export interface HarnessOffer {
+  id: string;
+  label: string;
+  models: string[];
+  defaultModel?: string;
+}
+
+/**
+ * What a user can pick: the allowed gateway harnesses, each with the models
+ * whose API it speaks.
+ */
+export function offerHarnesses(opts: {
+  allowed: string[];
+  models: GatewayModel[];
+}): HarnessOffer[] {
+  const out: HarnessOffer[] = [];
+  for (const id of opts.allowed) {
+    const info = GATEWAY_HARNESSES[id];
+    if (!info) continue;
+    const models = opts.models
+      .filter((m) => m.apiTypes.some((t) => info.apis.includes(t)))
+      .map((m) => m.name);
+    out.push({
+      id,
+      label: info.label,
+      models,
+      defaultModel: info.preferred.find((m) => models.includes(m)) ?? models[0],
+    });
+  }
+  return out;
+}

packages/appkit/src/plugins/omnigent/harnesses.ts

@@ -0,0 +1,2 @@
+export * from "./omnigent";
+export * from "./types";

packages/appkit/src/plugins/omnigent/index.ts

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "omnigent",
+  "displayName": "Omnigent Plugin",
+  "description": "Omnigent agent sessions for the app's users on the workspace's managed Omnigent: Claude Agent SDK, Pi and OpenAI Agents SDK on Databricks Sandboxes, with models through Unity Gateway",
+  "stability": "beta",
+  "resources": {
+    "required": [],
+    "optional": []
+  },
+  "scaffolding": {
+    "rules": {
+      "must": [
+        "Enable the Omnigent and Databricks Sandbox previews in the workspace",
+        "Account admin: add all-apis to the app's OAuth integration (databricks account custom-app-integration update)",
+        "Re-run that update after a bundle deploy or a user_api_scopes change, which both drop all-apis"
+      ]
+    }
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "instructions": {
+          "type": "string",
+          "description": "System instructions for every session"
+        },
+        "harnesses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Harnesses users may pick"
+        },
+        "defaultHarness": {
+          "type": "string"
+        },
+        "defaultModel": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}