openagent-ai

A lightweight, extensible AI Agent framework with tool calling, streaming, and multi-provider support.

30 Seconds Quick Start

import { anthropic } from 'openagent-ai'

const agent = anthropic('your-api-key')
const result = await agent.chat('Hello!')
console.log(result.text)

That's it! The agent can read/write files, execute commands, search code, and more.

Features

• Simple API: One-line initialization, easy chat() and stream() methods
• Built-in Tools: File operations, bash execution, web fetching out of the box
• Multi-Provider: Works with Anthropic, OpenAI, Google, and OpenAI-compatible APIs
• Extensible: Custom tools, custom agents, pluggable storage
• Streaming: Real-time streaming of responses and tool execution
• Agent Loop: Automatic multi-step tool execution

Installation

npm install openagent-ai

Usage Examples

Basic Chat

import { anthropic } from 'openagent-ai'

const agent = anthropic(process.env.ANTHROPIC_API_KEY)

// Simple chat
const result = await agent.chat('List files in current directory')
console.log(result.text)
console.log(result.toolCalls) // See what tools were used

Streaming

for await (const event of agent.stream('Create a hello.txt file')) {
  if (event.type === 'text') process.stdout.write(event.text)
  if (event.type === 'tool-start') console.log(`\nUsing: ${event.name}`)
  if (event.type === 'done') console.log(`\nCost: $${event.result.cost}`)
}

Use with OpenCode Config

If you have an opencode.json config file, you can load it directly:

import { OpenAgent, configureFromOpenCodeConfig } from 'openagent-ai'

// Load your opencode.json configuration
const config = require('./opencode.json')
configureFromOpenCodeConfig(config)

// Now use any configured provider
const agent = new OpenAgent({
  provider: 'anthropic',
  model: 'claude-opus-4.5',
})

const result = await agent.chat('Hello!')

Built-in Tools

| Tool | Description | |------|-------------| | read | Read file contents | | write | Create or overwrite files | | edit | Edit files with smart text matching | | bash | Execute shell commands | | glob | Find files by pattern | | grep | Search file contents with regex | | webfetch | Fetch web content | | question | Ask user for input | | task | Launch sub-agents for complex tasks | | todowrite | Manage task lists and track progress | | skill | Load specialized skills (git-expert, code-review, etc.) |

Provider Setup

Anthropic (Recommended)

import { anthropic } from 'openagent-ai'

// Direct API
const agent = anthropic('sk-ant-xxx')

// With proxy/custom endpoint
const agent = new OpenAgent({
  provider: 'anthropic',
  apiKey: 'your-key',
  baseURL: 'https://your-proxy.com/v1',  // optional
  model: 'claude-opus-4.5',
})

OpenAI

import { openai } from 'openagent-ai'
const agent = openai('sk-xxx', 'gpt-4o')

Google Gemini

import { google } from 'openagent-ai'
const agent = google('your-api-key', 'gemini-1.5-pro')

OpenAI-Compatible APIs (Together, Groq, DeepSeek, etc.)

import { OpenAgent } from 'openagent-ai'

// Together AI
const agent = new OpenAgent({
  provider: 'openai',
  apiKey: process.env.TOGETHER_API_KEY,
  baseURL: 'https://api.together.xyz/v1',
  model: 'meta-llama/Llama-3-70b-chat-hf',
})

// Groq
const agent = new OpenAgent({
  provider: 'openai',
  apiKey: process.env.GROQ_API_KEY,
  baseURL: 'https://api.groq.com/openai/v1',
  model: 'llama-3.1-70b-versatile',
})

// DeepSeek
const agent = new OpenAgent({
  provider: 'openai',
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: 'https://api.deepseek.com/v1',
  model: 'deepseek-chat',
})

// ZhipuAI (GLM)
const agent = new OpenAgent({
  provider: 'openai',
  apiKey: process.env.ZHIPU_API_KEY,
  baseURL: 'https://open.bigmodel.cn/api/paas/v4',
  model: 'glm-4',
})

// Local Ollama
const agent = new OpenAgent({
  provider: 'openai',
  apiKey: 'not-needed',
  baseURL: 'http://localhost:11434/v1',
  model: 'llama3',
})

Advanced Configuration

Full Options

