Skip to content

agentforcezone/agentforce-adk

BranchesTags

Repository files navigation

AgentForce ADK - The Agent Development Kit


AgentForce Logo



A powerful TypeScript Agentic Framework for building AiAgent Workflows


Installation • Quick Start • Features • Examples • API Reference • Tool Use • MCP Integration • License

or goto

The AgentForceZone Documentation Page



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:

# 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)

# 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)

# 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 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:

// 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

A Simple Server Example

Advanced Agent Example


And many more!

The Awesome ADK Example Repository


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:

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:

{
  "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:

MCP_CONFIG=custom-mcp.config.json

Using MCP with Agents

Basic MCP Usage

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

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.


API Reference

For detailed API documentation, visit the AgentForce ADK API Reference.


MVP Roadmap

  • Method chaining with fluent interface
  • Prompt management (system and user prompts)
  • Agent execution with real LLM calls
  • Multiple output formats (text, JSON, Yaml and markdown)
  • Server deployment capabilities
  • Comprehensive test coverage with mock data support
  • Ollama provider support (local models)
  • OpenRouter provider support (cloud models with multiple providers)
  • Function calling and tool integration
  • Content filter tool and improved file save formats
  • HTML, JSON, Markdown, and YAML output utilities with tools
  • Configurable asset path for agent skills
  • Template support with withTemplate method
  • NPM Publishing
  • JSR support for Bun and Deno
  • AgentForceServer base class
  • Docker support for local server deployment
  • RouteAgent functionality
  • Enhanced logging with Custom logger
  • saveToFile method for AgentForceAgent
  • Ollama ToolUse functionality
  • OpenAI compatible route handling
  • Schema validation for addRouteAgent method
  • Jest Test Runner integration
  • Enhanced server and workflow functions
  • Improved documentation and examples
  • JSR support for Bun and Deno
  • Browser automation tool with browser_use functionality
  • Comprehensive JSDoc examples and type documentation
  • Improved tool organization and directory structure
  • 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)
  • BMAD-METHOD integration
  • CodingAgent functionality (claude-cli, gemini-cli and qwen3-coder-cli integration)
  • 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

License

This project is licensed under the AgentForceZone License - see the LICENSE file for details.

Built with ❤️ by the AgentForceZone Team

About

The Agent Development Kit - A agentic typescript library

docs.agentforce.zone

Topics

typescript ai aiagent aiworkflow

Resources

Readme

License

View license
Activity
Custom properties

Stars

2 stars

Watchers

2 watching

Forks

0 forks
Report repository

Languages