@kernl-sdk/ai 0.2.10 → 0.3.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/ai@0.2.9 build /Users/andjones/Documents/projects/kernl/packages/providers/ai
+> @kernl-sdk/ai@0.2.10 build /Users/andjones/Documents/projects/kernl/packages/providers/ai
 > tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @kernl/ai
 
+## 0.3.0
+
+### Minor Changes
+
+- 3fe8682: Add native structured output support for agents
+
+  **kernl**
+  - Add `output` field to Agent config (Zod schema for structured responses)
+  - Rename type params: `TResponse` → `TOutput`, `AgentResponseType` → `AgentOutputType`
+  - Wire `agent.output` through Thread to protocol's `responseType`
+
+  **@kernl-sdk/ai**
+  - Add `RESPONSE_FORMAT` codec for AI SDK's `responseFormat` parameter
+  - Add structured output integration tests for OpenAI, Anthropic, and Google
+
 ## 0.2.10
 
 ### Patch Changes

package/dist/__tests__/integration.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import { openai } from "@ai-sdk/openai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { google } from "@ai-sdk/google";
 import { IN_PROGRESS } from "@kernl-sdk/protocol";
 import { AISDKLanguageModel } from "../language-model.js";
 /**
@@ -9,11 +10,26 @@ import { AISDKLanguageModel } from "../language-model.js";
  * These tests require API keys to be set:
  * - OPENAI_API_KEY for OpenAI tests
  * - ANTHROPIC_API_KEY for Anthropic tests
+ * - GOOGLE_GENERATIVE_AI_API_KEY for Google tests
  *
- * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key pnpm test:run
+ * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key GOOGLE_GENERATIVE_AI_API_KEY=your-key pnpm test:run
  */
 const SKIP_OPENAI_TESTS = !process.env.OPENAI_API_KEY;
 const SKIP_ANTHROPIC_TESTS = !process.env.ANTHROPIC_API_KEY;
+const SKIP_GOOGLE_TESTS = !process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+/**
+ * Shared JSON schema for structured output tests.
+ * Extracts a person's name and age from text.
+ */
+const PERSON_SCHEMA = {
+    type: "object",
+    properties: {
+        name: { type: "string", description: "The person's name" },
+        age: { type: "number", description: "The person's age in years" },
+    },
+    required: ["name", "age"],
+    additionalProperties: false,
+};
 describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
     let gpt41;
     beforeAll(() => {
@@ -645,6 +661,94 @@ describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
             })).rejects.toThrow(/max_output_tokens/);
         });
     });
+    describe("structured output", () => {
+        it("should generate structured JSON output with responseType", async () => {
+            const response = await gpt41.generate({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: John Smith is 42 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            });
+            expect(response.content).toBeDefined();
+            expect(response.content.length).toBeGreaterThan(0);
+            // Find the assistant message with JSON output
+            const messages = response.content.filter((item) => item.kind === "message" && item.role === "assistant");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("John Smith");
+            expect(parsed.age).toBe(42);
+        });
+        it("should stream structured JSON output with responseType", async () => {
+            const events = [];
+            for await (const event of gpt41.stream({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: Alice Wong is 28 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            })) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have text-delta events for streaming JSON
+            const textDeltas = events.filter((e) => e.kind === "text-delta");
+            expect(textDeltas.length).toBeGreaterThan(0);
+            // Should have a complete message with the JSON
+            const messages = events.filter((e) => e.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("Alice Wong");
+            expect(parsed.age).toBe(28);
+            // Should have finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+        });
+    });
 });
 describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
     let claude;
@@ -773,4 +877,241 @@ describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
             expect(finishEvents.length).toBe(1);
         });
     });
