agentpools Python 客户端指南
基于底层 Rust 高性能调度内核的 Python 异步客户端。
专为需要在 Python / asyncio 环境下高效、稳定管理多个长连接 AI Agent（Codex、Pi、ACP）而设计，提供优雅的原生
async with上下文管理。
1. 核心特性
- 极致轻量高效：基于 PyO3 与 Rust 原生线程池，避开 Python GIL 锁限制，多 Worker 并发性能极佳。
- 上下文管理器完美支持：使用
async with AgentPool(...)与async with await pool.acquire()，自动管理获取与安全归还，无句柄泄漏之忧。 - 多运行时与统一 MCP：完全支持 API v2，可在同一个池中混合调度 Codex app-server、Pi RPC 和 ACP，并统一注入 MCP 工具。
2. 本地开发与构建
环境要求：Python 3.9+，Rust 稳定版，maturin。
# 进入目录并安装 maturin
cd bindings/python
pip install maturin
# 本地快速构建并安装到当前虚拟环境
maturin develop
# 运行自动化测试套件
python -m unittest discover -s test -p "test_*.py"
3. 典型使用示例
① 基础使用与上下文管理
import asyncio
import os
from agentpools import AgentPool
async def main():
config = {
"apiVersion": 2,
"maxQueued": 16,
"agents": [
{
"runtime": "codexAppServer",
"program": "codex",
"args": ["app-server"],
"cwd": os.getcwd(),
"mcpServers": [
{"name": "sqlite", "command": "uvx", "args": ["mcp-server-sqlite"]}
]
}
]
}
# 1. 启动池
async with AgentPool(config) as pool:
# 2. 独占借出一个 Worker
async with await pool.acquire() as lease:
reply1 = await lease.ask("帮我写一个二分查找算法。")
print("第一轮回复:", reply1["text"])
# 在同一会话与上下文中追问
reply2 = await lease.ask("请加上详细的注释和复杂度分析。")
print("追问回复:", reply2["text"])
# 离开 lease 上下文时，Worker 自动归还池中
asyncio.run(main())
② 多轮校验与循环修复（Code Review 模式）
async with await pool.acquire() as lease:
res = await lease.ask("设计一个用户登录组件")
while needs_fix(res["text"]):
# 依然在原会话中根据反馈调整
res = await lease.ask("密码校验规则不符合要求，请调整后重新输出。")
4. 详细文档指引
1 maintainer
Metadata
1 maintainer
Release files for agentpools 0.1.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentpools-0.1.9.tar.gz | 133.3 kB | With provenance | Details for agentpools-0.1.9.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| agentpools-0.1.9-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for agentpools-0.1.9-cp39-abi3-win_amd64.whl |
| agentpools-0.1.9-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details for agentpools-0.1.9-cp39-abi3-manylinux_2_28_x86_64.whl |
| agentpools-0.1.9-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details for agentpools-0.1.9-cp39-abi3-manylinux_2_28_aarch64.whl |
| agentpools-0.1.9-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for agentpools-0.1.9-cp39-abi3-macosx_11_0_arm64.whl |
| agentpools-0.1.9-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for agentpools-0.1.9-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 3.6 MB
Release files / agentpools-0.1.9.tar.gz
| Download URL | agentpools-0.1.9.tar.gz |
|---|---|
| Size | 133.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f57fe3c614dc5dd9d3ba6d816bb6bbda9428f59537fbf43ed5216e080d3024e
|
|
BLAKE2b-256 checksum How to use checksums |
0954533f5b80835af8b1740b8da552c5ab7b030352bf1521a7b16fbf8b814945
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / agentpools-0.1.9-cp39-abi3-win_amd64.whl
| Download URL | agentpools-0.1.9-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 577.3 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
4c81ca17d50bff4b996d9e15ad405ec6ccd6045f9d8975cfe19167ba0d43a7f0
|
|
BLAKE2b-256 checksum How to use checksums |
8711aed020c33773f9eb477359e654c241913365098ecadbf0eab39bee7abfb9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / agentpools-0.1.9-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | agentpools-0.1.9-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 758.6 kB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
7377ce17213970188ada57d2986bd6d440812b57b8c93dcf6a5c81aaead8b9a9
|
|
BLAKE2b-256 checksum How to use checksums |
9ecfae5401cf5559f8bad0b07eb5cdeac3a9d37a6df52842a5f87989d421ad62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / agentpools-0.1.9-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | agentpools-0.1.9-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 729.4 kB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
61802ff3dcc4db890e90802bd33189ed12dda3ecca4569d748b3bcc2ad02ed80
|
|
BLAKE2b-256 checksum How to use checksums |
c93e1a9ce7b707c2860826d5d08adb5434531eccaa90b9a58e5f3bbb004841e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / agentpools-0.1.9-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | agentpools-0.1.9-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 667.4 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
3d3123c2eabc8f9b2dc479108ad0b0b401713e39dbb495deab15ba583434ba0b
|
|
BLAKE2b-256 checksum How to use checksums |
2bd177c266dfda821d9f344532ee42c31c56869621decce141c967489af71dc7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / agentpools-0.1.9-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | agentpools-0.1.9-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 694.9 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
33e016b0d87205908cdfc2393da657cec82e1cd8513cfd2bf9fc4af4d16ebe0e
|
|
BLAKE2b-256 checksum How to use checksums |
2076312d8156563a6909803367aba67112e4b17d84d89c8fab62f5226ea4955d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logSecurity for agentpools 0.1.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for agentpools-0.1.9.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
