@push.rocks/smartagent

A lightweight agentic loop built on Vercel AI SDK v6 via @push.rocks/smartai. Register tools, get a model, call runAgent() — done. 🚀

Install

pnpm install @push.rocks/smartagent

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Overview

@push.rocks/smartagent wraps the AI SDK's streamText with stopWhen: stepCountIs(n) for parallel multi-step tool execution. No classes to instantiate, no lifecycle to manage — just one async function:

import { runAgent, tool, z } from '@push.rocks/smartagent';
import { getModel } from '@push.rocks/smartai';

const model = getModel({
  provider: 'anthropic',
  model: 'claude-sonnet-4-5-20250929',
  apiKey: process.env.ANTHROPIC_TOKEN,
});

const result = await runAgent({
  model,
  prompt: 'What is 7 + 35?',
  system: 'You are a helpful assistant. Use tools when asked.',
  tools: {
    calculator: tool({
      description: 'Perform arithmetic',
      inputSchema: z.object({
        operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
        a: z.number(),
        b: z.number(),
      }),
      execute: async ({ operation, a, b }) => {
        const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
        return String(ops[operation]);
      },
    }),
  },
  maxSteps: 10,
});

console.log(result.text);    // "7 + 35 = 42"
console.log(result.steps);   // number of agentic steps taken
console.log(result.usage);   // { promptTokens, completionTokens, totalTokens }

Architecture

┌─────────────────────────────────────────────────┐
│  runAgent({ model, prompt, tools, maxSteps })   │
│                                                 │
│  ┌────────────┐   ┌───────────┐   ┌───────────┐ │
│  │ Messages   │──▶│ streamText│──▶│  Tools    │ │
│  │ (history)  │◀──│ (AI SDK)  │◀──│ (ToolSet) │ │
│  └────────────┘   └───────────┘   └───────────┘ │
│                                                 │
│  stopWhen: stepCountIs(maxSteps)                │
│  + retry with backoff on 429/529/503            │
│  + context overflow detection & recovery        │
│  + tool call repair (case-insensitive matching) │
└─────────────────────────────────────────────────┘

Key features:

• 🔄 Multi-step agentic loop — the model calls tools, sees results, and continues reasoning until done
• ⚡ Parallel tool execution — multiple tool calls in a single step are executed concurrently
• 🔧 Auto-retry with backoff — handles 429/529/503 errors with header-aware retry delays
• 🩹 Tool call repair — case-insensitive name matching + invalid tool sink prevents crashes
• 📊 Token streaming — onToken and onToolCall callbacks for real-time progress
• 💥 Context overflow handling — detects overflow and invokes your onContextOverflow callback

Core API

runAgent(options): Promise<IAgentRunResult>

The single entry point. Options:

Option	Type	Default	Description
model	LanguageModelV3	required	Model from @push.rocks/smartai's getModel()
prompt	string	required	The user's task/question
system	string	undefined	System prompt
tools	ToolSet	{}	Tools the agent can call
maxSteps	number	20	Max agentic steps before stopping
messages	ModelMessage[]	[]	Conversation history (for multi-turn)
maxRetries	number	5	Max retries on rate-limit/server errors
onToken	(delta: string) => void	—	Streaming token callback
onToolCall	(name: string) => void	—	Called when a tool is invoked
onContextOverflow	(messages) => messages	—	Handle context overflow (e.g., compact messages)

IAgentRunResult

interface IAgentRunResult {
  text: string;              // Final response text
  finishReason: string;      // 'stop', 'tool-calls', 'length', etc.
  steps: number;             // Number of agentic steps taken
  messages: ModelMessage[];  // Full conversation for multi-turn
  usage: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
}

Defining Tools 🛠️

Tools use Vercel AI SDK's tool() helper with Zod schemas:

import { tool, z } from '@push.rocks/smartagent';

const myTool = tool({
  description: 'Describe what this tool does',
  inputSchema: z.object({
    param1: z.string().describe('What this parameter is for'),
    param2: z.number().optional(),
  }),
  execute: async ({ param1, param2 }) => {
    // Do work, return a string
    return `Result: ${param1}`;
  },
});

Pass tools as a flat object to runAgent():

await runAgent({
  model,
  prompt: 'Do the thing',
  tools: { myTool, anotherTool },
  maxSteps: 10,
});

ToolRegistry

A lightweight helper for collecting tools:

import { ToolRegistry, tool, z } from '@push.rocks/smartagent';

const registry = new ToolRegistry();

registry.register('random_number', tool({
  description: 'Generate a random integer between min and max',
  inputSchema: z.object({
    min: z.number(),
    max: z.number(),
  }),
  execute: async ({ min, max }) => {
    return String(Math.floor(Math.random() * (max - min + 1)) + min);
  },
}));

