@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 | | providerOptions | ProviderOptions | undefined | Provider-specific AI SDK request options passed through to streamText() | | 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 | | onToolResult | (name: string, result: unknown) => void | — | Called when a tool finishes | | validateCompletion | (result) => string \| void | — | Return a string to reject and reprompt an incomplete run | | maxValidationRetries | number | 0 | Number of validation-triggered reprompts allowed | | 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: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
  };
  toolCalls: Array<{
    toolName: string;
    input: unknown;
    output?: unknown;
    error?: string;
  }>;
}

OpenAI Provider Options

Use providerOptions for provider-specific request settings such as GPT reasoning effort. SmartAgent forwards the object unchanged to AI SDK streamText().

import { getModelSetup } from '@push.rocks/smartai';
import { runAgent } from '@push.rocks/smartagent';

const setup = getModelSetup({
  provider: 'openai',
  model: 'gpt-5.5',
  apiKey: process.env.OPENAI_API_KEY,
  providerOptions: {
    openai: {
      reasoningEffort: 'xhigh',
    },
  },
});

const result = await runAgent({
  model: setup.model,
  system: 'You handle financial documents carefully.',
  prompt: 'Process this inbox document.',
  tools,
  maxSteps: 20,
  providerOptions: setup.providerOptions,
});

const saved = result.toolCalls.some((call) =>
  call.toolName === 'saveVoucher' || call.toolName === 'saveBankStatement',
);

Completion Validation

Use validateCompletion when a workflow must not finish unless a required side-effect happened. Return void to accept the run, or return a string to append that string as a new user message and continue. If retries are exhausted, runAgent() throws.

const result = await runAgent({
  model,
  prompt: 'Process this inbox document.',
  tools,
  maxSteps: 20,
  maxValidationRetries: 1,
  validateCompletion: (result) => {
    const saved = result.toolCalls.some((call) =>
      call.toolName === 'saveVoucher' || call.toolName === 'saveBankStatement',
    );

    if (!saved) {
      return 'You must call saveVoucher or saveBankStatement before finalizing.';
    }
  },
});

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 [email protected].

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.