Skip to content

feat(appkit): shared agent types and LLM adapter implementations#301

Merged
MarioCadenas merged 11 commits intomainfrom
agent/v2/1-types-adapters
May 5, 2026
Merged

feat(appkit): shared agent types and LLM adapter implementations#301
MarioCadenas merged 11 commits intomainfrom
agent/v2/1-types-adapters

Conversation

@MarioCadenas
Copy link
Copy Markdown
Collaborator

@MarioCadenas MarioCadenas commented Apr 21, 2026

Foundation layer for the agents feature. Adds the portable type surface
that every downstream layer builds on, plus three LLM adapter
implementations so the agents plugin (later PR) can target whatever the
user has.

Shared agent types

packages/shared/src/agent.ts — no behavior, just the type vocabulary:
AgentAdapter, AgentEvent, AgentInput, AgentRunContext,
AgentToolDefinition, Message, Thread, ThreadStore, ToolAnnotations,
ToolCall, ToolProvider, ResponseStreamEvent. Exported from the
shared barrel.

Adapters

  • packages/appkit/src/agents/databricks.tsDatabricksAdapter:
    streams OpenAI-compatible completions against a Databricks Model
    Serving endpoint. The fromServingEndpoint / fromModelServing
    factories route through the shared connectors/serving/stream
    helper, which delegates to the SDK's apiClient.request({ raw: true }).
    That gives the adapter centralised URL encoding + authentication
    with the rest of the serving surface — no bespoke fetch() +
    authenticate() plumbing. The raw new DatabricksAdapter({ endpointUrl, authenticate }) constructor is preserved as an escape hatch for
    tests and for pointing the adapter at non-workspace endpoints.

Each adapter is self-contained and independently testable.

Test plan

  • 17 adapter tests (Databricks) covering raw-fetch escape hatch,
    serving-connector routing, URL encoding of endpoint names with
    special characters, streaming + tool-call dispatch.
  • Full appkit vitest suite: 1552 tests passing at stack tip.

PR Stack

  1. Shared agent types + LLM adapters (this PR)
  2. Tool primitives + ToolProvider surfaces — feat(appkit): tool primitives and ToolProvider surfaces on core plugins #302
  3. Plugin infrastructure (attachContext + PluginContext) — feat(appkit): plugin infrastructure — attachContext + PluginContext mediator #303
  4. agents() plugin + createAgent(def) + markdown-driven agents — feat(appkit): agents() plugin, createAgent(def), and markdown-driven agents #304
  5. fromPlugin() DX + runAgent plugins arg + toolkit-resolver — feat(appkit): fromPlugin() DX, runAgent plugins arg, shared toolkit-resolver #305
  6. Reference app + dev-playground + docs — feat(appkit): reference agent-app, dev-playground chat UI, docs, and template #306

Demo

agent-demo.mp4

This was referenced Apr 21, 2026
@MarioCadenas MarioCadenas force-pushed the agent/v2/1-types-adapters branch from bb4efff to 5d060a6 Compare April 21, 2026 20:41
@MarioCadenas MarioCadenas force-pushed the agent/v2/1-types-adapters branch 3 times, most recently from 021cf0a to a4d0130 Compare April 22, 2026 16:19
@MarioCadenas MarioCadenas requested review from atilafassina, calvarjorge, ditadi and pkosiec and removed request for calvarjorge April 27, 2026 18:54
Comment thread packages/appkit/src/agents/databricks.ts
Comment thread packages/appkit/src/agents/langchain.ts Outdated
Comment thread packages/appkit/src/agents/databricks.ts Outdated
Comment thread packages/appkit/src/agents/langchain.ts Outdated
@MarioCadenas MarioCadenas force-pushed the agent/v2/1-types-adapters branch 6 times, most recently from 18b8bed to ee3a677 Compare May 4, 2026 09:41
@MarioCadenas MarioCadenas requested a review from a team as a code owner May 4, 2026 13:27
Comment thread packages/appkit/src/agents/databricks.ts
Comment thread packages/appkit/src/agents/databricks.ts
Comment thread packages/appkit/src/agents/databricks.ts
Foundation layer for the agents feature. Adds the portable type surface
that every downstream layer builds on, plus the Databricks Model Serving
adapter so the agents plugin (later PR) can target workspace-hosted
models.