+    describe("structured output", () => {
+        it("should generate structured JSON output with responseType", async () => {
+            const response = await claude.generate({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: Maria Garcia is 35 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            });
+            expect(response.content).toBeDefined();
+            expect(response.content.length).toBeGreaterThan(0);
+            // Find the assistant message with JSON output
+            const messages = response.content.filter((item) => item.kind === "message" && item.role === "assistant");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("Maria Garcia");
+            expect(parsed.age).toBe(35);
+        });
+        it("should stream structured JSON output with responseType", async () => {
+            const events = [];
+            for await (const event of claude.stream({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: David Chen is 55 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            })) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have text-delta events for streaming JSON
+            const textDeltas = events.filter((e) => e.kind === "text-delta");
+            expect(textDeltas.length).toBeGreaterThan(0);
+            // Should have a complete message with the JSON
+            const messages = events.filter((e) => e.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("David Chen");
+            expect(parsed.age).toBe(55);
+            // Should have finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+        });
+    });
+});
+describe.skipIf(SKIP_GOOGLE_TESTS)("AISDKLanguageModel - Google", () => {
+    let gemini;
+    beforeAll(() => {
+        gemini = new AISDKLanguageModel(google("gemini-2.0-flash"));
+    });
+    describe("generate", () => {
+        it("should generate a simple text response", async () => {
+            const response = await gemini.generate({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            { kind: "text", text: "Say 'Hello, World!' and nothing else." },
+                        ],
+                    },
+                ],
+                settings: {
+                    maxTokens: 50,
+                    temperature: 0,
+                },
+            });
+            expect(response.content).toBeDefined();
+            expect(response.content.length).toBeGreaterThan(0);
+            expect(response.usage).toBeDefined();
+            expect(response.usage.totalTokens).toBeGreaterThan(0);
+            const messages = response.content.filter((item) => item.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+        });
+    });
+    describe("stream", () => {
+        it("should stream text responses", async () => {
+            const events = [];
+            for await (const event of gemini.stream({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [{ kind: "text", text: "Count to 5" }],
+                    },
+                ],
+                settings: {
+                    maxTokens: 50,
+                    temperature: 0,
+                },
+            })) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have at least one finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+            // Should have usage information
+            const finishEvent = finishEvents[0];
+            expect(finishEvent.usage).toBeDefined();
+            expect(finishEvent.usage.totalTokens).toBeGreaterThan(0);
+        });
+    });
+    describe("structured output", () => {
+        it("should generate structured JSON output with responseType", async () => {
+            const response = await gemini.generate({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: Kenji Tanaka is 29 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            });
+            expect(response.content).toBeDefined();
+            expect(response.content.length).toBeGreaterThan(0);
+            // Find the assistant message with JSON output
+            const messages = response.content.filter((item) => item.kind === "message" && item.role === "assistant");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("Kenji Tanaka");
+            expect(parsed.age).toBe(29);
+        });
+        it("should stream structured JSON output with responseType", async () => {
+            const events = [];
+            for await (const event of gemini.stream({
+                input: [
+                    {
+                        kind: "message",
+                        role: "user",
+                        id: "msg-1",
+                        content: [
+                            {
+                                kind: "text",
+                                text: "Extract the person info: Sarah Johnson is 41 years old.",
+                            },
+                        ],
+                    },
+                ],
+                responseType: {
+                    kind: "json",
+                    schema: PERSON_SCHEMA,
+                    name: "person",
+                    description: "A person with name and age",
+                },
+                settings: {
+                    maxTokens: 100,
+                    temperature: 0,
+                },
+            })) {
+                events.push(event);
+            }
+            expect(events.length).toBeGreaterThan(0);
+            // Should have text-delta events for streaming JSON
+            const textDeltas = events.filter((e) => e.kind === "text-delta");
+            expect(textDeltas.length).toBeGreaterThan(0);
+            // Should have a complete message with the JSON
+            const messages = events.filter((e) => e.kind === "message");
+            expect(messages.length).toBeGreaterThan(0);
+            const msg = messages[0];
+            const textContent = msg.content.find((c) => c.kind === "text");
+            expect(textContent).toBeDefined();
+            // Parse and validate the JSON output
+            const parsed = JSON.parse(textContent.text);
+            expect(parsed.name).toBe("Sarah Johnson");
+            expect(parsed.age).toBe(41);
+            // Should have finish event
+            const finishEvents = events.filter((e) => e.kind === "finish");
+            expect(finishEvents.length).toBe(1);
+        });
+    });
 });

package/dist/convert/response.d.ts

@@ -1,6 +1,6 @@
 import type { Codec } from "@kernl-sdk/shared/lib";
