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

Metadata

Release files for langchain-agentx-python 2.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langchain-agentx-python 2.3.4
File	Size	Uploaded
langchain_agentx_python-2.3.4.tar.gz	1.1 MB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for langchain-agentx-python 2.3.4
File	Interpreter	ABI	Platform	Reset
langchain_agentx_python-2.3.4-py3-none-any.whl 1.5 MB Sep 29, 2026	Python 3	none	any	Details

Total release size: 2.6 MB

Release files / langchain_agentx_python-2.3.4.tar.gz

Download URL	langchain_agentx_python-2.3.4.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`12caf71cfd17119bdbfbbc05a338aa202c5fb8c0869fac960f74c9038f54a76a`
BLAKE2b-256 checksum How to use checksums	`8f696b69eb3f786b6f785cd6ca849e7b7af6d11422e16a578390c2b9f5ca9225`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.6`

Release files / langchain_agentx_python-2.3.4-py3-none-any.whl

Download URL	langchain_agentx_python-2.3.4-py3-none-any.whl
Size	1.5 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`36312ef5c7933d6cc0400558a9abe0a834b71cefc0e1c6d18ceca3c185ea0b61`
BLAKE2b-256 checksum How to use checksums	`93cf7a177f603740a52b7164108161ff124be63fb85c3c77ba7c98c633baaaa6`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.6`