`packages/shared/src/agent.ts` — no behavior, just the type vocabulary:
`AgentAdapter`, `AgentEvent`, `AgentInput`, `AgentRunContext`,
`AgentToolDefinition`, `Message`, `Thread`, `ThreadStore`,
`ToolAnnotations`, `ToolCall`, `ToolProvider`, `ResponseStreamEvent`.
Exported from the shared barrel.

`packages/appkit/src/agents/databricks.ts` — `DatabricksAdapter`:
streams OpenAI-compatible completions against a Databricks Model
Serving endpoint (raw fetch + SSE, no vendor SDKs). Also ships
`createDatabricksModel`, a Vercel-AI-SDK helper that returns a model
object you can pass to `streamText`/`useChat`/etc. — handles URL
rewriting (`/chat/completions` -> `/invocations`), per-request auth
refresh, and tool-name sanitization.

`@ai-sdk/openai` is a devDependency consumed by `createDatabricksModel`
via dynamic `import()`; consumers who use that helper install it
alongside `@databricks/appkit`.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
…E reader

- Bridge AbortSignal to SDK CancellationToken via Context on apiClient.request
- Pass signal from fromServingEndpoint streamBody into serving stream()
- Cancel SSE reader in streamCompletion finally for clean teardown

Tests: expect second request arg and Context when signal provided
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
- Forward Message.toolCalls/toolCallId to OpenAI tool_calls/tool_call_id
- Encode tool names with same wire map as run() (dots -> __)
- Use null assistant content when only tool_calls are present

Closes gap for resumed threads and hydrated conversation history.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
- Cap incomplete SSE tail, each complete line, assistant text, and per-index
  streamed tool arguments (UTF-16 code unit counts)
- Defaults: 1Mi line, 4Mi text, 2Mi tool args; overridable via adapter options
- Thread limits through fromServingEndpoint and fromModelServing

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
executeToolCalls now maps canonical tool names through nameToWire for
messages[].tool_calls while keeping dotted names for tool_call events
and executeTool.

Test: Llama-json text path asserts second POST uses analytics__query.
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
Matches the serving plugin env var name so deployments configure one variable.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
…it/beta

Remove ./agents/databricks package export; rely on beta entry and tsdown beta chunk.
Update JSDoc example import accordingly.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
Dots map to double underscores for serving; distinct names can share the same wire

string (e.g. foo.bar vs foo__bar). Throw instead of overwriting maps.

Add regression test before any HTTP call.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
…n paths

Shared parse / tool_call / execute / tool_result / message-append logic
between structured tool_calls handling and text-parse executeToolCalls().

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
- Yield status:error then rethrow when streamBody rejects
- AbortSignal.timeout(120s) for raw fetch when no runner signal
- Replace harmful Llama-array regex with indexOf/lastIndexOf slice
- Cap Python-style text parser input (64KiB); narrow SSE JSON with unknown guards
- console.debug malformed SSE JSON and reader teardown failures
- JSDoc: executeTool errors may reach the LLM

Includes regression tests.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
@MarioCadenas MarioCadenas force-pushed the agent/v2/1-types-adapters branch from 379c941 to 6dac357 Compare May 5, 2026 10:04
@MarioCadenas MarioCadenas enabled auto-merge (squash) May 5, 2026 10:17
@MarioCadenas MarioCadenas merged commit b5b695d into main May 5, 2026
9 checks passed
@MarioCadenas MarioCadenas deleted the agent/v2/1-types-adapters branch May 5, 2026 10:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants