# @agent-tars/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](https://github.com/user-attachments/assets/4f75a67e-624b-4e0f-a986-927d7fbbc73d) 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://agent-tars.com/beta)! 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](https://github.com/bytedance/UI-TARS-desktop/issues/842). ## Overview `@agent-tars/core` is the core implementation of Agent TARS, built on top of the Tarko Agent framework. It provides a comprehensive multimodal AI agent with advanced browser automation, filesystem operations, and intelligent search capabilities. ### Core Features - πŸ–±οΈ **One-Click Out-of-the-box CLI** - Supports both **headful** [Web UI](https://agent-tars.com/guide/basic/web-ui.html) and **headless** [server](https://agent-tars.com/guide/advanced/server.html)) [execution](https://agent-tars.com/guide/basic/cli.html). - 🌐 **Hybrid Browser Agent** - Control browsers using [GUI Agent](https://agent-tars.com/guide/basic/browser.html#visual-grounding), [DOM](https://agent-tars.com/guide/basic/browser.html#dom), or a hybrid strategy. - πŸ”„ **Event Stream** - Protocol-driven Event Stream drives [Context Engineering](https://agent-tars.com/beta#context-engineering) and [Agent UI](https://agent-tars.com/blog/2025-06-25-introducing-agent-tars-beta.html#easy-to-build-applications). - 🧰 **MCP Integration** - The kernel is built on MCP and also supports mounting [MCP Servers](https://agent-tars.com/guide/basic/mcp.html) to connect to real-world tools. ### Quick Start ```bash # Luanch with `npx`. npx @agent-tars/cli@latest # Install globally, required Node.js >= 22 npm install @agent-tars/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](https://agent-tars.com/guide/get-started/quick-start.html) guide for detailed setup instructions. ## Quick Start ### Installation ```bash npm install @agent-tars/core ``` ### Running Agent TARS Agent TARS can be started in multiple ways: #### Option 1: Using @agent-tars/cli (Recommended) ```bash # Install globally npm install -g @agent-tars/cli # Run Agent TARS agent-tars # Or use directly via npx npx @agent-tars/cli ``` #### Option 2: Using @tarko/agent-cli ```bash # Install globally npm install -g @tarko/agent-cli # Run Agent TARS through tarko CLI tarko run agent-tars # Or use directly via npx npx @tarko/agent-cli run agent-tars ``` #### Option 3: Programmatic Usage ### Basic Usage ```typescript import { AgentTARS } from '@agent-tars/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 ### AgentTARSOptions ```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'; } ``` ### Browser Control Modes - **`dom`**: Direct DOM manipulation (fastest, most reliable) - **`visual-grounding`**: Vision-based interaction (most flexible) - **`hybrid`**: Combines both approaches (recommended) ## Advanced Usage ### Custom Instructions ```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 }); ``` ### Browser State Management ```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'}`); } ``` ### Workspace Operations ```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 ### Core Methods - `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 ### Events 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](https://github.com/user-attachments/assets/1b07e0a7-b5ea-4f06-90a1-234afe659568) - πŸ“„ [Blog Post](https://agent-tars.com/beta) - 🐦 [Release Announcement on Twitter](https://x.com/_ulivz/status/1938009759413899384) - 🐦 [Official Twitter](https://x.com/agent_tars) - πŸ’¬ [Discord Community](https://discord.gg/HnKcSBgTVx) - πŸ’¬ [飞书亀桁羀](https://applink.larkoffice.com/client/chat/chatter/add_by_link?link_token=deen76f4-ea3c-4964-93a3-78f126f39651) - πŸš€ [Quick Start](https://agent-tars.com/quick-start) - πŸ’» [CLI Documentation](https://agent-tars.com/guide/basic/cli.html) - πŸ–₯️ [Web UI Guide](https://agent-tars.com/guide/basic/web-ui.html) - πŸ“ [Workspace Documentation](https://agent-tars.com/guide/basic/workspace.html) - πŸ”Œ [MCP Documentation](https://agent-tars.com/guide/basic/mcp.html) ## 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](https://github.com/bytedance/UI-TARS-desktop/blob/main/multimodal/CHANGELOG.md) ## Contributing See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines. ## License Apache-2.0 - See [LICENSE](../../LICENSE) for details.