Open History to see the last commit
Tool Registry API - Quick Start#
In 3 Steps#
1. Define Tools in Constructor#
const ai = new AI({
adapters: {
openai: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
},
tools: {
// ← Define all tools here!
get_weather: {
type: "function" as const,
function: {
name: "get_weather",
description: "Get weather for a location",
parameters: {
type: "object",
properties: {
location: { type: "string" },
},
required: ["location"],
},
},
execute: async (args: { location: string }) => {
return JSON.stringify({ temp: 72, condition: "sunny" });
},
},
calculate: {
type: "function" as const,
function: {
name: "calculate",
description: "Perform calculations",
parameters: {
type: "object",
properties: {
expression: { type: "string" },
},
required: ["expression"],
},
},
execute: async (args: { expression: string }) => {
return JSON.stringify({ result: eval(args.expression) });
},
},
},
});
2. Reference Tools by Name (Type-Safe!)#
const result = await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [{ role: "user", content: "What's the weather in SF?" }],
tools: ["get_weather"], // ← Type-safe! Autocomplete works!
toolChoice: "auto",
});
3. Use Multiple Tools#
const result = await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [{ role: "user", content: "Weather in NYC and calculate 5*20" }],
tools: ["get_weather", "calculate"], // ← Both tools!
toolChoice: "auto",
});
Type Safety#
✅ Autocomplete - IDE suggests available tool names ✅ Validation - TypeScript catches typos at compile time ✅ Runtime checks - Errors if tool doesn't exist
// ✅ Valid
tools: ["get_weather", "calculate"]
// ❌ TypeScript Error
tools: ["invalid_tool"]
Benefits vs Old API#
Before (Inline Tools)#
// Had to define tools every time!
ai.chat({
messages: [...],
tools: [
{ type: "function", function: { name: "get_weather", ... }, execute: ... },
{ type: "function", function: { name: "calculate", ... }, execute: ... },
],
});
After (Tool Registry)#
// Define once in constructor, use by name everywhere!
ai.chat({
messages: [...],
tools: ["get_weather", "calculate"], // ← Much cleaner!
});
With Streaming#
const stream = ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather", "calculate"],
toolChoice: "auto",
as: "stream" as const,
});
for await (const chunk of stream) {
if (chunk.type === "tool_call") {
console.log(`Calling: ${chunk.toolCall.function.name}`);
}
}
With HTTP Response#
// Perfect for API endpoints!
return ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather", "search_products", "send_email"],
toolChoice: "auto",
as: "response" as const,
});
Pro Tips#
- Use
as constwhen defining tools for type safety - Descriptive names like
get_weather,search_products - Keep tools in one place for easy maintenance
- List available tools:
ai.toolNames - Get a tool:
ai.getTool("get_weather")
Common Pattern: Separate File#
// tools.ts
export const tools = {
get_weather: { /* ... */ },
calculate: { /* ... */ },
search_products: { /* ... */ },
} as const;
// ai-client.ts
import { tools } from "./tools";
export const ai = new AI({
adapters: { /* ... */ },
tools, // ← Import from separate file!
});
// api.ts
import { ai } from "./ai-client";
ai.chat({
messages: [...],
tools: ["get_weather"], // ← Type-safe across files!
});
Summary#
Define once, use everywhere with full type safety! 🎉
See full documentation: docs/TOOL_REGISTRY.md