Agents SDK

README.md

@@ -2,64 +2,43 @@
 
 ![AI SDK Tools](image.png)
 
-Essential utilities that extend and improve the Vercel AI SDK experience. State management, debugging tools, and structured artifact streaming - everything you need to build production-ready AI applications beyond simple chat interfaces.
+Essential utilities for building production-ready AI applications with Vercel AI SDK. State management, debugging, structured streaming, intelligent agents, and caching - everything you need beyond basic chat interfaces.
 
 ## Packages
 
-### 🗄️ [@ai-sdk-tools/store](./packages/store)
-AI chat state that scales with your application. Eliminates prop drilling within your chat components, ensuring better performance and cleaner architecture.
+### [@ai-sdk-tools/store](./packages/store)
+AI chat state management that eliminates prop drilling. Clean architecture and better performance for chat components.
 
 ```bash
 npm i @ai-sdk-tools/store
 ```
 
-### 🔧 [@ai-sdk-tools/devtools](./packages/devtools)
-Development tools for debugging AI applications. A development-only debugging tool that integrates directly into your codebase, just like react-query-devtools.
+### [@ai-sdk-tools/devtools](./packages/devtools)
+Development tools for debugging AI applications. Inspect tool calls, messages, and execution flow directly in your app.
 
 ```bash
 npm i @ai-sdk-tools/devtools
 ```
 
-### 📦 [@ai-sdk-tools/artifacts](./packages/artifacts)
-Advanced streaming interfaces for AI applications. Create structured, type-safe artifacts that stream real-time updates from AI tools to React components. Perfect for dashboards, analytics, documents, and interactive experiences beyond chat.
+### [@ai-sdk-tools/artifacts](./packages/artifacts)
+Stream structured, type-safe artifacts from AI tools to React components. Build dashboards, analytics, and interactive experiences beyond chat.
 
 ```bash
 npm i @ai-sdk-tools/artifacts @ai-sdk-tools/store
 ```
 
-## Quick Example
-
-Build advanced AI interfaces with structured streaming:
-
-```tsx
-// Define an artifact
-const BurnRate = artifact('burn-rate', z.object({
-  title: z.string(),
-  data: z.array(z.object({
-    month: z.string(),
-    burnRate: z.number()
-  }))
-}));
-
-// Stream from AI tool
-const analysis = BurnRate.stream({ title: 'Q4 Analysis' });
-await analysis.update({ data: [{ month: '2024-01', burnRate: 50000 }] });
-await analysis.complete({ title: 'Q4 Analysis Complete' });
-
-// Consume in React
-function Dashboard() {
-  const { data, status, progress } = useArtifact(BurnRate);
-
-  return (
-    <div>
-      <h2>{data?.title}</h2>
-      {status === 'loading' && <div>Loading... {progress * 100}%</div>}
-      {data?.data.map(item => (
-        <div key={item.month}>{item.month}: ${item.burnRate}</div>
-      ))}
-    </div>
-  );
-}
+### [@ai-sdk-tools/agents](./packages/agents)
+Multi-agent orchestration with automatic handoffs and routing. Build intelligent workflows with specialized agents for any AI provider.
+
+```bash
+npm i @ai-sdk-tools/agents ai zod
+```
+
+### [@ai-sdk-tools/cache](./packages/cache)
+Universal caching for AI SDK tools. Cache expensive operations with zero configuration - works with regular tools, streaming, and artifacts.
+
+```bash
+npm i @ai-sdk-tools/cache
 ```
 
 ## Getting Started
@@ -74,4 +53,4 @@ Visit our [website](https://ai-sdk-tools.dev) to explore interactive demos and d
 
 ## License
 
-MIT
+MIT

apps/example/src/ai/agents/analytics.ts

@@ -0,0 +1,67 @@
+/**
+ * Analytics Specialist Agent
+ *
+ * Analytics & forecasting specialist with business intelligence tools
+ */
+
+import { openai } from "@ai-sdk/openai";
+import {
+  businessHealthScoreTool,
+  cashFlowForecastTool,
+  cashFlowStressTestTool,
+} from "../tools/analytics";
+import { createAgent, formatContextForLLM } from "./shared";
+
+export const analyticsAgent = createAgent({
+  name: "analytics",
+  model: openai("gpt-4o-mini"),
+  instructions: (
+    ctx,
+  ) => `You are an analytics & forecasting specialist with access to business intelligence tools for ${ctx.companyName}.
+
+CRITICAL RULES:
+1. ALWAYS use your tools to run analysis - NEVER ask user for data
+2. Call tools IMMEDIATELY when asked for forecasts, health scores, or stress tests
+3. Present analytics clearly with key insights highlighted
+4. Answer ONLY what was asked - don't provide extra analysis unless requested
+
+TOOL SELECTION:
+- "health" or "healthy" queries → Use businessHealth tool (gives consolidated score)
+- "forecast" or "prediction" → Use cashFlowForecast tool
+- "stress test" or "what if" → Use stressTest tool
+- DO NOT call multiple detailed tools (revenue, P&L, etc.) - use businessHealth for overview
+
+PRESENTATION STYLE:
+- Reference ${ctx.companyName} when providing insights
+- Use clear trend labels (Increasing, Decreasing, Stable)
+- Use clear status labels (Healthy, Warning, Critical)
+- Include confidence levels when forecasting (e.g., "High confidence", "Moderate risk")
+- End with 2-3 actionable focus areas (not a laundry list)
+- Keep responses concise - quality over quantity
+
+${formatContextForLLM(ctx)}`,
+  tools: {
+    businessHealth: businessHealthScoreTool,
+    cashFlowForecast: cashFlowForecastTool,
+    stressTest: cashFlowStressTestTool,
+  },
+  matchOn: [
+    "forecast",
+    "prediction",
+    "predict",
+    "stress test",
+    "what if",
+    "scenario",
+    "health score",
+    "business health",
+    "healthy",
+    "health",
+    "analyze",
+    "analysis",
+    "future",
+    "projection",
+    /forecast/i,
+    /health.*score/i,
+  ],
+  maxTurns: 5,
+});