Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (73 loc) · 4.36 KB

AGENTS.md

File metadata and controls

91 lines (73 loc) · 4.36 KB
Raw

Kai Agent - Development Guide

Kai Agent is an autonomous AI research engineer for security scanning, code optimization, and deep research. Maintained by the Kai team at FirstBatch.

Naming

The codebase was originally forked from Hermes Agent, but runtime names are now Kai-only. Use kai_* modules, KAI_* environment variables, and ~/.kai-agent/ for user state.

Development Environment

source .venv/bin/activate  # ALWAYS activate before running Python

Project Structure

kai-agent/
├── run_agent.py          # AIAgent class - core conversation loop (from Hermes)
├── model_tools.py        # Tool orchestration, _discover_tools(), handle_function_call()
├── toolsets.py           # Toolset definitions, _KAI_CORE_TOOLS list
├── cli.py                # CLI orchestrator
├── kai_state.py          # SessionDB - SQLite session store (FTS5 search)
├── agent/                # Agent internals
│   ├── prompt_builder.py     # System prompt assembly (Kai Agent identity)
│   ├── context_compressor.py # Auto context compression
│   ├── prompt_caching.py     # Anthropic prompt caching
│   ├── auxiliary_client.py   # Auxiliary LLM client
│   ├── model_metadata.py     # Model context lengths
│   ├── display.py            # Spinner, tool preview formatting
│   ├── skill_commands.py     # Skill slash commands
│   └── trajectory.py         # Trajectory saving helpers
├── tools/                # Tool implementations
│   ├── registry.py       # Central tool registry
│   ├── mcp_tool.py       # MCP client (connects to Kai backend + other servers)
│   ├── terminal_tool.py  # Terminal orchestration
│   ├── file_tools.py     # File operations
│   ├── web_tools.py      # Firecrawl search/extract
│   ├── browser_tool.py   # Browserbase browser automation
│   ├── delegate_tool.py  # Subagent delegation
│   └── ...               # Other tools
├── skills/               # Skill documents
│   ├── kai-security/     # Security scanning workflows
│   ├── kai-evolve/       # Evolution workflows
│   ├── kai-research/     # Research and analysis
│   ├── kai-ops/          # Operational monitoring
│   ├── research/         # General research skills (from Hermes)
│   └── software-development/  # Dev skills (from Hermes)
├── gateway/              # Messaging gateway (Slack, Discord, Telegram, Email)
└── cli-config.yaml       # Configuration including Kai MCP server

Key differences from upstream Hermes

  1. Scoped toolset: _KAI_CORE_TOOLS defines the Kai tool surface. No Home Assistant, image gen, TTS, RL, or Honcho tools.
  2. Kai Agent identity: System prompt in agent/prompt_builder.py defines a security/optimization research engineer persona.
  3. Kai MCP: Pre-configured connection to ${KAI_BACKEND_URL}/mcp with JWT auth. Auto-discovers 32 Kai tools.
  4. Kai skills: Pre-seeded workflows for scan, evolve, triage, evaluator creation, research contextualization, and monitoring.
  5. Env var expansion in MCP headers: tools/mcp_tool.py supports ${VAR} syntax in HTTP headers for auth tokens.

Kai MCP tools (auto-discovered)

The following tools are automatically available when connected to Kai backend:

  • Workspaces: list_my_workspaces, get_workspace_details
  • Repositories: list_repositories, get_repository_details, add_github_repository, remove_repository, browse_repository_files, read_repository_files
  • Code Audits: list_code_audits, start_code_audit, get_code_audit_details, abort_code_audit, get_audit_progress_logs, list_audit_tiers
  • Vulnerabilities: list_vulnerabilities, get_vulnerability_details
  • Code Optimization: list_code_optimizations, start_code_optimization, get_code_optimization_progress, abort_code_optimization, get_optimization_iterations, get_optimized_programs
  • Evaluators: list_code_evaluators, get_evaluator_details, create_ai_evaluator
  • Integrations: create_github_security_issue, create_jira_security_ticket
  • Billing: check_workspace_credits, view_billing_history

Running

# CLI mode
python cli.py

# Slack gateway
python -m gateway.run --platform slack

# With specific toolset
python cli.py --toolset kai-cli

Testing changes

python -m pytest tests/ -x -q