Client-Side Tools

import type { ToolSet } from '@deuz-sdk/core';
import { z } from 'zod';

const tools: ToolSet = {
  // server tool — the loop runs this and feeds the result back automatically
  getWeather: {
    description: 'Get the current weather for a city.',
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => ({ city, tempC: 22 }),
  },
  // client tool — no execute; the loop stops and returns the call to you
  confirmPurchase: {
    description: 'Ask the user to confirm a purchase before charging.',
    parameters: z.object({ sku: z.string(), amount: z.number() }),
  },
};

import { generateText } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';
import { z } from 'zod';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const result = await generateText({
  model: anthropic('claude-opus-4-8'),
  messages: [{ role: 'user', content: 'Buy SKU-42 for me.' }],
  maxSteps: 5,
  tools: {
    confirmPurchase: {
      description: 'Ask the user to confirm a purchase before charging.',
      parameters: z.object({ sku: z.string(), amount: z.number() }),
    },
  },
});

const pending = result.toolCalls ?? [];
for (const call of pending) {
  // { toolCallId, toolName, args }
  console.log(call.toolName, call.args);
}

// result.response.messages ends with the assistant turn (the tool_use),
// and there is NO tool turn yet — that's yours to add.

{ type: 'tool-call', toolCallId: string, toolName: string, input: unknown }

interface ToolResultPart {
  type: 'tool_result';
  toolUseId: string;   // === the pending call's toolCallId
  result: unknown;     // your answer (string or JSON-serializable)
  isError?: boolean;   // optional; set true to report a failure to the model
}

import { generateText } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';
import type { Message } from '@deuz-sdk/core';
import { z } from 'zod';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const tools = {
  confirmPurchase: {
    description: 'Ask the user to confirm a purchase before charging.',
    parameters: z.object({ sku: z.string(), amount: z.number() }),
  },
};

let messages: Message[] = [{ role: 'user', content: 'Buy SKU-42 for $30.' }];

// 1) First call — stops at the client tool.
const first = await generateText({
  model: anthropic('claude-opus-4-8'),
  messages,
  maxSteps: 5,
  tools,
});
messages = [...messages, ...first.response.messages]; // includes the assistant tool_use turn

// 2) Resolve the pending call however you like (here: a confirmation gate).
const toolResults = (first.toolCalls ?? []).map((call) => {
  const approved = userApproved(call.args); // your own logic
  return {
    type: 'tool_result' as const,
    toolUseId: call.toolCallId,
    result: approved ? { status: 'charged' } : { status: 'declined' },
  };
});

// 3) Append ONE tool message answering every pending call, then call again.
messages = [...messages, { role: 'tool', content: toolResults }];

const second = await generateText({
  model: anthropic('claude-opus-4-8'),
  messages,
  maxSteps: 5,
  tools,
});

console.log(second.text); // the model's reply now that it has the result

function userApproved(_args: unknown): boolean {
  return true;
}

const tools = {
  // Model proposes the action; humans approve before anything runs.
  proposeRefund: {
    description: 'Propose a refund for an order. A human must approve it.',
    parameters: z.object({ orderId: z.string(), amount: z.number() }),
  },
};

// After the loop stops with a pending proposeRefund call:
const call = (result.toolCalls ?? [])[0];
const decision = await askHuman(call?.args); // { approved, note, hard }

const toolResult = {
  type: 'tool_result' as const,
  toolUseId: call!.toolCallId,
  result: decision.approved
    ? await issueRefund(call!.args) // run the real side effect yourself
    : { denied: true, reason: decision.note },
  isError: !decision.approved && decision.hard,
};

const first = await generateText({ model, messages, tools, maxSteps: 5 });

if (first.pendingApprovals) {
  const verdicts = await askUser(first.pendingApprovals); // your UI
  const second = await generateText({
    model,
    messages: [...messages, ...first.response.messages],
    tools,
    maxSteps: 5,
    approvalResponses: verdicts.map((v) => ({
      approvalId: v.approvalId,
      approved: v.approved,
      reason: v.reason, // optional; denial reasons are fed back to the model
    })),
  });
}

import { streamChat } from '@deuz-sdk/core';
import { toDeuzStreamResponse } from '@deuz-sdk/core/ui';
import { createAnthropic } from '@deuz-sdk/core/anthropic';
import type { Message } from '@deuz-sdk/core';

export const runtime = 'edge';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

export async function POST(req: Request) {
  const { messages } = (await req.json()) as { messages: Message[] };

  const result = streamChat({
    model: anthropic('claude-opus-4-8'),
    messages,
    maxSteps: 5,
    tools: {
      // client tool: only the browser can read the user's location
      getUserLocation: {
        description: 'Get the user’s current coordinates (runs in the browser).',
        parameters: {
          type: 'object',
          properties: {},
          additionalProperties: false,
        },
      },
    },
  });

  return toDeuzStreamResponse(result);
}

import { readDeuzStream } from '@deuz-sdk/core/ui';
import type { Message, ToolResultPart } from '@deuz-sdk/core';

async function send(messages: Message[]): Promise<Message[]> {
  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ messages }),
  });

  let text = '';
  const pending: { toolCallId: string; input: unknown }[] = [];

  for await (const part of readDeuzStream(res)) {
    switch (part.type) {
      case 'text-delta':
        text += part.text;
        break;
      case 'tool-call':
        // a client tool was called — remember it; nothing runs server-side
        pending.push({ toolCallId: part.toolCallId, input: part.input });
        break;
      case 'error':
        throw new Error(part.message);
      default:
        break;
    }
  }

  // No pending client-tool call: the assistant produced a final answer.
  if (pending.length === 0) {
    return [...messages, { role: 'assistant', content: text }];
  }

  // Reconstruct the assistant tool_use turn the server already emitted...
  const assistant: Message = {
    role: 'assistant',
    content: pending.map((p) => ({
      type: 'tool_use' as const,
      id: p.toolCallId,
      name: 'getUserLocation',
      input: p.input,
    })),
  };

  // ...resolve each call in the browser...
  const toolParts: ToolResultPart[] = await Promise.all(
    pending.map(async (p) => ({
      type: 'tool_result' as const,
      toolUseId: p.toolCallId,
      result: await readGeolocation(),
    })),
  );

  // ...then re-POST history with the assistant turn + tool_result turn appended.
  const next: Message[] = [
    ...messages,
    assistant,
    { role: 'tool', content: toolParts },
  ];
  return send(next); // recurse until no client tool is pending
}

function readGeolocation(): Promise<{ lat: number; lon: number }> {
  return new Promise((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(
      (pos) => resolve({ lat: pos.coords.latitude, lon: pos.coords.longitude }),
      reject,
    );
  });
}