Agent Kernel Lab

A small Python runtime for studying how an Agent system can coordinate planning, memory, tool calls, decision routing, and multi-agent review.

中文说明：这是一个从零写的小型 Agent runtime，用来展示 AI Agent 系统里的任务分解、记忆、工具调用、决策路由、多 Agent 协作和状态机 trace。

Project page · Repository

Direction

This project is informed by the current Agent framework direction on GitHub: high-star projects such as AutoGen, CrewAI, LangGraph, and AutoAgent show strong demand for stateful orchestration, tool use, and multi-agent collaboration. This repository is a smaller independent implementation focused on readable core mechanics instead of broad integrations.

中文说明：当前 GitHub 上高热 Agent 框架主要集中在多 Agent 协作、状态化编排、工具调用和自动化工作流。本项目不复制这些框架的代码，而是做一个更小、更容易阅读的核心机制实现。

What Is Implemented

• Task decomposition engine that turns a broad goal into ordered task objects.
• Tool registry with explicit tool specs and safe unknown-tool handling.
• Short-term and long-term memory store with lexical ranking.
• Decision engine that routes task types to agent roles.
• Multi-agent execution with planner, builder, and critic profiles.
• State machine for received -> planning -> acting -> reviewing -> completed.
• CLI that prints a human-readable trace or full JSON trace.
• Pytest coverage for memory, tools, state transitions, and runtime execution.
• Static GitHub Pages project page for architecture and demo trace.

中文：

• 任务分解引擎：把宽泛目标拆成有顺序的 task。
• 工具注册层：显式管理工具，未知工具会返回失败结果。
• 短期/长期记忆：使用轻量词法排序做 memory retrieval。
• 决策引擎：按任务类型路由到不同 Agent。
• 多 Agent 执行：包含 planner、builder、critic 三类角色。
• 状态机：记录 received、planning、acting、reviewing、completed。
• CLI：可输出可读 trace 或完整 JSON trace。
• 测试：覆盖 memory、tools、状态机和 runtime。
• GitHub Pages：展示架构和运行 trace。

Architecture

Goal
  -> TaskDecomposer
  -> StateMachine
  -> DecisionEngine
  -> AgentExecutor
  -> ToolRegistry
  -> MemoryStore
  -> Trace + Final Summary

Core modules:

Module	Responsibility
agent_kernel.planner	split a broad requirement into task objects
agent_kernel.memory	store and retrieve short/long-term memory
agent_kernel.tools	register and execute deterministic tools
agent_kernel.agents	define agent profiles and task routing decisions
agent_kernel.state	enforce valid runtime state transitions
agent_kernel.runtime	orchestrate planning, acting, review, and trace output

中文：整体结构把 Agent 系统拆成可测试模块，而不是把所有逻辑塞进一个 prompt 或一个巨大的函数。

How To Run

git clone https://github.com/jsdnaasd/agent-kernel-lab.git
cd agent-kernel-lab

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run a trace:

agent-kernel run "Design an AI Agent system with planning, memory, tool calling, and multi-agent review"

Run with seed memory and JSON output:

agent-kernel run "Build a reliable agent workflow" \
  --memory "Agent systems need planning, memory, tool routing, and critic review." \
  --json

中文：CLI 会输出 goal、最终摘要、每个 task 的 agent/tool 分配，以及状态机过程。

Verification / Tests

pytest -v

Expected coverage:

• memory search ranks relevant items
• tool registry handles known and unknown tools
• state machine rejects invalid transitions
• runtime completes a multi-agent trace
• JSON trace contains tool outputs

Static page check:

python3 -m http.server 5173 --directory docs
curl -I http://localhost:5173

Known Limitations

• No external LLM call yet; the runtime is deterministic by design.
• Memory retrieval is lexical, not embedding-based.
• Tool execution is local and synchronous.
• Multi-agent collaboration is role-based routing, not free-form chat between agents.
• No durable database; memory is in-process.
• No sandbox for arbitrary user-defined tools yet.

中文限制：

• 当前没有调用外部大模型，先做确定性的 runtime。
• memory retrieval 是词法检索，不是向量检索。
• 工具执行是本地同步调用。
• 多 Agent 协作是角色路由，不是多个模型自由对话。
• 没有持久化数据库。
• 还没有用户自定义工具的沙箱。

Roadmap

• Add persistent SQLite memory.
• Add optional embedding-based memory retrieval.
• Add async tool execution and timeout controls.
• Add a YAML workflow loader.
• Add a simple model adapter interface for OpenAI-compatible APIs.
• Add evaluation fixtures for planner output quality.

中文下一步：

• 增加 SQLite 持久化 memory。
• 可选接入 embedding memory retrieval。
• 增加异步工具执行和超时控制。
• 增加 YAML workflow loader。
• 增加 OpenAI-compatible model adapter。
• 增加 planner 输出质量评测样例。