Class: TeamsPlugin

AppKit plugin that configures an instance-owned Adaptive Card runtime and exposes card building as an AppKit agent tool.

Example

import { createApp, server } from "@databricks/appkit";
import { teams } from "@dbx-tools/teams";

await createApp({
  plugins: [
    server(),
    teams({ webhookUrl: process.env.TEAMS_WEBHOOK_URL }),
  ],
});

Extends

• ToolRegistryPlugin<TeamsPluginConfig>

Constructors

Constructor

new TeamsPlugin(config): TeamsPlugin

Parameters

config

TeamsPluginConfig

Returns

TeamsPlugin

Inherited from

ToolRegistryPlugin<TeamsPluginConfig>.constructor

Properties

app

protected app: AppManager

Inherited from

ToolRegistryPlugin.app

---

cache

protected cache: CacheManager

Inherited from

ToolRegistryPlugin.cache

---

config

protected config: TeamsPluginConfig

Inherited from

ToolRegistryPlugin.config

---

context?

protected optional context?: PluginContext

Inherited from

ToolRegistryPlugin.context

---

devFileReader

protected devFileReader: DevFileReader

Inherited from

ToolRegistryPlugin.devFileReader

---

isReady

protected isReady: boolean

Inherited from

ToolRegistryPlugin.isReady

---

name

name: string

Plugin name identifier.

Inherited from

ToolRegistryPlugin.name

---

streamManager

protected streamManager: StreamManager

Inherited from

ToolRegistryPlugin.streamManager

---

telemetry

protected telemetry: ITelemetry

Inherited from

ToolRegistryPlugin.telemetry

---

toolRegistry

protected readonly toolRegistry: ToolRegistry

The tool this plugin offers to an AppKit agent.

Marked autoInheritable: building a card is a pure, side-effect-free transform (nothing leaves the building), so it is safe to hand to any agent by default - unlike a send.

execute re-parses its arguments with the local schema: AppKit validates against the same schema first, but re-parsing is what gives the body typed arguments instead of unknown.

Overrides

ToolRegistryPlugin.toolRegistry

---

manifest

static manifest: object

config

config: object

config.schema

schema: JSONSchema7 = TEAMS_CONFIG_SCHEMA

description

description: string

displayName

displayName: string = "Teams"

name

name: "teams" = "teams"

resources

resources: object

resources.optional

optional: never[] = []

resources.required

required: never[] = []

stability

stability: "beta" = "beta"

---

phase

static phase: PluginPhase

Plugin initialization phase.

• ‘core’: Initialized first (e.g., config plugins)
• ‘normal’: Initialized second (most plugins)
• ‘deferred’: Initialized last (e.g., server plugin)

Inherited from

ToolRegistryPlugin.phase

Methods

abortActiveOperations()

abortActiveOperations(): void

Cancel in-flight work (abort signals, SSE streams). Runs in the first phase of graceful shutdown, BEFORE any plugin’s shutdown() hook — so it must not tear down shared resources (e.g. connection pools) that other plugins’ hooks may still need. Put teardown in shutdown().

Returns

void

Inherited from

ToolRegistryPlugin.abortActiveOperations

---

asUser()

asUser(req): this

Execute operations using the user’s identity from the request. Returns a proxy of this plugin where all method calls execute with the user’s Databricks credentials instead of the service principal.

Parameters

req

Request

The Express request containing the user token in headers

Returns

this

A proxied plugin instance that executes as the user

Throws

AuthenticationError if user token is not available in request headers (production only). In development mode (NODE_ENV=development), skips user impersonation instead of throwing.

Inherited from

ToolRegistryPlugin.asUser

---

attachContext()

attachContext(deps?): void

Binds runtime dependencies (telemetry provider, cache, plugin context) to this plugin. Called by AppKit._createApp after construction and before setup(). Idempotent: safe to call if the constructor already bound them eagerly. Kept separate so factories can eagerly construct plugin instances without running this before TelemetryManager.initialize() / CacheManager.getInstance() have run.

Parameters

deps?

context?

unknown

telemetryConfig?

TelemetryOptions

Returns

void

Inherited from

ToolRegistryPlugin.attachContext

---

clientConfig()

clientConfig(): Record<string, unknown>

Returns startup config to expose to the client. Override this to surface server-side values that are safe to publish to the frontend, such as feature flags, resource IDs, or other app boot settings.

This runs once when the server starts, so it should not depend on request-scoped or user-specific state.

String values that match non-public environment variables are redacted unless you intentionally expose them via a matching PUBLIC_APPKIT_ env var.

Values must be JSON-serializable plain data (no functions, Dates, classes, Maps, Sets, BigInts, or circular references). By default returns an empty object (plugin contributes nothing to client config).

On the client, read the config with the usePluginClientConfig hook (React) or the getPluginClientConfig function (vanilla JS), both from @databricks/appkit-ui.

Returns

Record<string, unknown>

Example

// Server — plugin definition
class MyPlugin extends Plugin<MyConfig> {
  clientConfig() {
    return {
      warehouseId: this.config.warehouseId,
      features: { darkMode: true },
    };
  }
}

// Client — React component
import { usePluginClientConfig } from "@databricks/appkit-ui/react";

interface MyPluginConfig { warehouseId: string; features: { darkMode: boolean } }

const config = usePluginClientConfig<MyPluginConfig>("myPlugin");
config.warehouseId; // "abc-123"

// Client — vanilla JS
import { getPluginClientConfig } from "@databricks/appkit-ui/js";

const config = getPluginClientConfig<MyPluginConfig>("myPlugin");