-import { type LanguageModelResponse, type LanguageModelWarning } from "@kernl-sdk/protocol";
-import type { LanguageModelV3Content, LanguageModelV3FinishReason, LanguageModelV3Usage, LanguageModelV3CallWarning } from "@ai-sdk/provider";
+import { type LanguageModelResponse, type LanguageModelResponseType, type LanguageModelWarning } from "@kernl-sdk/protocol";
+import type { LanguageModelV3Content, LanguageModelV3FinishReason, LanguageModelV3Usage, LanguageModelV3CallWarning, JSONSchema7 } from "@ai-sdk/provider";
 /**
  * AI SDK generate result structure
  */
@@ -13,4 +13,22 @@ export interface AISdkGenerateResult {
 }
 export declare const MODEL_RESPONSE: Codec<LanguageModelResponse, AISdkGenerateResult>;
 export declare const WARNING: Codec<LanguageModelWarning, LanguageModelV3CallWarning>;
+/**
+ * AI SDK response format type.
+ *
+ * Maps to the `responseFormat` parameter in AI SDK's doGenerate/doStream.
+ */
+export interface AISdkResponseFormat {
+    type: "json";
+    schema?: JSONSchema7;
+    name?: string;
+    description?: string;
+}
+/**
+ * Codec for converting protocol responseType to AI SDK responseFormat.
+ *
+ * - `kind: "text"` or undefined → undefined (AI SDK defaults to text)
+ * - `kind: "json"` → `{ type: "json", schema, name, description }`
+ */
+export declare const RESPONSE_FORMAT: Codec<LanguageModelResponseType | undefined, AISdkResponseFormat | undefined>;
 //# sourceMappingURL=response.d.ts.map

package/dist/convert/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/convert/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAIL,KAAK,qBAAqB,EAI1B,KAAK,oBAAoB,EAE1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC3B,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACvC,YAAY,EAAE,2BAA2B,CAAC;IAC1C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,EAAE,KAAK,CAAC,0BAA0B,CAAC,CAAC;CAC7C;AAED,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,qBAAqB,EAAE,mBAAmB,CAiG1E,CAAC;AAmBJ,eAAO,MAAM,OAAO,EAAE,KAAK,CAAC,oBAAoB,EAAE,0BAA0B,CA0BzE,CAAC"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/convert/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAIL,KAAK,qBAAqB,EAE1B,KAAK,yBAAyB,EAG9B,KAAK,oBAAoB,EAE1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACvC,YAAY,EAAE,2BAA2B,CAAC;IAC1C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,EAAE,KAAK,CAAC,0BAA0B,CAAC,CAAC;CAC7C;AAED,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,qBAAqB,EAAE,mBAAmB,CAiG1E,CAAC;AAmBJ,eAAO,MAAM,OAAO,EAAE,KAAK,CAAC,oBAAoB,EAAE,0BAA0B,CA0BzE,CAAC;AAEJ;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CACjC,yBAAyB,GAAG,SAAS,EACrC,mBAAmB,GAAG,SAAS,CAiBhC,CAAC"}

package/dist/convert/response.js

@@ -123,3 +123,25 @@ export const WARNING = {
         }
     },
 };
+/**
+ * Codec for converting protocol responseType to AI SDK responseFormat.
+ *
+ * - `kind: "text"` or undefined → undefined (AI SDK defaults to text)
+ * - `kind: "json"` → `{ type: "json", schema, name, description }`
+ */
+export const RESPONSE_FORMAT = {
+    encode: (responseType) => {
+        if (!responseType || responseType.kind === "text") {
+            return undefined;
+        }
+        return {
+            type: "json",
+            schema: responseType.schema,
+            name: responseType.name,
+            description: responseType.description,
+        };
+    },
+    decode: () => {
+        throw new Error("codec:unimplemented");
+    },
+};

