K-Agent Lite

A Rust implementation of a simple agent providing an AI assistant with dynamic Python tool integration capabilities.

Features

• Dynamic Python Tool Execution: Create and execute Python tools on-the-fly using uvx
• Automatic Dependency Management: Auto-detects imports and isolates dependencies via uvx --with
• Tool Management: Register, update, and call custom Python functions dynamically
• Rich Terminal Output: Markdown rendering with syntax-highlighted code blocks
• Environment Configuration: Support for .env files and automatic API key detection
• Multi-Provider LLM Integration: Supports OpenRouter, OpenAI, Anthropic, Gemini AI Studio, and custom OpenAI-compatible endpoints

Key Features

1. Dynamic Python Tool Execution:

   • Creates Python tools dynamically at runtime
   • Stores tool definitions in a registry
   • Executes Python code via uvx with automatic dependency isolation
   • Auto-detects import statements for dependency management
   • Supports full Python ecosystem without manual package installation

2. LLM Integration: Supports real API calls to:

   • OpenRouter: Use model names with openrouter/ prefix (e.g., openrouter/anthropic/claude-3.5-sonnet)
   • OpenAI: Use standard model names (e.g., gpt-4o, gpt-4-turbo, o1-preview)
   • Anthropic: Use model names with claude- prefix (e.g., claude-3-5-sonnet-20241022)
   • Gemini AI Studio: Use model names with gemini- prefix (e.g., gemini-2.0-flash, gemini-1.5-pro)
   • Custom Endpoints: Support for local LLMs and OpenAI-compatible APIs via BASE_CUSTOM_URL
   • Automatically detects provider based on model name prefix or custom configuration

3. Tool Lifecycle:

   • Create: Define Python functions with parameters
   • Register: Store in Rust-managed registry
   • Execute: Run via Python interpreter with JSON parameter passing
   • Update: Overwrite existing tools seamlessly

4. Hybrid Architecture:

   • Rust runtime for performance and safety
   • Python execution for flexibility and ecosystem access
   • Best of both worlds!

Setup

