The lightweight foundation for building agents (TypeScript implementation)
\n \n
\n\n
\n \n
\n\nStirrup is a lightweight framework, or starting point template, for building agents in TypeScript/JavaScript. It differs from other agent frameworks by:\n\n- **Working with the model, not against it:** Stirrup gets out of the way and lets the model choose its own approach to completing tasks. Many frameworks impose rigid workflows that can degrade results.\n- **Best practices and tools built-in:** We analyzed the leading agents (Claude Code, Codex, and others) to understand and incorporate best practices relating to topics like context management and foundational tools (e.g., code execution).\n- **Fully customizable:** Use Stirrup as a package or as a starting template to build your own fully customized agents.\n\n> **Note:** This is the TypeScript implementation of the [Python Stirrup framework](https://github.com/ArtificialAnalysis/Stirrup).\n\n## Features\n\n- ๐ **Online search / web browsing:** Search and fetch web pages\n- ๐งช **Code execution:** Run code locally, in Docker, or in an E2B sandbox\n- ๐ **MCP client support:** Connect to MCP servers and use their tools/resources\n- ๐ **Document input and output:** Import files into context and produce file outputs\n- ๐งฉ **Skills system:** Extend agents with modular, domain-specific instruction packages\n- ๐ ๏ธ **Flexible tool execution:** A generic `Tool` interface allows easy tool definition and extension with Zod validation\n- ๐ค **Human-in-the-loop:** Includes a built-in user input tool that enables human feedback or clarification during agent execution\n- ๐ง **Context management:** Automatically summarizes conversation history when approaching context limits, with deduplication to prevent summary accumulation\n- ๐ **Flexible provider support:** Pre-built support for OpenAI-compatible APIs (Chat Completions + Responses API), Anthropic, and Vercel AI SDK\n- ๐ผ๏ธ **Multimodal support:** Process images, video, and audio with automatic format conversion\n- ๐ **Speed metrics:** Track output tokens per second (OTPS), generation time, and per-tool execution durations\n- ๐พ **Agent run cache:** Cache and resume interrupted agent runs from where they left off\n- โ **Output file validation:** Finish tool validates that reported output files actually exist before completing\n- โ **Type-safe:** Built from the ground up with TypeScript\n\n\n\n## Installation\n\n```bash\nnpm install @stirrup/stirrup\n# or\npnpm add @stirrup/stirrup\n# or\nyarn add @stirrup/stirrup\n```\n\n## Quick Start\n\n```typescript\nimport { Agent, DEFAULT_TOOLS, SIMPLE_FINISH_TOOL } from '@stirrup/stirrup';\nimport { ChatCompletionsClient } from '@stirrup/stirrup/clients/openai';\n\nasync function main() {\n // Create client using ChatCompletionsClient\n // Automatically uses OPENROUTER_API_KEY environment variable\n const client = new ChatCompletionsClient({\n baseURL: 'https://openrouter.ai/api/v1',\n model: 'anthropic/claude-4.5-sonnet',\n });\n\n // As no tools are provided, the agent will use the default tools, which consist of:\n // - Web tools (web search and web fetching, note web search requires BRAVE_API_KEY)\n // - Local code execution tool (to execute shell commands)\n const agent = new Agent({\n client, \n name: 'agent', \n maxTurns: 15,\n tools: DEFAULT_TOOLS,\n finishTool: SIMPLE_FINISH_TOOL,\n });\n\n // Run with session context - handles tool lifecycle, logging and file outputs\n // Structured logging is enabled by default\n await using session = agent.session({ outputDir: './output/getting_started_example' });\n \n const result = await session.run(\n `What is the population of Australia over the last 3 years? Search the web to find out and create a\n simple chart using python and matplotlib showing the current population per year.`\n );\n\n console.log(\"Result:\", result.finishParams);\n}\n\nmain().catch(console.error);\n```\n\n> **Note:** This example uses OpenRouter. Set `OPENROUTER_API_KEY` in your environment before running. Web search requires a `BRAVE_API_KEY`. The agent will still work without it, but web search will be unavailable.\n\n## Full Customization\n\nFor using Stirrup as a foundation for your own fully customized agent, you can clone and import Stirrup locally:\n\n```bash\n# Clone the repository\ngit clone https://github.com/ArtificialAnalysis/StirrupJS.git\ncd StirrupJS\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n```\n\n## How It Works\n\n- **`Agent`** - Configures and runs the agent loop until a finish tool is called or max turns reached\n- **`session()`** - Context manager that sets up tools, manages files, handles logging, and ensures cleanup\n- **`Tool`** - Define tools with Zod parameters for full type safety\n- **`ToolProvider`** - Manage tools that require lifecycle (connections, temp directories, etc.)\n- **`DEFAULT_TOOLS`** - Standard tools included by default: code execution and web tools\n\n## Using Other LLM Providers\n\nStirrup supports multiple providers out of the box.\n\n### OpenAI-Compatible APIs\n\n```typescript\nimport { ChatCompletionsClient } from '@stirrup/stirrup/clients/openai';\n\n// Create client using Deepseek's OpenAI-compatible endpoint\nconst client = new ChatCompletionsClient({\n baseURL: 'https://api.deepseek.com',\n model: 'deepseek-chat',\n apiKey: process.env.DEEPSEEK_API_KEY,\n});\n\nconst agent = new Agent({ client, name: 'deepseek_agent', ... });\n```\n\n### Anthropic\n\n```typescript\nimport { AnthropicClient } from '@stirrup/stirrup/clients/anthropic';\n\nconst client = new AnthropicClient({\n model: 'claude-sonnet-4-5',\n apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nconst agent = new Agent({ client, name: 'claude_agent', ... });\n```\n\n### OpenAI Responses API\n\nFor models that support the newer Responses API (e.g., o3, o4-mini):\n\n```typescript\nimport { OpenResponsesClient } from '@stirrup/stirrup/clients/open-responses';\n\nconst client = new OpenResponsesClient({\n model: 'o3-mini',\n reasoningEffort: 'medium',\n});\n\nconst agent = new Agent({ client, name: 'responses_agent', ... });\n```\n\n### Vercel AI SDK\n\nStirrup integrates seamlessly with the Vercel AI SDK, giving you access to any provider supported by their ecosystem.\n\n```typescript\nimport { VercelAIClient } from '@stirrup/stirrup/clients/vercel-ai';\nimport { anthropic } from '@ai-sdk/anthropic';\n\nconst client = new VercelAIClient({\n model: anthropic('claude-sonnet-4-5'),\n});\n\nconst agent = new Agent({ client, name: 'vercel_agent', ... });\n```\n\n## Default Tools\n\nWhen you use `DEFAULT_TOOLS`, you get:\n\n| Tool Provider | Tools Provided | Description |\n| ------------- | -------------- | ----------- |\n| `LocalCodeExecToolProvider` | `code_exec` | Execute shell commands in an isolated temp directory |\n| `WebToolProvider` | `web_fetch`, `web_search` | Fetch web pages and search (search requires `BRAVE_API_KEY`) |\n\n## Extending with Pre-Built Tools\n\n```typescript\nimport { Agent, DEFAULT_TOOLS, CALCULATOR_TOOL, SIMPLE_FINISH_TOOL } from '@stirrup/stirrup';\nimport { ChatCompletionsClient } from '@stirrup/stirrup/clients/openai';\n\n// Create client\nconst client = new ChatCompletionsClient({ ... });\n\n// Create agent with default tools + calculator tool\nconst agent = new Agent({\n client,\n name: 'web_calculator_agent',\n tools: [...DEFAULT_TOOLS, CALCULATOR_TOOL],\n finishTool: SIMPLE_FINISH_TOOL,\n});\n```\n\n## Defining Custom Tools\n\nStirrup uses Zod for type-safe tool definitions:\n\n```typescript\nimport { z } from 'zod';\nimport { Agent, Tool, ToolUseCountMetadata, DEFAULT_TOOLS } from '@stirrup/stirrup';\n\n// Define parameters schema\nconst GreetParamsSchema = z.object({\n name: z.string().describe('Name of the person to greet'),\n formal: z.boolean().default(false).describe('Use formal greeting'),\n});\n\n// Create the tool\nconst GreetTool: Tool = {\n name: 'greet',\n description: 'Greet someone by name',\n parameters: GreetParamsSchema,\n executor: async (params) => {\n const greeting = params.formal ? `Good day, ${params.name}.` : `Hey ${params.name}!`;\n \n return {\n content: greeting,\n metadata: new ToolUseCountMetadata(1),\n };\n },\n};\n\n// Add to agent\nconst agent = new Agent({\n client,\n name: 'greeting_agent',\n tools: [...DEFAULT_TOOLS, GreetTool],\n ...\n});\n```\n\n## Advanced Features\n\n### Structured Logging\n\nStirrup JS includes a powerful structured logging system powered by Pino. It's enabled by default when using `agent.session()`:\n\n```typescript\n// Defaults to pretty-printed debug logs\nawait using session = agent.session();\n\n// Customize logging\nawait using session = agent.session({\n loggerOptions: {\n level: 'info', // 'trace' | 'debug' | 'info' | 'warn' | 'error'\n pretty: false, // Set to false for JSON output (production)\n }\n});\n\n// Disable default logger\nawait using session = agent.session({ noLogger: true });\n```\n\n### Speed Metrics\n\nEvery agent run tracks performance metrics including output tokens per second (OTPS), generation time, and per-tool durations. These are available in the run result and displayed automatically by the structured logger:\n\n```typescript\nconst result = await session.run('Create a chart');\n\nconsole.log(result.speedStats);\n// {\n// modelSlug: 'claude-sonnet-4-5',\n// totalGenerationMs: 5200,\n// totalOutputTokens: 1200,\n// totalToolMs: 3100,\n// generationCount: 4,\n// toolBreakdown: { code_exec: 2800, web_fetch: 300 }\n// }\n```\n\n### Agent Run Cache\n\nWhen an agent run is interrupted (max turns reached, errors), the conversation state is automatically cached to `~/.cache/stirrup/`. Resume from where you left off:\n\n```typescript\n// First run - gets interrupted at max turns\nawait using session = agent.session({ outputDir: './output' });\nawait session.run('Complex multi-step task');\n\n// Resume from cache\nawait using session2 = agent.session({ outputDir: './output', resume: true });\nawait session2.run('Complex multi-step task'); // Picks up where it left off\n```\n\n### Message Alternation\n\nSome LLM providers require strict user/assistant message alternation. Enable automatic continuation prompts:\n\n```typescript\nconst agent = new Agent({\n client,\n name: 'strict-agent',\n blockSuccessiveAssistantMessages: true, // Inject \"Please continue\" when needed\n ...\n});\n```\n\n### Shared Execution Environment\n\nSub-agents can share the parent's code execution sandbox to avoid file transfer overhead:\n\n```typescript\nconst subAgent = new Agent({\n client,\n name: 'worker',\n shareParentExecEnv: true, // Reuse parent's sandbox\n ...\n});\n```\n\n### Event Monitoring\n\nMonitor agent progress in real-time with typed events:\n\n```typescript\nagent.on('turn:start', ({ turn, maxTurns }) => {\n console.log(`Turn ${turn}/${maxTurns}`);\n});\n\nagent.on('tool:start', ({ name }) => {\n console.log(`Executing ${name}...`);\n});\n```\n\n## Development\n\n```bash\n# Install\nnpm install\n\n# Build\nnpm run build\n\n# Run examples\nnpx tsx examples/getting-started.ts\n\n# Test\nnpm test\n\n# Type check\nnpm run typecheck\n\n# Run documentation\nuv run mkdocs serve\n```\n\n## License\n\nLicensed under the [MIT LICENSE](LICENSE).\n","readmeFilename":"README.md"}
![\"NPM](\"https://img.shields.io/npm/v/@stirrup%2Fstirrup\")
![\"License\"](\"https://img.shields.io/github/license/ArtificialAnalysis/Stirrup\")
![\"MkDocs\"](\"https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff\"){kind=icon}
\n