package/dist/language-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"language-model.d.ts","sourceRoot":"","sources":["../src/language-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAS7B;;GAEG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IAK1C,OAAO,CAAC,KAAK;IAJzB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEL,KAAK,EAAE,eAAe;IAK1C;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAejC;;OAEG;IACI,MAAM,CACX,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC;CAgF3C"}
+{"version":3,"file":"language-model.d.ts","sourceRoot":"","sources":["../src/language-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAS7B;;GAEG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IAK1C,OAAO,CAAC,KAAK;IAJzB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEL,KAAK,EAAE,eAAe;IAK1C;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAiBjC;;OAEG;IACI,MAAM,CACX,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC;CAkF3C"}

package/dist/language-model.js

@@ -2,7 +2,7 @@ import { message, reasoning } from "@kernl-sdk/protocol";
 import { MESSAGE } from "./convert/message.js";
 import { TOOL } from "./convert/tools.js";
 import { MODEL_SETTINGS } from "./convert/settings.js";
-import { MODEL_RESPONSE } from "./convert/response.js";
+import { MODEL_RESPONSE, RESPONSE_FORMAT } from "./convert/response.js";
 import { convertStream } from "./convert/stream.js";
 /**
  * LanguageModel adapter for the AI SDK LanguageModelV3.
@@ -24,10 +24,12 @@ export class AISDKLanguageModel {
         const messages = request.input.map(MESSAGE.encode);
         const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
         const settings = MODEL_SETTINGS.encode(request.settings);
+        const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
         const result = await this.model.doGenerate({
             prompt: messages,
             tools,
             ...settings,
+            responseFormat,
             abortSignal: request.abort,
         });
         return MODEL_RESPONSE.decode(result);
@@ -39,10 +41,12 @@ export class AISDKLanguageModel {
         const messages = request.input.map(MESSAGE.encode);
         const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
         const settings = MODEL_SETTINGS.encode(request.settings);
+        const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
         const stream = await this.model.doStream({
             prompt: messages,
             tools,
             ...settings,
+            responseFormat,
             abortSignal: request.abort,
         });
         // text + reasoning buffers for delta accumulation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/ai",
-  "version": "0.2.10",
+  "version": "0.3.0",
   "description": "Vercel AI SDK adapter for kernl",
   "keywords": [
     "kernl",
@@ -69,8 +69,8 @@
   },
   "dependencies": {
     "@kernl-sdk/protocol": "0.2.8",
-    "@kernl-sdk/shared": "^0.3.0",
-    "@kernl-sdk/retrieval": "0.1.3"
+    "@kernl-sdk/retrieval": "0.1.3",
+    "@kernl-sdk/shared": "^0.3.0"
   },
   "scripts": {
     "build": "tsc && tsc-alias --resolve-full-paths",

package/src/__tests__/integration.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import { openai } from "@ai-sdk/openai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { google } from "@ai-sdk/google";
 import { IN_PROGRESS } from "@kernl-sdk/protocol";
 
 import { AISDKLanguageModel } from "../language-model";
@@ -11,12 +12,28 @@ import { AISDKLanguageModel } from "../language-model";
  * These tests require API keys to be set:
  * - OPENAI_API_KEY for OpenAI tests
  * - ANTHROPIC_API_KEY for Anthropic tests
+ * - GOOGLE_GENERATIVE_AI_API_KEY for Google tests
  *
- * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key pnpm test:run
+ * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key GOOGLE_GENERATIVE_AI_API_KEY=your-key pnpm test:run
  */
 
 const SKIP_OPENAI_TESTS = !process.env.OPENAI_API_KEY;
 const SKIP_ANTHROPIC_TESTS = !process.env.ANTHROPIC_API_KEY;
+const SKIP_GOOGLE_TESTS = !process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+
+/**
+ * Shared JSON schema for structured output tests.
+ * Extracts a person's name and age from text.
+ */
+const PERSON_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    name: { type: "string" as const, description: "The person's name" },
+    age: { type: "number" as const, description: "The person's age in years" },
+  },
+  required: ["name", "age"],
+  additionalProperties: false,
+};
 
 describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
   let gpt41: AISDKLanguageModel;
@@ -741,6 +758,109 @@ describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
       ).rejects.toThrow(/max_output_tokens/);
     });
   });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await gpt41.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: John Smith is 42 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("John Smith");
+      expect(parsed.age).toBe(42);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of gpt41.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Alice Wong is 28 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Alice Wong");
+      expect(parsed.age).toBe(28);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
 });
 
 describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
@@ -887,4 +1007,283 @@ describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
       expect(finishEvents.length).toBe(1);
     });
   });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await claude.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Maria Garcia is 35 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Maria Garcia");