const agent = new OpenAgent({
  // Provider settings
  provider: 'anthropic',           // 'anthropic' | 'openai' | 'google'
  apiKey: 'your-api-key',
  baseURL: 'https://custom.api/v1', // optional proxy
  model: 'claude-sonnet-4-20250514',
  headers: { 'X-Custom': 'value' }, // optional headers
  
  // Behavior settings
  mode: 'build',                   // 'plan' (read-only) | 'build' (full access)
  maxSteps: 10,                    // max tool execution rounds
  temperature: 0.7,
  maxOutputTokens: 4096,
  workingDirectory: '/path/to/dir',
  
  // Custom tools
  tools: [myCustomTool],
  useBuiltinTools: true,           // default: true
})

Custom Tools

import { OpenAgent, defineTool } from 'openagent-ai'
import { z } from 'zod'

const calculator = defineTool({
  id: 'calculator',
  description: 'Perform math calculations',
  parameters: z.object({
    expression: z.string().describe('Math expression like "2 + 2"'),
  }),
  execute: async (args) => ({
    title: 'Calculation',
    output: `Result: ${eval(args.expression)}`,
  }),
})

const agent = new OpenAgent({
  provider: 'anthropic',
  apiKey: 'your-key',
  tools: [calculator],
})

Custom System Prompt

const agent = new OpenAgent({
  provider: 'anthropic',
  apiKey: 'your-key',
  agent: {
    name: 'code-reviewer',
    systemPrompt: `You are an expert code reviewer.
Focus on: code quality, security, performance.`,
    allowedTools: ['read', 'grep', 'glob'],  // optional: restrict tools
  },
})

Session Management

// Chat returns sessionId for continuation
const result1 = await agent.chat('Read package.json')
console.log(result1.sessionId)

// Continue same conversation
const result2 = await agent.chat('What version?', { 
  sessionId: result1.sessionId 
})

// Or use fluent API
const result3 = await agent
  .continueSession(result1.sessionId)
  .chat('Summarize it')

// Start fresh session
const result4 = await agent.newSession().chat('New topic')

Sub-Agents with Task Tool

The task tool allows agents to spawn sub-agents for complex operations:

// The agent can use the task tool to delegate complex work
const result = await agent.chat(`
  I need you to:
  1. Find all TypeScript files with TODO comments
  2. Create a summary report
  
  Use the task tool to explore the codebase efficiently.
`)

// Available sub-agent types:
// - general: Multi-step tasks and research
// - explore: Fast codebase exploration

Skills System

Load specialized knowledge on-demand:

import { registerSkill, getAvailableSkills } from 'openagent-ai'

// Built-in skills: git-expert, code-review, typescript-expert, testing

// Agent can load skills during conversation
const result = await agent.chat('Load the git-expert skill and help me resolve merge conflicts')

// Register custom skills
registerSkill({
  name: 'my-skill',
  description: 'Custom domain knowledge',
  content: `# My Skill\n\nGuidelines for...`,
})

// List available skills
console.log(getAvailableSkills())

Task Management

Track complex tasks with the todowrite tool:

import { getTodos, setTodos, clearTodos } from 'openagent-ai'

// The agent automatically uses todowrite for complex tasks
const result = await agent.chat(`
  Implement user authentication:
  1. Create login endpoint
  2. Add session management
  3. Write tests
`)

// Programmatically access todos
const todos = getTodos(result.sessionId)
console.log(todos) // [{ id, content, status, priority }, ...]

Agent Modes

• build (default): Full access - can read, write, execute
• plan: Read-only - can only read files and search

// Start in plan mode
const agent = new OpenAgent({ mode: 'plan' })

// Switch to build mode when ready
agent.setMode('build')

Examples

See the examples/ directory:

# Basic usage
npx tsx examples/simple.ts

# Custom tools
npx tsx examples/advanced.ts

# Test different providers
npx tsx examples/test-providers.ts
npx tsx examples/test-providers.ts anthropic --tools

API Reference

ChatResult

interface ChatResult {
  text: string           // Final response text
  toolCalls: ToolCall[]  // Tools that were called
  usage: TokenUsage      // { input, output }
  cost: number           // Estimated cost in USD
  finishReason: string   // 'stop', 'tool_use', etc.
  sessionId: string      // For continuing conversation
}

StreamEvent

type StreamEvent =
  | { type: 'text'; text: string }
  | { type: 'tool-start'; name: string; input: object }
  | { type: 'tool-end'; name: string; output: string }
  | { type: 'done'; result: ChatResult }
  | { type: 'error'; error: Error }

Documentation

• Architecture - System design
• Roadmap - Future plans
• Contributing - How to contribute

License

MIT

Links

• GitHub
• npm