registry.register('is_even', tool({
  description: 'Check if a number is even',
  inputSchema: z.object({ number: z.number() }),
  execute: async ({ number: n }) => n % 2 === 0 ? 'Yes' : 'No',
}));

const result = await runAgent({
  model,
  prompt: 'Generate a random number and tell me if it is even',
  tools: registry.getTools(),
  maxSteps: 10,
});

Built-in Tool Factories 🧰

Import from the @push.rocks/smartagent/tools subpath:

import { filesystemTool, shellTool, httpTool, jsonTool } from '@push.rocks/smartagent/tools';

filesystemTool(options?)

Returns: read_file, write_file, list_directory, delete_file

const tools = filesystemTool({ rootDir: '/home/user/workspace' });

await runAgent({
  model,
  prompt: 'Create a file called hello.txt with "Hello World"',
  tools,
  maxSteps: 5,
});

Options:

• rootDir — restrict all file operations to this directory. Paths outside it throw Access denied.

shellTool(options?)

Returns: run_command

const tools = shellTool({ cwd: '/tmp', allowedCommands: ['ls', 'echo', 'cat'] });

await runAgent({
  model,
  prompt: 'List all files in /tmp',
  tools,
  maxSteps: 5,
});

Options:

• cwd — working directory for commands
• allowedCommands — whitelist of allowed commands (if set, others are rejected)

httpTool()

Returns: http_get, http_post

const tools = httpTool();

await runAgent({
  model,
  prompt: 'Fetch the data from https://api.example.com/status',
  tools,
  maxSteps: 5,
});

jsonTool()

Returns: json_validate, json_transform

const tools = jsonTool();

// Direct usage:
const result = await tools.json_validate.execute({
  jsonString: '{"name":"test","value":42}',
  requiredFields: ['name', 'value'],
});
// → "Valid JSON: object with 2 keys"

Streaming & Callbacks 🎥

Monitor the agent in real-time:

const result = await runAgent({
  model,
  prompt: 'Analyze this data...',
  tools,
  maxSteps: 10,

  // Token-by-token streaming
  onToken: (delta) => process.stdout.write(delta),

  // Tool call notifications
  onToolCall: (toolName) => console.log(`\n🔧 Calling: ${toolName}`),
});

Context Overflow Handling 💥

For long-running agents that might exceed the model's context window, use the compaction subpath:

import { runAgent } from '@push.rocks/smartagent';
import { compactMessages } from '@push.rocks/smartagent/compaction';

const result = await runAgent({
  model,
  prompt: 'Process all 500 files...',
  tools,
  maxSteps: 100,

  onContextOverflow: async (messages) => {
    // Summarize the conversation to free up context space
    return await compactMessages(model, messages);
  },
});

Output Truncation ✂️

Prevent large tool outputs from consuming too much context:

import { truncateOutput } from '@push.rocks/smartagent';

const { content, truncated, notice } = truncateOutput(hugeOutput, {
  maxLines: 2000,   // default
  maxBytes: 50_000, // default
});

The built-in tool factories use truncateOutput internally.

Multi-Turn Conversations 💬

Pass the returned messages back for multi-turn interactions:

// First turn
const turn1 = await runAgent({
  model,
  prompt: 'Create a project structure',
  tools,
  maxSteps: 10,
});

// Second turn — continues the conversation
const turn2 = await runAgent({
  model,
  prompt: 'Now add a README to the project',
  tools,
  maxSteps: 10,
  messages: turn1.messages, // pass history
});

Exports

Main (@push.rocks/smartagent)

Export	Type	Description
runAgent	function	Core agentic loop
ToolRegistry	class	Tool collection helper
truncateOutput	function	Output truncation utility
ContextOverflowError	class	Error type for context overflow
tool	function	Re-exported from @push.rocks/smartai
z	object	Re-exported Zod for schema definitions
stepCountIs	function	Re-exported from AI SDK
jsonSchema	function	Re-exported from @push.rocks/smartai

Tools (@push.rocks/smartagent/tools)

Export	Type	Description
filesystemTool	factory	File operations (read, write, list, delete)
shellTool	factory	Shell command execution
httpTool	factory	HTTP GET/POST requests
jsonTool	factory	JSON validation and transformation

Compaction (@push.rocks/smartagent/compaction)

Export	Type	Description
compactMessages	function	Summarize message history to free context

Dependencies

• @push.rocks/smartai — Provider registry, getModel(), re-exports tool/jsonSchema
• ai v6 — Vercel AI SDK (streamText, stepCountIs, ModelMessage)
• zod — Tool input schema definitions
• @push.rocks/smartfs — Filesystem tool implementation
• @push.rocks/smartshell — Shell tool implementation
• @push.rocks/smartrequest — HTTP tool implementation

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.