+      expect(parsed.age).toBe(35);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of claude.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: David Chen is 55 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("David Chen");
+      expect(parsed.age).toBe(55);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
+});
+
+describe.skipIf(SKIP_GOOGLE_TESTS)("AISDKLanguageModel - Google", () => {
+  let gemini: AISDKLanguageModel;
+
+  beforeAll(() => {
+    gemini = new AISDKLanguageModel(google("gemini-2.5-flash-lite"));
+  });
+
+  describe("generate", () => {
+    it("should generate a simple text response", async () => {
+      const response = await gemini.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              { kind: "text", text: "Say 'Hello, World!' and nothing else." },
+            ],
+          },
+        ],
+        settings: {
+          maxTokens: 50,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+      expect(response.usage).toBeDefined();
+      expect(response.usage.totalTokens).toBeGreaterThan(0);
+
+      const messages = response.content.filter(
+        (item) => item.kind === "message",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("stream", () => {
+    it("should stream text responses", async () => {
+      const events = [];
+
+      for await (const event of gemini.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [{ kind: "text", text: "Count to 5" }],
+          },
+        ],
+        settings: {
+          maxTokens: 50,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have at least one finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+
+      // Should have usage information
+      const finishEvent = finishEvents[0] as any;
+      expect(finishEvent.usage).toBeDefined();
+      expect(finishEvent.usage.totalTokens).toBeGreaterThan(0);
+    });
+  });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await gemini.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Kenji Tanaka is 29 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Kenji Tanaka");
+      expect(parsed.age).toBe(29);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of gemini.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Sarah Johnson is 41 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Sarah Johnson");
+      expect(parsed.age).toBe(41);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
 });

package/src/convert/response.ts

@@ -5,6 +5,7 @@ import {
   FAILED,
   type LanguageModelResponse,
   type LanguageModelResponseItem,
+  type LanguageModelResponseType,
   type LanguageModelFinishReason,
   type LanguageModelUsage,
   type LanguageModelWarning,
@@ -16,6 +17,7 @@ import type {
   LanguageModelV3FinishReason,
   LanguageModelV3Usage,
   LanguageModelV3CallWarning,
+  JSONSchema7,
 } from "@ai-sdk/provider";
 
 /**
@@ -172,3 +174,42 @@ export const WARNING: Codec<LanguageModelWarning, LanguageModelV3CallWarning> =
       }
     },
   };
+
+/**
+ * AI SDK response format type.
+ *
+ * Maps to the `responseFormat` parameter in AI SDK's doGenerate/doStream.
+ */
+export interface AISdkResponseFormat {
+  type: "json";
+  schema?: JSONSchema7;
+  name?: string;
+  description?: string;
+}
+
+/**
+ * Codec for converting protocol responseType to AI SDK responseFormat.
+ *
+ * - `kind: "text"` or undefined → undefined (AI SDK defaults to text)
+ * - `kind: "json"` → `{ type: "json", schema, name, description }`
+ */
+export const RESPONSE_FORMAT: Codec<
+  LanguageModelResponseType | undefined,
+  AISdkResponseFormat | undefined
+> = {
+  encode: (responseType) => {
+    if (!responseType || responseType.kind === "text") {
+      return undefined;
+    }
+
+    return {
+      type: "json",
+      schema: responseType.schema,
+      name: responseType.name,
+      description: responseType.description,
+    };
+  },
+  decode: () => {
+    throw new Error("codec:unimplemented");
+  },
+};

package/src/language-model.ts

@@ -11,7 +11,7 @@ import { message, reasoning } from "@kernl-sdk/protocol";
 import { MESSAGE } from "./convert/message";
 import { TOOL } from "./convert/tools";
 import { MODEL_SETTINGS } from "./convert/settings";
-import { MODEL_RESPONSE } from "./convert/response";
+import { MODEL_RESPONSE, RESPONSE_FORMAT } from "./convert/response";
 import { convertStream } from "./convert/stream";
 
 /**
@@ -36,11 +36,13 @@ export class AISDKLanguageModel implements LanguageModel {
     const messages = request.input.map(MESSAGE.encode);
     const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
     const settings = MODEL_SETTINGS.encode(request.settings);
+    const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
 
     const result = await this.model.doGenerate({
       prompt: messages,
       tools,
       ...settings,
+      responseFormat,
       abortSignal: request.abort,
     });
 
@@ -56,11 +58,13 @@ export class AISDKLanguageModel implements LanguageModel {
     const messages = request.input.map(MESSAGE.encode);
     const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
     const settings = MODEL_SETTINGS.encode(request.settings);
+    const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
 
     const stream = await this.model.doStream({
       prompt: messages,
       tools,
       ...settings,
+      responseFormat,
       abortSignal: request.abort,
     });