@~lyre/ai-agents 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -91,6 +91,31 @@ type RunParams = {
     temperature?: number;
     /** Max number of tool-call iterations before bailing. Default 8. */
     maxSteps?: number;
+    /**
+     * Optional schema-constrained final output. When set, the run uses tools AND forces the model's
+     * FINAL answer to be a JSON object matching this schema (AI SDK `Output.object`) — i.e. call tools,
+     * read their results, then produce a validated object. The validated object is surfaced on the
+     * `finish` stream event as `object` (and on `RunResult.object`). Generating the object counts as a
+     * step, so keep `maxSteps` high enough for tool calls + the object step. Omit for free-text runs.
+     */
+    output?: {
+        schema: z.ZodSchema<any>;
+        name?: string;
+        description?: string;
+    };
+    /**
+     * Tool-selection policy for the FIRST step (AI SDK / OpenAI `tool_choice`):
+     * - `'auto'` (default): the model decides whether to call a tool.
+     * - `'required'`: the model MUST call a tool before it can answer — use this to force a data
+     *   round-trip so the model can't fabricate an answer (e.g. a canvas with placeholder values).
+     * - `'none'`: the model must not call tools.
+     * - `{ toolName }`: force a specific tool.
+     * Only the first step is constrained; later steps fall back to `auto` so the model can stop calling
+     * tools and produce its final (optionally schema-constrained) answer.
+     */
+    toolChoice?: 'auto' | 'required' | 'none' | {
+        toolName: string;
+    };
     /** Forwarded to tool `execute(input, context)`. */
     context?: Record<string, any>;
 };
@@ -112,6 +137,8 @@ type RunResult = {
         toolName: string;
         output: unknown;
     }[];
+    /** The schema-validated final object, present only when the run was given `output`. */
+    object?: unknown;
     raw: any;
 };
 type StreamEvent = {
@@ -140,6 +167,8 @@ type StreamEvent = {
         outputTokens: number;
         totalTokens: number;
     };
+    /** The schema-validated final object, present only when the run was given `output`. */
+    object?: unknown;
 } | {
     type: 'error';
     error: unknown;

package/dist/index.js

@@ -111,6 +111,21 @@ function buildTools(registry, agent, context) {
   }
   return out;
 }
+function buildRunOptions(params) {
+  const opts = {};
+  if (params.output) {
+    opts.output = Output.object({
+      schema: params.output.schema,
+      name: params.output.name,
+      description: params.output.description
+    });
+  }
+  if (params.toolChoice && params.toolChoice !== "auto") {
+    opts.toolChoice = params.toolChoice;
+    opts.prepareStep = ({ stepNumber }) => stepNumber === 0 ? { toolChoice: params.toolChoice } : { toolChoice: "auto" };
+  }
+  return opts;
+}
 async function run(registry, params, defaults) {
   const agent = registry.resolveAgent(params.agent);
   const messages = buildMessages(agent, params);
@@ -119,6 +134,7 @@ async function run(registry, params, defaults) {
     model: resolveModel(agent, defaults),
     messages,
     tools,
+    ...buildRunOptions(params),
     temperature: params.temperature ?? agent.temperature,
     maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
     stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
@@ -142,6 +158,7 @@ async function run(registry, params, defaults) {
       toolName: r.toolName,
       output: r.output
     })),
+    ...params.output ? { object: result.experimental_output } : {},
     raw: result
   };
 }
@@ -153,6 +170,7 @@ async function* runStream(registry, params, defaults) {
     model: resolveModel(agent, defaults),
     messages,
     tools,
+    ...buildRunOptions(params),
     temperature: params.temperature ?? agent.temperature,
     maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
     stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
@@ -199,6 +217,10 @@ async function* runStream(registry, params, defaults) {
         break;
       case "finish": {
         const finalUsage = part.totalUsage ?? part.usage;
+        let object;
+        if (params.output) {
+          object = await result.experimental_output;
+        }
         yield {
           type: "finish",
           finishReason: part.finishReason,
@@ -206,7 +228,8 @@ async function* runStream(registry, params, defaults) {
             inputTokens: finalUsage?.inputTokens ?? accumulatedUsage.inputTokens,
             outputTokens: finalUsage?.outputTokens ?? accumulatedUsage.outputTokens,
             totalTokens: finalUsage?.totalTokens ?? accumulatedUsage.totalTokens
-          }
+          },
+          ...params.output ? { object } : {}
         };
         break;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@~lyre/ai-agents",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Multi-provider AI agents SDK for SvelteKit + Node. Thin agent/tool/run/runStream surface over the Vercel AI SDK — OpenAI, Anthropic, Google Gemini, Mistral, Cohere. Zod-typed tools, full streaming event surface, optional HTML sanitizer.",
   "type": "module",
   "sideEffects": false,