# AgentForce ADK - The Agent Development Kit
## We are in Beta!
This project is in early development and is not yet production-ready. It is intended for testing and experimentation only. Use at your own risk.
## Overview
AgentForce ADK is a TypeScript Agent library for creating, managing, and orchestrating AiAgent Workflows. Built with modern TypeScript practices, it provides a simple powerful interface to develop Agent-Based applications. The Agent Development Kit supports multiple AI providers and models, making it flexible for various use cases.
## Installation
AgentForce ADK is available on both npm and JSR registries:
```bash
# Install via npm
npm install @agentforce/adk
# Install via JSR (JavaScript Registry)
npx jsr add @agentforce/adk # For Node.js projects
bunx jsr add @agentforce/adk # For Bun projects
deno add jsr:@agentforce/adk # For Deno projects
# Install via Bun (from npm)
bun add @agentforce/adk
```
#### Installation Method Comparison:
| Method | Best For | Command | Benefits |
|--------|----------|---------|----------|
| **npm** | Node.js projects, existing npm workflows | `npm install @agentforce/adk` | Largest ecosystem, familiar tooling |
| **JSR** | TypeScript-first projects, Deno/Bun compatibility | `npx jsr add @agentforce/adk` (Node.js)
`bunx jsr add @agentforce/adk` (Bun)
`deno add @agentforce/adk` (Deno) | Native TypeScript support, better type checking |
| **Bun (npm)** | Fast development, modern JavaScript projects | `bun add @agentforce/adk` | Fastest package manager, built-in TypeScript support |
#### Runtime Compatibility:
- **Node.js**:
- npm: `npm install @agentforce/adk`
- JSR: `npx jsr add @agentforce/adk`
- **Deno**:
- JSR: `deno add jsr:@agentforce/adk` (recommended)
- **Bun**:
- npm: `bun add @agentforce/adk`
- JSR: `bunx jsr add @agentforce/adk`
- **Browsers**: Works with bundlers like Vite, Webpack, or Rollup using any installation method
### Provider Setup
#### Ollama (Recommended for local development)
```bash
# Install Ollama on macOS using Homebrew
brew install ollama
# Or install via curl
curl -fsSL https://ollama.ai/install.sh | sh
# Verify installation
ollama --version
# Start Ollama server
ollama serve
# Pull a model, e.g
ollama pull gemma3:12b
ollama pull phi4-mini-reasoning:latest
ollama pull magistral:latest
```
#### OpenRouter (Multiple Models via API)
```bash
# Set your OpenRouter API key
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
# Or add to .env file
echo "OPENROUTER_API_KEY=sk-or-v1-your-api-key-here" >> .env
```
Get your API key at [OpenRouter.ai](https://openrouter.ai/settings/keys) to access models from:
- OpenAI (GPT-5, gpt-oss-120b, gpt-4, gpt-3.5-turbo)
- Anthropic (Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.5)
- Google (Gemini 2.5 Pro, Gemini 2.5 Flash, Gemma 3)
- Meta (Llama 4, Llama 3)
- Free models (GLM 4.5 Air (free), Qwen3 Coder (free), Kimi K2 (free), etc.)
#### OpenAI, Anthropic, Google
Not yet implemented! Coming Soon
## Quick Start
Create your first agent in just a few lines of code:
```typescript
// Import main classes
import { AgentForceAgent } from "@agentforce/adk";
// Create and configure your agent
const agent = new AgentForceAgent({ name: "StoryTellerAgent" })
.useLLM("ollama", "gemma3:4b")
.systemPrompt("You are a creative story writer.")
.prompt("Write a short story about AI and humanity.");
// Run the agent and get the response in markdown format
const response = await agent.output("md");
console.log(response);
```
## Features
- **Simple API**: Create agents with minimal code
- **Method Chaining**: Fluent interface for configuring agents
- **Cross-Runtime Support**: Works seamlessly in Bun, Node.js, and Deno environments
- **Multiple AI Providers**: Support for Ollama (local), OpenRouter (cloud), with OpenAI/Anthropic/Google coming soon
- **Model Switching**: Easily switch between different models with `useLLM()`
- **Cloud & Local Models**: Use local Ollama models or cloud models via OpenRouter
- **Prompt Management**: Set system and user prompts with `.systemPrompt()` and `.prompt()`
- **Multiple Output Formats**: Support for text, JSON, and Markdown output formats
- **Type Safe**: Full TypeScript support with proper type definitions
- **Debug Support**: Built-in debugging capabilities
- **Test-Friendly**: Comprehensive test coverage and designed for testability
- **Server Mode**: Built-in server functionality for agent deployment with automatic runtime detection
- **OpenAI Compatibility**: Full OpenAI chat completions API compatibility for seamless integration
- **Browser Automation**: Advanced browser automation capabilities for complex web interactions
- **Enhanced Documentation**: Comprehensive JSDoc examples and type documentation for better developer experience
## Examples
[A Basic Agent Example](https://docs.agentforce.zone/adk/examples/basic/)
[A Simple Server Example](https://docs.agentforce.zone/adk/examples/server/)
[Advanced Agent Example](https://docs.agentforce.zone/adk/examples/advanced/)
And many more!
[The Awesome ADK Example Repository](https://github.com/agentforcezone/agentforce-adk-awesome)
## Tool Use
AgentForce ADK supports tool use for advanced agent capabilities. You can define tools that agents can call during execution, allowing for dynamic interactions and enhanced functionality.
### Available Tools
The AgentForce ADK includes the following built-in tools:
#### File System Tools
- **`fs_read_file`** - Read the contents of a specified file
- **`fs_write_file`** - Write content to a specified file
- **`fs_list_dir`** - List contents of a directory
- **`fs_move_file`** - Move or rename files
- **`fs_find_files`** - Find files matching specified patterns
- **`fs_find_dirs_and_files`** - Find both directories and files
- **`fs_search_content`** - Search for content within files
- **`fs_get_file_tree`** - Get a complete file tree structure
#### Web and API Tools
- **`web_fetch`** - Web scraping with JavaScript rendering using Puppeteer
- **`api_fetch`** - HTTP requests with security and resource limits
- **`filter_content`** - Filter and process content
- **`browser_use`** - Advanced browser automation for complex web interactions
#### Git and GitHub Tools
- **`gh_list_repos`** - List GitHub repositories
#### System Tools
- **`os_exec`** - Execute system commands
#### Utility Tools
- **`md_create_ascii_tree`** - Create ASCII tree representations in Markdown
### Using Tools
Tools can be used by agents during execution to perform various tasks. Here's a basic example:
```typescript
import { AgentForceAgent } from "@agentforce/adk";
// File management agent
const fileAgent = new AgentForceAgent({
name: "FileAgent",
tools: ["fs_read_file", "fs_write_file"]
})
.useLLM("ollama", "gpt-oss:20b")
.systemPrompt("You are a file management assistant.")
.prompt("Read the README.md file and create a summary");
const response = await fileAgent.run();
// Browser automation agent
const browserAgent = new AgentForceAgent({
name: "WebAutomationAgent",
tools: ["browser_use", "fs_write_file"]
})
.useLLM("openrouter", "openai/gpt-5-mini")
.systemPrompt("You are a web automation specialist.")
.prompt("Navigate to example.com and extract the main heading");
const webResponse = await browserAgent.run();
```
## MCP Integration
AgentForce ADK supports **Model Context Protocol (MCP)** servers, enabling agents to connect to external tools and services that implement the MCP standard. This provides powerful extensibility beyond the built-in tools.
### What is MCP?
MCP (Model Context Protocol) is a standardized protocol for connecting language models to external tools, resources, and data sources. It allows agents to interact with a growing ecosystem of MCP-compatible servers and services.
### Configuration
#### Global MCP Configuration
Create a `mcp.config.json` file in your project root:
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
}
}
}
```
#### Environment Variables
Set `MCP_CONFIG` environment variable to use a custom config file path:
```bash
MCP_CONFIG=custom-mcp.config.json
```
### Using MCP with Agents
#### Basic MCP Usage
```typescript
import { AgentForceAgent } from "@agentforce/adk";
const agent = new AgentForceAgent({
name: "MCPAgent",
mcps: ["filesystem", "github"] // MCP servers to connect to
})
.useLLM("openrouter", "z-ai/glm-4.5v")
.systemPrompt("You are an assistant with file system and GitHub access.")
.prompt("List files in /tmp and show my GitHub repositories");
const response = await agent.run();
```
#### Agent-Specific MCP Configuration
```typescript
const gitAgent = new AgentForceAgent({
name: "GitAgent",
mcps: ["github"],
mcpConfig: "git-specific-mcp.config.json" // Custom config for this agent
})
.useLLM("openrouter", "z-ai/glm-4.5v")
.prompt("Create a new GitHub repository for my project");
const response = await gitAgent.run();
```
### Features
- **Automatic Tool Integration** - MCP tools are automatically available to agents
- **Environment Variable Support** - Use `${VAR_NAME}` syntax in configurations
- **Agent-Specific Configs** - Each agent can have its own MCP configuration
- **Resource and Prompt Loading** - Access MCP resources and prompts
- **Error Handling** - Graceful handling of connection and execution errors
For detailed MCP implementation information, see the [MCP Implementation Guide](docs/MCP_IMPLEMENTATION.md).
## API Reference
For detailed API documentation, visit the [AgentForce ADK API Reference](https://docs.agentforce.zone/adk/).
## MVP Roadmap
- [x] Method chaining with fluent interface
- [x] Prompt management (system and user prompts)
- [x] Agent execution with real LLM calls
- [x] Multiple output formats (text, JSON, Yaml and markdown)
- [x] Server deployment capabilities
- [x] Comprehensive test coverage with mock data support
- [x] Ollama provider support (local models)
- [x] OpenRouter provider support (cloud models with multiple providers)
- [x] Function calling and tool integration
- [x] Content filter tool and improved file save formats
- [x] HTML, JSON, Markdown, and YAML output utilities with tools
- [x] Configurable asset path for agent skills
- [x] Template support with withTemplate method
- [x] NPM Publishing
- [x] JSR support for Bun and Deno
- [x] AgentForceServer base class
- [x] Docker support for local server deployment
- [x] RouteAgent functionality
- [x] Enhanced logging with Custom logger
- [x] saveToFile method for AgentForceAgent
- [x] Ollama ToolUse functionality
- [x] OpenAI compatible route handling
- [x] Schema validation for addRouteAgent method
- [x] Jest Test Runner integration
- [x] Enhanced server and workflow functions
- [x] Improved documentation and examples
- [x] JSR support for Bun and Deno
- [x] Browser automation tool with browser_use functionality
- [x] Comprehensive JSDoc examples and type documentation
- [x] Improved tool organization and directory structure
- [x] Enhanced MCP Client integration with automatic tool loading
## Coming soon - until 1.0.0
- [ ] Streaming responses
- [ ] Multi-agent workflows and communication
- [ ] Advanced error handling and retry mechanisms
- [ ] Performance monitoring and analytics
- [ ] Enhanced debugging tools
- [ ] Support for more AI providers
- [ ] Advanced model management (versioning, rollback)
- [ ] Improved documentation and examples
- [ ] MCP Server Integration and plugins
- [ ] AgentForceZone CLI for easy project setup
- [ ] AgentForceZone Marketplace for sharing agents and workflows
- [ ] License Change to Apache 2.0
- [ ] Enhanced security features
- [ ] Flow Integration - complex workflow management
- [ ] ...
## Changelog
Check the [CHANGELOG](CHANGELOG.md)
## License
This project is licensed under the AgentForceZone License - see the [LICENSE](LICENSE) file for details.
---
Built with ❤️ by the AgentForceZone Team
