langchain-agentx-python
langchain-agentx-python 是一组基于 LangChain / LangGraph 的”代码智能体”工具函数，帮助你在自己的项目里快速集成：
- OpenCode 风格的 LangGraph Agent（代码理解、重构、分析）
- 上下文感知中间件、性能监控等基础设施
- 完整的工具运行时系统和权限管理
安装
发布到 PyPI 后，你可以直接通过 pip 安装：
pip install langchain-agentx-python
快速上手
from langchain_agentx import create_loop_agent
# 这里省略 LangChain / LangGraph 相关模型与工具配置
agent = create_loop_agent(...)
具体的能力和使用方式可以参考源码中的 docstring 以及各模块下的 README.md。
工具进度显示
长耗时工具（如 BashRuntimeTool）可在执行期间通过 ToolExecutionContext.emit_progress() 向 CLI 实时报告进度。事件经 LangGraph dispatch_custom_event("tool_progress", ...) 发出，CLI 通过 astream_events 接收。
# 工具 invoke 内（同步路径）
ctx.emit_progress(
phase="running",
data={"output": chunk, "total_lines": line_count, "elapsed_time_seconds": elapsed},
)
# 异步工具
await ctx.aemit_progress(phase="query_update", data={"query": query})
向后兼容：进度为可选能力。未发射 progress 或 CLI 未监听时，工具仍按 ToolResultEnvelope 正常返回。emit_progress 在无 LangGraph 上下文时静默失败，不中断工具主流程。
文档：
- 设计：
docs/design-docs/tool-runtime/tool-progress-design.html - 事件契约：
docs/design-docs/tool-runtime/tool-progress-event-contract.html - 工具作者门禁：
docs/guides/tool-implementation-checklist.html#section-4-2
测试：
pytest tests/regression/tool_progress/ tests/tool_runtime/progress/ langchain_agentx/tool_runtime/test_emit_progress.py -v
发布新版本流程
重要特性：本项目的构建脚本会自动排除所有测试文件，生成纯净的生产包。当前有 140+ 个测试文件在构建时会被自动过滤，确保发布的包轻量、干净。
以下命令默认在项目根目录并已激活 Python 虚拟环境。
📋 发布前检查清单
- 代码已提交到 Git 仓库
- 版本号已更新（
pyproject.toml） - 工作区干净（
git status检查） - 已安装构建工具（首次需要）
🚀 快速发布（推荐使用专用构建脚本）
Step 1: 准备版本号
编辑 pyproject.toml，修改版本号：
[project]
name = "langchain-agentx-python"
version = "0.1.0" # 当前版本为 0.1，发布建议改为 0.1.0
Step 2: 提交代码更改
# 检查状态
git status
# 提交所有更改
git add .
git commit -m "release: prepare for version 0.1.0"
git push
Step 3: 使用专用构建脚本生成纯净包
# 使用项目专用构建脚本（自动排除测试文件）
bash script/build-wheel.sh
构建脚本特性：
- ✅ 自动排除 140+ 个测试文件
- ✅ 排除
__pycache__、.pytest_cache等 - ✅ 验证 wheel 包内容安全性
- ✅ 生成到
_build/dist/目录
构建成功后会看到：
== Wheel content check (no test_* files) ==
wheel: langchain_agentx_python-0.1.0-py3-none-any.whl
py files: 456
bad test-like files: 0
wheel check ok
Step 4: 验证构建产物
# 查看生成的文件
ls -lh _build/dist/
# 应该看到：
# langchain_agentx_python-0.1.0-py3-none-any.whl
Step 5: 本地测试安装（推荐）
# 创建临时测试环境
python -m venv test_env
source test_env/bin/activate # Linux/macOS
# 或 test_env\Scripts\activate # Windows
# 安装构建的包
python -m pip install _build/dist/*.whl
# 验证导入
python -c "from langchain_agentx import create_loop_agent; print('SDK 安装成功')"
# 清理测试环境
deactivate
rm -rf test_env
Step 6: 发布到 PyPI
首次发布需要配置 PyPI 凭证：
- 注册 PyPI 账号：https://pypi.org/account/register/
- 启用双重认证（2FA）
- 生成 API Token：https://pypi.org/manage/account/token/
- 创建
~/.pypirc配置文件：
cat > ~/.pypirc <<'EOF'
[distutils]
index-servers =
pypi
testpypi
[pypi]
username = __token__
password = pypi-xxxx你的API_TOKENxxxx
[testpypi]
username = __token__
password = pypi-xxxx你的TestPyPI_TOKENxxxx
EOF
发布到 TestPyPI（推荐先测试）：
# 上传到测试仓库
python -m twine upload --repository testpypi _build/dist/*
# 测试安装
python -m pip install --index-url https://test.pypi.org/simple/ langchain-agentx-python==0.1.0
发布到正式 PyPI：
# 上传到正式仓库
python -m twine upload _build/dist/*
# 验证发布
python -m pip install langchain-agentx-python==0.1.0
Step 7: 打标签并推送（可选但推荐）
# 创建版本标签
git tag v0.1.0
# 推送标签到远程
git push --tags
📦 备用方法：使用标准构建工具
如果专用构建脚本不可用，可以使用标准方法：
# 安装构建工具
python -m pip install -U build twine
# 清理旧构建
rm -rf dist/ build/ *.egg-info
# 构建分发包
python -m build
# 查看产物
ls -lh dist/
# 发布
python -m twine upload dist/*
⚠️ 注意事项
- 版本号格式：建议使用语义化版本，如
0.1.0、0.2.0等 - 测试文件排除：专用构建脚本会自动排除所有测试文件，标准方法需要手动配置
- PyPI 名称：包名在 PyPI 上显示为
langchain-agentx-python - 版本冲突：如果版本号已存在，上传会失败，需要更新版本号
🔄 下次发布
下次发布时，只需重复上述步骤：
- 更新
pyproject.toml版本号 - 提交代码：
git commit && git push - 构建包：
bash script/build-wheel.sh - 发布：
python -m twine upload _build/dist/* - 打标签：
git tag && git push --tags
核心功能
Agent Loop 系统
- OpenCode 风格的 LangGraph Agent 实现
- finish_reason 驱动的主动退出机制
- 完全兼容 LangChain 生态
工具运行时系统
- 跨平台工具执行（Bash、Glob、Grep、Read 等）
- 权限管理和安全控制
- 工具状态隔离和会话管理
中间件和钩子系统
- 上下文感知的中间件
- before/after 钩子系统
- 性能监控和事件追踪
配置和工作空间管理
- 统一的工作空间配置
- Agent Home 目录管理
- 跨平台路径处理
文档
- 工程指南：
CLAUDE.md - 架构文档：
docs/architecture/ - 设计文档：
docs/design-docs/ - 开发指南：
docs/guides/
开发
环境
# 推荐：项目 venv（Windows Git Bash 示例）
export VENV_PYTHON="$HOME/langchain_agentx_venv/Scripts/python.exe"
# 可编辑安装 + dev 依赖（首次或 pyproject.toml 变更后）
"$VENV_PYTHON" -m pip install -e ".[dev]"
依赖方向门禁（import-linter，提交前自检）
阶段 0 仓内 import 方向静态门禁（F1 / F3 / F4 / I1 / L1）。本地 git commit 不会触发 CI；GitHub Actions 在 push 到 main 或 开/更新 PR 时运行（且变更命中 .importlinter、langchain_agentx/** 等 paths 时）。
改 langchain_agentx/ 前或 commit 前建议跑：
# 1) import 方向扫描（与 CI lint-imports job 一致）
bash scripts/lint-imports.sh
# 2) pytest 回归（CI 同跑）
python -m pytest langchain_agentx/test_import_direction_gate_regression.py -v
# 3) trace 伴侣包单向依赖（正交互补，建议一并跑）
python -m pytest langchain_agentx/test_trace_companion_import_guard.py -v
Windows 若不用脚本，可等价执行：
export PYTHONUTF8=1
lint-imports --config .importlinter
新增跨层 / 禁依赖 import 且无合法 ignore 登记 → 上述命令 exit 非 0；已在 baseline 的老违规（.importlinter 内 ignore_imports）→ 仍可通过。
维护 baseline（须同步 docs/design-docs/evolution/baseline-exit-plan.md，单独 PR）：
python scripts/generate_importlinter_ignore.py
设计 / 实施文档：docs/design-docs/evolution/stage-0-dependency-direction-gate.md · docs/exec-plan/evolution/stage-0-dependency-direction-gate-2026-06-10.html
运行测试
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest langchain_agentx/
一键日常（不含 LLM）：bash scripts/run-default-tests.sh（详见 scripts/README.md）
代码规范
所有代码遵循项目编码规范：docs/guides/coding-style-guide.html
贡献
欢迎提交 Issue 和 Pull Request！
许可证
Apache License 2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file langchain_agentx_python-2.1.9.tar.gz.
File metadata
- Download URL: langchain_agentx_python-2.1.9.tar.gz
- Upload date:
- Size: 1.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
42ecf03b11195bcccf6fd48e482d01d61f5e55a5b16ffde91aaa858c235be7f6
|
|
| MD5 |
3ee8dc6c1010f6a7868d35028416c0e4
|
|
| BLAKE2b-256 |
c6a50181c39adb2242219b48c3f687de9ab89fdcb3996e2467439d193606b6cd
|
File details
Details for the file langchain_agentx_python-2.1.9-py3-none-any.whl.
File metadata
- Download URL: langchain_agentx_python-2.1.9-py3-none-any.whl
- Upload date:
- Size: 1.5 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6566871e94763f8d68c397fb7c3d573395c5af4f4f71de8095e07394a1905852
|
|
| MD5 |
8c24fc8242e0b8b1f929b284cfc32e8a
|
|
| BLAKE2b-256 |
05b53837c13ca172cd0e673a7f356f90fbc2adcf361397545aa7101818020d66
|
