@tars-agent/core

Agent TARS is a general multimodal AI Agent stack, it brings the power of GUI Agent and Vision into your terminal, computer, browser and product.

!image

It primarily ships with a CLI and Web UI for usage. It aims to provide a workflow that is closer to human-like task completion through cutting-edge multimodal LLMs and seamless integration with various real-world MCP tools.

📣 Just released: Agent TARS Beta - check out our announcement blog post!

https://github.com/user-attachments/assets/772b0eef-aef7-4ab9-8cb0-9611820539d8

Booking Hotel	Generate Chart with extra MCP Servers
Instruction: I am in Los Angeles from September 1st to September 6th, with a budget of $5,000. Please help me book a Ritz-Carlton hotel closest to the airport on booking.com and compile a transportation guide for me	Instruction: Draw me a chart of Hangzhou's weather for one month

For more use cases, please check out #842.

Overview

@tars-agent/core is the core implementation of Agent TARS, built on top of the tarco Agent framework. It provides a comprehensive multimodal AI agent with advanced browser automation, filesystem operations, and intelligent search capabilities.

$3

- 🖱️ One-Click Out-of-the-box CLI - Supports both headful Web UI and headless server) execution.
- 🌐 Hybrid Browser Agent - Control browsers using GUI Agent, DOM, or a hybrid strategy.
- 🔄 Event Stream - Protocol-driven Event Stream drives Context Engineering and Agent UI.
- 🧰 MCP Integration - The kernel is built on MCP and also supports mounting MCP Servers to connect to real-world tools.

$3

``bash


Luanch with npx.

npx @tars-agent/cli@latest

Install globally, required Node.js >= 22

npm install @tars-agent/cli@latest -g

Run with your preferred model provider

agent-tars --provider volcengine --model doubao-1-5-thinking-vision-pro-250428 --apiKey your-api-key
agent-tars --provider anthropic --model claude-3-7-sonnet-latest --apiKey your-api-key
`

Visit the comprehensive Quick Start guide for detailed setup instructions.

Quick Start

$3

`bash
npm install @tars-agent/core
`

$3

Agent TARS can be started in multiple ways:

#### Option 1: Using @tars-agent/cli (Recommended)

`bash


Install globally

npm install -g @tars-agent/cli

Run Agent TARS

agent-tars

Or use directly via npx

npx @tars-agent/cli
`

#### Option 2: Using @tarco/agent-cli

`bash


Install globally

npm install -g @tarco/agent-cli

Run Agent TARS through tarco CLI

tarco run agent-tars

Or use directly via npx

npx @tarco/agent-cli run agent-tars
`

#### Option 3: Programmatic Usage

$3

`typescript
import { AgentTARS } from '@tars-agent/core';

// Create an agent instance
const agent = new AgentTARS({
model: {
provider: 'openai',
model: 'gpt-4',
apiKey: process.env.OPENAI_API_KEY,
},
workspace: './workspace',
browser: {
headless: false,
control: 'hybrid',
},
});

// Initialize and run
await agent.initialize();
const result = await agent.run('Search for the latest AI research papers');
console.log(result);
`

Configuration

$3

`typescript
interface AgentTARSOptions {
// Model configuration
model?: {
provider: 'openai' | 'anthropic' | 'doubao';
model: string;
apiKey: string;
};

// Browser settings
browser?: {
headless?: boolean;
control?: 'dom' | 'visual-grounding' | 'hybrid';
cdpEndpoint?: string;
};

// Search configuration
search?: {
provider: 'browser_search' | 'tavily';
count?: number;
apiKey?: string;
};

// Workspace settings
workspace?: string;

// MCP implementation
mcpImpl?: 'in-memory' | 'stdio';
}
`

$3

- dom: Direct DOM manipulation (fastest, most reliable)
- visual-grounding: Vision-based interaction (most flexible)
- hybrid: Combines both approaches (recommended)

Advanced Usage

$3

`typescript
const agent = new AgentTARS({
instructions:
You are a specialized research assistant.
Focus on academic papers and technical documentation.
Always provide citations and sources.
,
// ... other options
});
`

$3

`typescript
// Get browser control information
const browserInfo = agent.getBrowserControlInfo();
console.log(Mode: ${browserInfo.mode});
console.log(Tools: ${browserInfo.tools.join(', ')});

// Access browser manager
const browserManager = agent.getBrowserManager();
if (browserManager) {
const isAlive = await browserManager.isBrowserAlive();
console.log(Browser status: ${isAlive ? 'alive' : 'dead'});
}
`

$3

`typescript
// Get current workspace
const workspace = agent.getWorkingDirectory();
console.log(Working in: ${workspace});

// All file operations are automatically scoped to workspace
const result = await agent.run(
"Create a summary.md file with today's findings",
);
`

Error Handling

`typescript
try {
await agent.initialize();
const result = await agent.run('Your task here');
} catch (error) {
console.error('Agent error:', error);
} finally {
// Always cleanup
await agent.cleanup();
}
`

API Reference

$3

- initialize(): Initialize the agent and all components
- run(message): Execute a task with the given message
- cleanup(): Clean up all resources
- getWorkingDirectory(): Get current workspace path
- getBrowserControlInfo(): Get browser control status
- getBrowserManager(): Access browser manager instance

$3

The agent emits events through the event stream:

`typescript
agent.eventStream.subscribe((event) => {
if (event.type === 'tool_result') {
console.log(Tool ${event.name} completed);
}
});
``

Resources

!agent-tars-banner

- 📄 Blog Post
- 🐦 Release Announcement on Twitter
- 🐦 Official Twitter
- 💬 Discord Community
- 💬 飞书交流群
- 🚀 Quick Start
- 💻 CLI Documentation
- 🖥️ Web UI Guide
- 📁 Workspace Documentation
- 🔌 MCP Documentation

Features

- 🌐 Advanced Browser Control: Multiple control strategies (DOM, Visual, Hybrid)
- 📁 Safe Filesystem Operations: Workspace-scoped file management
- 🔍 Intelligent Search: Integration with multiple search providers
- 🔧 MCP Integration: Built-in Model Context Protocol support
- 📸 Visual Understanding: Screenshot-based browser interaction
- 🛡️ Safety First: Path validation and workspace isolation

What's Changed

See Full CHANGELOG

Contributing

See CONTRIBUTING.md for development guidelines.

License

Apache-2.0 - See LICENSE for details.