@deepagents/agent 0.3.1 → 0.7.0

package/README.md

@@ -0,0 +1,257 @@
+# @deepagents/agent
+
+A framework for building multi-agent AI systems with TypeScript. Create agents that use tools, coordinate through handoffs, and work together to solve complex tasks.
+
+## Features
+
+- **Agent Composition** - Build modular agents with specific roles and capabilities
+- **Tool Integration** - Compatible with Vercel AI SDK tools
+- **Handoffs** - Agents can delegate to specialized agents automatically
+- **Structured Output** - Type-safe responses with Zod schemas
+- **Streaming** - Real-time streaming responses
+- **Context Sharing** - Type-safe state passed between agents
+
+## Installation
+
+```bash
+npm install @deepagents/agent
+```
+
+Requires Node.js LTS (20+) and a `zod` peer dependency.
+
+## Quick Start
+
+### Simple Agent
+
+```typescript
+import { agent, execute, user } from '@deepagents/agent';
+import { openai } from '@ai-sdk/openai';
+
+const assistant = agent({
+  name: 'assistant',
+  model: openai('gpt-4o'),
+  prompt: 'You are a helpful assistant.',
+});
+
+const stream = execute(assistant, 'Hello!', {});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Agent with Tools
+
+```typescript
+import { agent, execute } from '@deepagents/agent';
+import { openai } from '@ai-sdk/openai';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+const weatherTool = tool({
+  description: 'Get weather for a location',
+  parameters: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }) => {
+    return { temperature: 72, condition: 'sunny', location };
+  },
+});
+
+const weatherAgent = agent({
+  name: 'weather_agent',
+  model: openai('gpt-4o'),
+  prompt: 'You help users check the weather.',
+  tools: { weather: weatherTool },
+});
+
+const stream = execute(weatherAgent, 'What is the weather in Tokyo?', {});
+console.log(await stream.text);
+```
+
+### Multi-Agent with Handoffs
+
+```typescript
+import { agent, instructions, swarm } from '@deepagents/agent';
+import { openai } from '@ai-sdk/openai';
+
+const researcher = agent({
+  name: 'researcher',
+  model: openai('gpt-4o'),
+  prompt: 'You research topics and provide detailed information.',
+  handoffDescription: 'Handles research and fact-finding tasks',
+  tools: { /* research tools */ },
+});
+
+const writer = agent({
+  name: 'writer',
+  model: openai('gpt-4o'),
+  prompt: 'You write clear, engaging content based on research.',
+  handoffDescription: 'Handles writing and content creation',
+});
+
+const coordinator = agent({
+  name: 'coordinator',
+  model: openai('gpt-4o'),
+  prompt: instructions({
+    purpose: ['Coordinate research and writing tasks'],
+    routine: [
+      'Analyze the request',
+      'Use transfer_to_researcher for fact-finding',
+      'Use transfer_to_writer for content creation',
+    ],
+  }),
+  handoffs: [researcher, writer],
+});
+
+// Agents automatically transfer control via transfer_to_<agent_name> tools
+const stream = swarm(coordinator, 'Write a blog post about AI agents', {});
+```
+
+### Structured Output
+
+```typescript
+import { agent, generate } from '@deepagents/agent';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const analyzer = agent({
+  name: 'analyzer',
+  model: openai('gpt-4o'),
+  prompt: 'Analyze the sentiment of the given text.',
+  output: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    confidence: z.number(),
+    keywords: z.array(z.string()),
+  }),
+});
+
+const result = await generate(analyzer, 'I love this product!', {});
+console.log(result.experimental_output);
+// { sentiment: 'positive', confidence: 0.95, keywords: ['love', 'product'] }
+```
+
+### Context Variables
+
+Share state between agents and tools:
+
+```typescript
+import { agent, execute, toState } from '@deepagents/agent';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+interface AppContext {
+  userId: string;
+  preferences: Record<string, string>;
+}
+
+const preferenceTool = tool({
+  description: 'Save user preference',
+  parameters: z.object({
+    key: z.string(),
+    value: z.string(),
+  }),
+  execute: async ({ key, value }, options) => {
+    const ctx = toState<AppContext>(options);
+    ctx.preferences[key] = value;
+    return `Saved ${key}=${value}`;
+  },
+});
+
+const assistant = agent<unknown, AppContext>({
+  name: 'assistant',
+  model: openai('gpt-4o'),
+  prompt: (ctx) => `Help user ${ctx?.userId} manage their preferences.`,
+  tools: { savePreference: preferenceTool },
+});
+
+const context: AppContext = { userId: 'user123', preferences: {} };
+const stream = execute(assistant, 'Set my theme to dark', context);
+await stream.text;
+
+console.log(context.preferences); // { theme: 'dark' }
+```
+
+## API Reference
+
+### `agent(config)`
+
+Creates a new agent:
+
+```typescript
+agent<Output, ContextIn, ContextOut>({
+  name: string;                    // Agent identifier (required)
+  model: LanguageModel;            // AI SDK model (required)
+  prompt: string | string[] | ((ctx?) => string);  // Instructions
+  tools?: ToolSet;                 // Available tools
+  handoffs?: Agent[];              // Agents to delegate to
+  handoffDescription?: string;     // When to use this agent
+  output?: z.Schema<Output>;       // Structured output schema
+  temperature?: number;            // LLM temperature
+  toolChoice?: ToolChoice;         // 'auto' | 'none' | 'required'
+})
+```
+
+### `instructions({ purpose, routine })`
+
+Helper for structured prompts:
+
+```typescript
+instructions({
+  purpose: string | string[],  // Agent's role
+  routine: string[],           // Step-by-step workflow
+})
+
+// For swarm coordination
+instructions.swarm({ purpose, routine })
+```
+
+### Execution Functions
+
+```typescript
+// Streaming execution
+execute(agent, messages, context, config?)
+stream(agent, messages, context, config?)  // alias
+
+// Non-streaming execution
+generate(agent, messages, context, config?)
+
+// High-level UI streaming with handoff support
+swarm(agent, messages, context, abortSignal?)
+```
+
+### Utilities
+
+```typescript
+// Create user message
+user(message: string): UIMessage
+
+// Access context in tools
+toState<T>(options: ToolCallOptions): T
+
+// Extract structured output
+toOutput<T>(result): Promise<T>
+```
+
+## AI Model Providers
+
+Works with any model provider supported by the [Vercel AI SDK](https://sdk.vercel.ai/docs):
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { groq } from '@ai-sdk/groq';
+
+const agent1 = agent({ model: openai('gpt-4o'), /* ... */ });
+const agent2 = agent({ model: anthropic('claude-sonnet-4-20250514'), /* ... */ });
+const agent3 = agent({ model: google('gemini-1.5-pro'), /* ... */ });
+```
+
+## Documentation
+
+Full documentation available at [januarylabs.github.io/deepagents](https://januarylabs.github.io/deepagents/docs/agent).
+
+## Repository
+
+[github.com/JanuaryLabs/deepagents](https://github.com/JanuaryLabs/deepagents)

package/dist/index.js

@@ -406,6 +406,100 @@ function toOutput(result) {
 function toState(options) {
   return options.experimental_context;
 }
+function htmlElementChunking() {
+  const WORD_REGEX = /\S+\s+/m;
+  return (buffer) => {
+    if (buffer.startsWith("<")) {
+      if (/^<[a-z]/i.test(buffer)) {
+        if (/^<[a-z][a-z0-9-]*$/i.test(buffer)) {
+          return null;
+        }
+        const elementMatch = /^<([a-z][a-z0-9]*(?:-[a-z0-9]+)*)([\s/>])/i.exec(
+          buffer
+        );
+        if (elementMatch) {
+          const elementName = elementMatch[1];
+          const endIndex = findElementEnd(buffer, elementName);
+          if (endIndex === -1) {
+            return null;
+          }
+          return buffer.slice(0, endIndex);
+        }
+      }
+    }
+    const ltIndex = buffer.indexOf("<");
+    if (ltIndex > 0) {
+      const textBefore = buffer.slice(0, ltIndex);
+      const wordMatch2 = WORD_REGEX.exec(textBefore);
+      if (wordMatch2) {
+        return textBefore.slice(0, wordMatch2.index + wordMatch2[0].length);
+      }
+      return textBefore;
+    }
+    const wordMatch = WORD_REGEX.exec(buffer);
+    if (wordMatch) {
+      return buffer.slice(0, wordMatch.index + wordMatch[0].length);
+    }
+    return null;
+  };
+}
+function findElementEnd(buffer, elementName) {
+  const nameEndIndex = buffer.indexOf(elementName) + elementName.length;
+  let inQuote = null;
+  let escaped = false;
+  let openTagClosed = false;
+  let depth = 0;
+  for (let i = nameEndIndex; i < buffer.length; i++) {
+    const char = buffer[i];
+    const prevChar = i > 0 ? buffer[i - 1] : "";
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (inQuote) {
+      if (char === inQuote) {
+        inQuote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      inQuote = char;
+      continue;
+    }
+    if (!openTagClosed) {
+      if (char === ">" && prevChar === "/") {
+        return i + 1;
+      }
+      if (char === ">") {
+        openTagClosed = true;
+      }
+      continue;
+    }
+    const closingTagLength = elementName.length + 3;
+    const potentialClosingTag = buffer.slice(i, i + closingTagLength);
+    if (potentialClosingTag.toLowerCase() === `</${elementName.toLowerCase()}>`) {
+      if (depth === 0) {
+        return i + closingTagLength;
+      }
+      depth--;
+      i += closingTagLength - 1;
+      continue;
+    }
+    const openingTagLength = elementName.length + 1;
+    const potentialOpeningTag = buffer.slice(i, i + openingTagLength);
+    if (potentialOpeningTag.toLowerCase() === `<${elementName.toLowerCase()}`) {
+      const afterName = buffer[i + openingTagLength];
+      if (afterName === " " || afterName === ">" || afterName === "/" || afterName === "\n" || afterName === "	") {
+        depth++;
+      }
+    }
+  }
+  return -1;
+}
 
 // packages/agent/src/lib/swarm.ts
 import { groq } from "@ai-sdk/groq";
@@ -425,7 +519,7 @@ import chalk from "chalk";
 import dedent2 from "dedent";
 import { zodToJsonSchema } from "zod-to-json-schema";
 function generate(agent2, messages, contextVariables, config) {
-  const result = generateText({
+  return generateText({
     abortSignal: config?.abortSignal,
     providerOptions: agent2.providerOptions ?? config?.providerOptions,
     model: agent2.model,
@@ -433,7 +527,7 @@ function generate(agent2, messages, contextVariables, config) {
     messages: convertToModelMessages(
       Array.isArray(messages) ? messages : [user(messages)]
     ),
-    temperature: agent2.temperature,
+    experimental_repairToolCall: repairToolCall,
     stopWhen: stepCountIs(25),
     tools: agent2.toToolset(),
     activeTools: agent2.toolsNames,
@@ -454,7 +548,6 @@ function generate(agent2, messages, contextVariables, config) {
     //   (contextVariables as any).content = result.content;
     // },
   });
-  return Object.assign(result, { state: contextVariables });
 }
 function execute(agent2, messages, contextVariables, config) {
   const runId = generateId2();
@@ -466,9 +559,10 @@ function execute(agent2, messages, contextVariables, config) {
     messages: convertToModelMessages(
       Array.isArray(messages) ? messages : [user(messages)]
     ),
-    temperature: agent2.temperature,
     stopWhen: stepCountIs(25),
-    experimental_transform: smoothStream(),
+    experimental_transform: smoothStream({
+      chunking: htmlElementChunking()
+    }),
     tools: agent2.toToolset(),
     activeTools: agent2.toolsNames,
     experimental_context: contextVariables,
@@ -665,8 +759,8 @@ var Agent = class _Agent {
   handoffToolName;
   handoffTool;
   output;
-  temperature;
   providerOptions;
+  logging;
   constructor(config) {
     this.model = config.model;
     this.toolChoice = config.toolChoice || "auto";
@@ -674,9 +768,9 @@ var Agent = class _Agent {
     this.prepareHandoff = config.prepareHandoff;
     this.prepareEnd = config.prepareEnd;
     this.output = config.output;
-    this.temperature = config.temperature;
     this.internalName = snakecase(config.name);
     this.providerOptions = config.providerOptions;
+    this.logging = config.logging;
     this.handoff = {
       name: this.internalName,
       instructions: config.prompt,
@@ -781,7 +875,7 @@ ${output}
             experimental_output: this.output ? Output2.object({ schema: this.output }) : void 0,
             onStepFinish: (step) => {
               const toolCall = step.toolCalls.at(-1);
-              if (toolCall) {
+              if (toolCall && this.logging) {
                 console.log(
                   `Debug: ${chalk2.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
                 );
@@ -810,7 +904,10 @@ ${JSON.stringify(error)}
   toTool(props) {
     return { [this.handoffToolName]: this.asTool(props) };
   }
-  debug(prefix = "") {
+  debug() {
+    if (!this.logging) {
+      return;
+    }
     console.log(
       `Debug: ${chalk2.bgMagenta("Agent")}: ${chalk2.dim.black(this.handoff.name)}`
     );
@@ -850,7 +947,6 @@ ${JSON.stringify(error)}
       handoffDescription: agent2?.handoffDescription ?? this.handoff.handoffDescription,
       handoffs: [...this.handoffs],
       output: agent2?.output ?? this.output,
-      temperature: agent2?.temperature ?? this.temperature,
       providerOptions: agent2?.providerOptions ?? this.providerOptions
     });
   }
@@ -1916,11 +2012,30 @@ var lmstudio = createOpenAICompatible({
   supportsStructuredOutputs: true,
   includeUsage: true
 });
+var ollama = createOpenAICompatible({
+  name: "ollama",
+  baseURL: process.env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434/v1",
+  supportsStructuredOutputs: true
+});
 var glm = createOpenAICompatible({
   name: "z.ai",
   baseURL: "https://api.z.ai/api/paas/v4/",
   apiKey: process.env.ZAI_API_KEY
 });
+var cerebras = createOpenAICompatible({
+  name: "cerebras",
+  baseURL: "https://api.cerebras.ai/v1",
+  apiKey: process.env.CEREBRAS_API_KEY,
+  includeUsage: true,
+  supportsStructuredOutputs: true
+});
+var nebius = createOpenAICompatible({
+  name: "nebius",
+  baseURL: "https://api.tokenfactory.nebius.com/v1/",
+  apiKey: process.env.NEBIUS_API_KEY,
+  includeUsage: true,
+  supportsStructuredOutputs: true
+});
 async function embed(documents) {
   const dimensions = 1024;
   const { embeddings } = await embedMany({
@@ -1995,12 +2110,14 @@ export {
   STEM_STEP_BACK_EXAMPLES,
   SUPERVISOR_PROMPT_PREFIX,
   agent,
+  cerebras,
   confirm,
   embed,
   execute,
   finished,
   generate,
   glm,
+  htmlElementChunking,
   input,
   instructions,
   isTransferToolResult,
@@ -2016,6 +2133,8 @@ export {
   memoryTools,
   memoryWrite,
   messageToUiMessage,
+  nebius,
+  ollama,
   pipe,
   prepareAgent,
   prepareStep,