@wattdata/sdk

Agentic customer intelligence with one line of code.

Quick Start

npm install @wattdata/sdk

import { createWattClient } from "@wattdata/sdk";

const watt = createWattClient({
  wattApiKey: process.env.WATT_API_KEY,
  wattMcpUrl: process.env.WATT_MCP_URL,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await watt.prompt("Resolve the identity for [email protected]");
console.log(response);

Usage

prompt() — Simple text response

const response = await watt.prompt("Resolve the identity for [email protected]");

generate() — Full result with steps and usage

const result = await watt.generate({
  prompt: "Analyze my customers",
  file: "/data/customers.csv",
});

console.log(result.text);    // Final response
console.log(result.steps);   // Agent steps
console.log(result.usage);   // Token usage

stream() — Streaming text

const result = await watt.stream({
  prompt: "Find tech executives in San Francisco",
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Structured output

Pass output to generate(), stream(), or streamChat() to get typed structured responses. The agent still runs its full tool loop — structured output only constrains the final response.

import { createWattClient, Output, z } from "@wattdata/sdk";

// Object output
const result = await watt.generate({
  prompt: "Find the CEO of Acme Corp",
  output: Output.object({
    schema: z.object({ name: z.string(), title: z.string() }),
  }),
});
console.log(result.output); // { name: "John Doe", title: "CEO" }

// Array output with streaming
const stream = await watt.stream({
  prompt: "List tech companies in SF",
  output: Output.array({
    element: z.object({ name: z.string(), industry: z.string() }),
  }),
});
for await (const partial of stream.partialOutputStream) {
  console.log(partial); // progressively more complete array
}
const final = await stream.output; // fully typed array

Available output types: Output.object(), Output.array(), Output.choice(), Output.text(), Output.json()

streamChat() — Chat UI integration

Returns a streaming Response for web frameworks. Pass output to constrain the agent's final response to a typed schema — the structured JSON streams as the last assistant message:

export async function POST(req: Request) {
  const { messages } = await req.json();
  const watt = createWattClient({
    wattApiKey: process.env.WATT_API_KEY,
    wattMcpUrl: process.env.WATT_MCP_URL,
    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  });
  return watt.streamChat(messages, {
    output: Output.object({
      schema: z.object({ response: z.string(), summary: z.string() }),
    }),
  });
}

Options: sendReasoning, file, abortSignal, output

Custom tools

Pass tools to inject custom tools into the agent alongside MCP and SDK tools:

import { tool } from "ai";
import { z } from "zod";

const watt = createWattClient({
  wattApiKey: process.env.WATT_API_KEY,
  wattMcpUrl: process.env.WATT_MCP_URL,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  tools: {
    draft_slack_message: tool({
      description: "Draft a Slack message summarizing analysis findings",
      inputSchema: z.object({
        channel: z.string(),
        title: z.string().max(150),
        body: z.string(),
        highlights: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
      }),
      execute: async (input) => input,
    }),
  },
});

Custom tools are merged with MCP-discovered tools and built-in SDK tools. They're available in generate(), stream(), and streamChat().

Note: Custom tools take precedence over MCP and SDK tools with the same name. A warning is logged when a collision is detected. Avoid naming custom tools after built-in tools (e.g., upload_file, entity_resolve) unless you intend to override them.

File uploads

Pass file to upload and analyze local files:

const result = await watt.generate({
  prompt: "Analyze my customers",
  file: "/data/customers.csv",
});

API Reference

| Method | Returns | Description | |--------|---------|-------------| | prompt(text) | Promise<string> | Simple text response | | generate(opts) | Promise<GenerateTextResult> | Full result with steps and usage. Pass output for structured responses | | stream(opts) | Promise<StreamTextResult> | Streaming text. Pass output for structured responses | | streamChat(messages, opts?) | Promise<Response> | Streaming response for chat UIs. Pass output for structured responses | | close() | Promise<void> | Close MCP connection |

Configuration

createWattClient({
  wattApiKey: string;        // Watt API key
  wattMcpUrl: string;        // Watt MCP server URL
  anthropicApiKey: string;   // Anthropic API key
  systemPrompt?: string;     // Custom system prompt (optional)
  tools?: ToolSet;           // Custom tools merged into the agent (optional)
});

License

MIT