Inherited from

ToolRegistryPlugin.clientConfig

---

execute()

protected execute<T>(fn, options, userKey?): Promise<ExecutionResult<T>>

Execute a function with the plugin’s interceptor chain.

Returns an ExecutionResult discriminated union:

• { ok: true, data: T } on success
• { ok: false, status: number, message: string } on failure

Errors are never thrown — the method is production-safe.

Type Parameters

T

T

Parameters

fn

(signal?) => Promise<T>

options

PluginExecutionSettings

userKey?

string

Returns

Promise<ExecutionResult<T>>

Inherited from

ToolRegistryPlugin.execute

---

executeAgentTool()

executeAgentTool(name, args, signal?, _context?): Promise<unknown>

Validate and dispatch one AppKit agent tool call.

Parameters

name

string

args

unknown

signal?

AbortSignal

_context?

AgentToolExecutionContext

Returns

Promise<unknown>

Inherited from

ToolRegistryPlugin.executeAgentTool

---

executeStream()

protected executeStream<T>(res, fn, options, userKey?): Promise<void>

Type Parameters

T

T

Parameters

res

IAppResponse

fn

StreamExecuteHandler<T>

options

StreamExecutionSettings

userKey?

string

Returns

Promise<void>

Inherited from

ToolRegistryPlugin.executeStream

---

exports()

exports(): object

Returns the public exports for this plugin. Override this to define a custom public API. By default, returns an empty object.

The returned object becomes the plugin’s public API on the AppKit instance (e.g. appkit.myPlugin.method()). AppKit automatically binds method context and adds asUser(req) for user-scoped execution.

Returns

buildCard

buildCard: (spec, signal?) => Promise<{ card: { $schema: string; actions?: Record<string, unknown>[]; body: Record<string, unknown>[]; type: "AdaptiveCard"; version: string; }; title: string; }>

Compile a card spec into an Adaptive Card document. For agent-driven builds use teamsCardTool instead.

Parameters

spec

actions?

object[] = ...

facts?

object[] = ...

subtitle?

string = ...

text?

string = ...

title

string = ...

signal?

AbortSignal

Returns

Promise<{ card: { $schema: string; actions?: Record<string, unknown>[]; body: Record<string, unknown>[]; type: "AdaptiveCard"; version: string; }; title: string; }>

postCard

postCard: (cardDocument, signal?) => Promise<void>

Post a compiled card to the configured Teams incoming webhook. Throws when no webhook is configured.

Parameters

cardDocument

$schema

string = ...

actions?

Record<string, unknown>[] = ...

body

Record<string, unknown>[] = ...

type

"AdaptiveCard" = ...

version

string = ...

signal?

AbortSignal

Returns

Promise<void>

Example

class MyPlugin extends Plugin {
  private getData() { return []; }

  exports() {
    return { getData: this.getData };
  }
}

// After registration:
const appkit = await createApp({ plugins: [myPlugin()] });
appkit.myPlugin.getData();

Overrides

ToolRegistryPlugin.exports

---

getAgentTools()

getAgentTools(): AgentToolDefinition[]

Tool definitions offered to an AppKit agent.

Returns

AgentToolDefinition[]

Inherited from

ToolRegistryPlugin.getAgentTools

---

getEndpoints()

getEndpoints(): PluginEndpointMap

Returns

PluginEndpointMap

Inherited from

ToolRegistryPlugin.getEndpoints

---

getSkipBodyParsingPaths()

getSkipBodyParsingPaths(): ReadonlySet<string>

Returns

ReadonlySet<string>

Inherited from

ToolRegistryPlugin.getSkipBodyParsingPaths

---

injectRoutes()

injectRoutes(router): void

Mount the card-building and card-posting routes under the plugin base path (/api/teams). POST /card is what the dev display page calls to preview a card live; POST /post pushes a compiled card to the configured Teams incoming webhook.

Neither route is wrapped in asUser(req): compiling a card is a pure transform of the request body and posting goes to a preconfigured webhook, so neither reads workspace data on the caller’s behalf and neither needs an OBO token. Wrapping them would make the routes throw AuthenticationError whenever the user-token header is absent (a local curl, a health probe), which - since AppKit does not catch a rejection raised inside the handler - takes the process down rather than answering 401.

Parameters

router

Router

Returns

void

Overrides

ToolRegistryPlugin.injectRoutes

---

registerEndpoint()

protected registerEndpoint(name, path): void

Parameters

name

string

path

string

Returns

void

Inherited from

ToolRegistryPlugin.registerEndpoint

---

resolveUserId()

protected resolveUserId(req): string

Resolve the effective user ID from a request.

Returns the x-forwarded-user header when present. In development mode (NODE_ENV=development) falls back to the current context user ID so that callers outside an active runInUserContext scope still get a consistent value.

Parameters

req

Request

Returns

string

Throws

AuthenticationError in production when no user header is present.

Inherited from

ToolRegistryPlugin.resolveUserId

---

route()

protected route<_TResponse>(router, config): void

Type Parameters

_TResponse

_TResponse

Parameters

router

Router

config

RouteConfig

Returns

void

Inherited from

ToolRegistryPlugin.route

---

setup()

setup(): Promise<void>

Log the effective config so the resolved card version and whether a webhook is wired up are obvious at boot. Runtime construction already resolved config and captured this plugin’s interceptor chain.

Returns

Promise<void>

Overrides

ToolRegistryPlugin.setup

---

shutdown()

shutdown(): void

Release this plugin’s instance-owned runtime.

Returns

void