easy-agentic 0.1.0

A plugin framework for agents, built on LangGraph deepagents + langgraph-cli.

easy-agentic

一个面向 Agent 的 plugin（插件）框架：为构建在 LangGraph deepagents + langgraph-cli 之上的 Agent 提供统一的扩展注入机制，所有扩展（agent / tool / skill / filesystem / middleware / model …）都通过 plugin 接入。

它不是业务 Agent，也不实现运行时或服务容器——这些分别交给 deepagents 与 langgraph-cli。 详细定位与设计见 doc/requirement.md 与 doc/architecture.md。

技术栈

• Python 3.12（由 uv 锁定）
• 包 / 环境管理：uv
• Agent 运行时：deepagents；服务/接口：langgraph-cli（agent server）
• LLM 方向：Claude（langchain-anthropic）

---

快速开始

# 1. 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 同步依赖（按 uv.lock 装齐到 .venv）
uv sync

# 3. 配置环境变量：复制 .env 模板并填入 API key 等
#    （.env 已被 git 忽略，切勿提交真实密钥）

# 4. 启动本地 agent server（LangGraph Studio）
uv run langgraph dev
# 默认 http://127.0.0.1:2024

---

uv 使用方式

uv 一个工具搞定 Python 版本 + 虚拟环境 + 依赖 + 运行：读 pyproject.toml（声明的依赖）→ 解析出 uv.lock（锁定精确版本）→ 同步进 .venv。日常不需要手动激活虚拟环境，用 uv run 即可。

最常用的命令

命令	作用	何时用
uv add <包>	加运行时依赖（自动写入 pyproject 并安装）	要用某个库时（别手改 pyproject）
uv add --dev <包>	加开发依赖（pytest、ruff 等）	仅开发/测试用的工具
uv remove <包>	移除依赖	不再需要时
uv run <命令>	在项目环境里执行命令	跑一切：uv run pytest、uv run langgraph dev
uv sync	让 .venv 与 uv.lock 对齐	拉取代码 / 切换环境后一键装齐

90% 的时间只会用到 uv add 和 uv run。

关键认知

• 依赖只通过 uv add 管理，不要手动编辑 pyproject.toml 的 dependencies；精确版本锁在 uv.lock（纳入版本控制）。
• uv run 会在执行前隐式同步环境，所以加完依赖可直接 uv run，无需先 uv sync。
• 不用 pip install、不用 source .venv/bin/activate——uv 自动为子进程准备好环境。
• Python 版本由 .python-version 锁定为 3.12，uv 自动选用对应解释器。

uv run 的内部机制（简述）

uv run X ≈ 「确保环境与 lock 一致」+「临时激活 .venv」+「执行 X」。其中 X 最终落到 .venv/bin/ 下绑定了本项目解释器的可执行文件：

• uv run pytest → 执行 .venv/bin/pytest（安装时生成的入口脚本，shebang 指向项目 .venv 的 python）
• uv run python foo.py → 用 .venv/bin/python 跑 foo.py

常用开关：--no-sync（跳过同步）、--frozen（不重解析）、--locked（要求 lock 已最新，适合 CI）。

---

常用开发命令

uv run langgraph dev          # 启动本地 agent server（总入口 graph: easy_agentic.graph:main）
uv run pytest                 # 跑测试
uv add <包> / uv add --dev <包>   # 增加依赖
uv sync                       # 同步环境

项目文档

• CLAUDE.md — 项目宪法（给 AI 协作者）
• doc/ — 需求、架构、规范、路线图、决策记录（ADR）