1. Install Rust: Ensure you have Rust installed (https://rustup.rs/)

2. Clone and Build:

   git clone <repository>
   cd k-agent-lite
   cargo build

3. Environment Configuration:

   cp .env.example .env
   # Edit .env with your API keys and model selection

   Example .env configuration:

   # For OpenRouter (supports multiple providers)
   LITELLM_MODEL=openrouter/anthropic/claude-3.5-sonnet
   OPENROUTER_API_KEY=your_openrouter_key_here
   
   # Or for OpenAI directly
   LITELLM_MODEL=gpt-4o
   OPENAI_API_KEY=your_openai_key_here
   
   # Or for Anthropic directly
   LITELLM_MODEL=claude-3-5-sonnet-20241022
   ANTHROPIC_API_KEY=your_anthropic_key_here
   
   # Or for Gemini AI Studio
   LITELLM_MODEL=gemini-2.0-flash
   GEMINI_API_KEY=your_gemini_key_here
   
   # Or for custom OpenAI-compatible endpoint
   BASE_CUSTOM_URL=http://localhost:8000/v1/chat/completions
   BASE_CUSTOM_MODEL=llama-3.1-8b
   CUSTOM_API_KEY=your_custom_key_here  # Optional

Usage

Interactive Mode

cargo run

Then enter your task when prompted.

CLI Mode

cargo run -- "your task here"

Verbose Mode

cargo run -- -v "your task here"
# or
cargo run -- --verbose

Verbose mode displays detailed information about tool calls, API requests, and execution steps.

Project Structure

src/
├── main.rs           # Main application code
Cargo.toml           # Dependencies and project metadata
Cargo.lock           # Dependency lock file
.env.example         # Environment variables template
README.md            # This file
README_RUST.md       # Additional documentation

Dependencies

• tokio: Async runtime for asynchronous operations
• serde/serde_json: JSON serialization/deserialization
• reqwest: HTTP client for LLM API calls
• colored: Terminal color output
• anyhow: Error handling and context
• dotenv: Environment variable loading from .env files
• clap: Command line argument parsing
• uuid: UUID generation for unique identifiers
• ureq: Synchronous HTTP client
• lazy_static: Global static variables
• termimad: Markdown rendering in terminal
• syntect: Syntax highlighting for code blocks

Extending the Rust Version

LLM Provider Support

The implementation automatically detects the LLM provider based on the model name:

• OpenRouter: Prefix with openrouter/ (e.g., openrouter/anthropic/claude-3.5-sonnet)

  • Requires OPENROUTER_API_KEY environment variable
  • Supports models from Anthropic, OpenAI, Google, Meta, and more
  • API endpoint: https://openrouter.ai/api/v1/chat/completions

• OpenAI: Use standard model names (e.g., gpt-4o, gpt-4-turbo, o1-preview)

  • Requires OPENAI_API_KEY environment variable
  • API endpoint: https://api.openai.com/v1/chat/completions

• Anthropic: Prefix with claude- (e.g., claude-3-5-sonnet-20241022)

  • Requires ANTHROPIC_API_KEY environment variable
  • API endpoint: https://api.anthropic.com/v1/messages

• Gemini AI Studio: Prefix with gemini- (e.g., gemini-2.0-flash, gemini-1.5-pro)

  • Requires GEMINI_API_KEY environment variable (get from https://aistudio.google.com/apikey)
  • API endpoint: https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
  • Uses OpenAI-compatible API format

• Custom OpenAI-compatible Endpoints: For local LLMs, vLLM, Ollama, etc.

  • Set BASE_CUSTOM_URL to your endpoint URL
  • Set BASE_CUSTOM_MODEL to your model name
  • Optionally set CUSTOM_API_KEY (defaults to OPENAI_API_KEY if not provided)
  • Example: Running a local vLLM server or Ollama with OpenAI compatibility

Adding Custom Providers

To add support for additional providers, modify the call_llm function in src/main.rs to add a new condition in the provider detection logic.

Adding New Tools

To add new built-in tools:

1. Add the tool to the get_available_tools() function
2. Add a new match arm in the call_tool() function
3. Implement the tool's functionality

Dynamic Tool Execution

For more advanced dynamic tool execution, consider:

• Using a scripting engine like rhai or rune
• Implementing a plugin system with dynamic library loading
• WebAssembly integration for sandboxed code execution

Limitations

1. Requires Python 3 and uvx installed on the system
2. Tool execution has overhead from process spawning
3. Limited Composio integration compared to Python version
4. No built-in web search capabilities (can be added as custom Python tools)
5. Maximum 50 iterations per task to prevent infinite loops

Feature Plan

K-Agent Lite is under active development. Below are the planned features and enhancements:

1. Advanced Dynamic Tools

Status: 🚧 In Planning

Enhance the current dynamic tool system with:

• Tool Versioning: Track tool versions and allow rollback to previous implementations
• Tool Composition: Combine multiple tools into complex workflows
• Tool Dependencies: Define dependencies between tools with automatic resolution
• Tool Validation: Runtime validation of tool inputs/outputs with JSON schema
• Tool Caching: Cache tool results for identical inputs to improve performance
• Tool Metrics: Track execution time, success rate, and resource usage per tool
• Async Tool Execution: Execute independent tools in parallel for better performance

Implementation Approach:

// Example: Enhanced tool registry with versioning
struct ToolRegistry {
    tools: HashMap<String, Vec<ToolVersion>>,
    metrics: HashMap<String, ToolMetrics>,
    cache: LRUCache<ToolCacheKey, ToolResult>,
}

2. MCP (Model Context Protocol) Integration

Status: In Planning

Integrate Model Context Protocol for standardized context sharing and tool interoperability:

• MCP Server Support: Connect to MCP servers to access external tools and resources
• MCP Client Implementation: Expose K-Agent tools as MCP-compatible endpoints
• Resource Management: Access files, APIs, and databases through MCP resource providers
• Prompt Templates: Share and reuse prompt templates across MCP-compatible systems
• Sampling Support: Leverage MCP's sampling capabilities for LLM interactions
• Transport Layers: Support stdio, HTTP/SSE, and WebSocket transports

Key Benefits:

• Standardized tool discovery and invocation
• Seamless integration with other MCP-compatible agents
• Access to growing ecosystem of MCP servers (filesystem, database, API integrations)
• Improved context management and resource sharing

Example Use Cases:

# Connect to MCP servers for enhanced capabilities
export MCP_SERVERS="filesystem,database,github"

# Access GitHub through MCP
cargo run -- "analyze recent commits in my repository"

# Query databases through MCP
cargo run -- "get sales data from the analytics database"

3. Skills System

Status: 🚧 In Planning

Implement a reusable skills system for common agent capabilities:

• Skill Modules: Pre-built, tested modules for common tasks

  • Web Skills: Web scraping, API interaction, form filling
  • Data Skills: CSV/JSON/XML parsing, data transformation, analysis
  • File Skills: File operations, archive handling, text processing
  • Research Skills: Web search, content summarization, fact extraction
  • Code Skills: Code generation, testing, refactoring, documentation

• Skill Discovery: Automatic detection and registration of available skills

• Skill Dependencies: Manage Python package dependencies per skill

• Skill Testing: Built-in test suites for skill validation

• Skill Marketplace: Share and discover community-contributed skills

Skill Structure:

# skills/web_scraper/skill.toml
[skill]
name = "web_scraper"
version = "1.0.0"
description = "Extract data from web pages"
author = "K-Agent Community"

[dependencies]
python = ["beautifulsoup4", "requests", "lxml"]

[tools]
scrape_page = { file = "scraper.py", function = "scrape_page" }
extract_links = { file = "scraper.py", function = "extract_links" }

Skill Categories:

1. Communication Skills: Email, Slack, Discord integrations
2. Development Skills: Git operations, CI/CD, deployment
3. Productivity Skills: Calendar, task management, note-taking
4. Analytics Skills: Data visualization, statistical analysis
5. Security Skills: Secret scanning, vulnerability detection

4. Additional Planned Features

Short Term (Next Release):

• ✅ UVX installation check and guidance
• 🚧 Configuration file support (YAML/TOML)
• 🚧 Structured logging with multiple levels
• 🚧 Better error handling with automatic retry logic
• 🚧 Token usage tracking and cost estimation

Medium Term:

• Plugin system for extensible tools
• WebAssembly sandbox for secure code execution
• Streaming responses for real-time output
• Memory persistence across sessions
• Context management and summarization

Long Term:

• Multi-agent coordination and collaboration
• Self-improvement through reinforcement learning
• Visual workflow editor for tool composition
• Browser-based UI for agent interaction
• Cloud deployment support (Docker, Kubernetes)

Contributing to Features

We welcome contributions! If you're interested in helping implement any of these features:

1. Check the Issues page for related discussions
2. Join the conversation about feature design
3. Submit PRs with incremental improvements
4. Share your use cases and requirements

Future Improvements

1. Plugin system for extensible tools
2. WebAssembly sandbox for dynamic code execution
3. Better error handling and recovery with retries
4. Configuration file support (YAML/TOML)
5. Structured logging system
6. Composio integration for external tool access
7. Streaming responses for real-time output
8. Token usage tracking and cost estimation

Reference

This is a Rust implementation inspired by Pippin-Lite, a minimalistic template for dynamic self-building AI agents. Pippin-Lite is a lighter-weight cousin of the Pippin framework, designed as an educational starting point for exploring autonomous agents.

License

This project is licensed under the MIT License. See the LICENSE file for details.

---