Promptulate (pne)
用几行 Python 代码搭建 LLM Agent 应用的轻量框架。
- Star 数
- ★ 513
- 最近更新
- 3 个月前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 41/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 需要在一个 Python 后端里快速接入多种大模型的开发者，用 pne.chat 统一调用 ollama 本地模型或云端模型
- 不适合
- 希望完全不写代码、直接用现成界面的用户
- 需要稳定长期支持与成熟生态的企业团队
- 不愿申请任何 LLM 或 Tavily 等第三方 API 密钥的用户
这个 Agent 能做什么，适合哪些场景？
Promptulate（简称 pne）是 Cogit Lab 开发的 AI Agent 应用开发框架，以 Python 风格 API 降低 Agent 开发门槛。核心入口是 pne.chat()：传入 messages 与 model 即可完成对话，也可通过 output_schema 直接得到 Pydantic 结构化输出。框架借助 litellm 集成近30家模型提供方，用 provider/model_name 形式切换 ollama、gpt-4o、anthropic 等模型。Agent 支持 enable_plan 开启 Plan-and-Solve 式的规划、工具调用与反思循环，并可单独调用 pne.Planner、pne.LLMFactory 等原子化组件。工具层可包装 LangChain 工具，也可把任意 Python 函数变成 Agent 工具。它以 Python 库形式嵌入你自己的应用，需要自备模型与搜索服务的 API 密钥。
通过 pip 安装 pne 后，开发者在 Python 代码中 import promptulate，主要调用 pne.chat()。它接收 messages（含 role/content 结构，支持 gpt-4o 的多模态 image_url 内容）、model 字符串、output_schema，返回字符串或解析后的 Pydantic 对象。当 enable_plan=True 时，框架先由 Agent 生成计划（goals 与带 task_id 的任务列表），再由 Tool Agent 依次执行 Thought/Action/Observation 循环，调用外部工具（如 LangChain 的 TavilySearchResults）并输出观察结果，最后给出 Agent Result 与修订后的计划。pne.LLMFactory.build() 构建模型实例，pne.Planner 可脱离完整 Agent 单独做任务规划。框架还提供 Hooks 与生命周期管理、Prompt 缓存、OpenAI SDK 替代能力和 Streamlit 组件。
- 需要在一个 Python 后端里快速接入多种大模型的开发者，用 pne.chat 统一调用 ollama 本地模型或云端模型
- 要让 LLM 返回固定字段（如省份列表、结构化表单）的后端工程师，用 output_schema 加 Pydantic 模型约束输出
- 需要让 Agent 自己拆分任务并通过搜索引擎回答多步问题的研究者，开启 enable_plan 配合 Tavily 工具
- 已有 LangChain 工具链、想以更低改造成本接入 Agent 的团队，直接复用 TavilySearchResults 等工具
- 做原型验证的产品与数据人员，用 Streamlit/Gradio 示例快速搭建聊天界面
- 只想用 Planner 组件做任务拆解、不需要完整 Agent 循环的开发者
如何安装或部署这个 Agent？
要求 Python 3.8 或更高版本，使用 pip 安装官方包名 pne：
pip install -U pne然后按所用模型设置对应 API 密钥环境变量，例如 OpenAI 与 Tavily：
export OPENAI_API_KEY="your_openai_api_key"
export TAVILY_API_KEY="your_tavily_api_key"如何使用这个 Agent？
最小可用调用是一次 pne.chat：
import promptulate as pne
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Who are you?"},
]
response: str = pne.chat(messages=messages, model="gpt-4-turbo")
print(response)模型用 provider/model_name 指定，例如本地 ollama：
import promptulate as pne
resp: str = pne.chat(model="ollama/llama2", messages=[{"content": "Hello, how are you?", "role": "user"}])用 Pydantic 模型获取结构化输出：
from typing import List
import promptulate as pne
from pydantic import BaseModel, Field
class LLMResponse(BaseModel):
provinces: List[str] = Field(description="List of provinces' names")
resp: LLMResponse = pne.chat("Please tell me all provinces in China.", output_schema=LLMResponse)
print(resp)开启规划能力并挂载 LangChain 搜索工具：
import promptulate as pne
from langchain_community.tools.tavily_search import TavilySearchResults
tools = [TavilySearchResults(max_results=5)]
pne.chat("what is the hometown of the 2024 Australia open winner?", model="gpt-4-1106-preview", enable_plan=True)也可以单独使用 Planner：
import promptulate as pne
model = pne.LLMFactory.build("gpt-4-turbo")
planner = pne.Planner(model, system_prompt="You are a planner")
plans = planner.run("Plan a trip to Paris")
print(plans)这个 Agent 有哪些优点和局限？
- 入口极其精简，pne.chat() 一个函数覆盖对话、结构化输出和 Agent 规划，上手只需几行代码
- 通过 litellm 兼容近30家模型提供方，用 provider/model_name 命名即可切换云端与本地 ollama 模型
- 提供 output_schema 与 Pydantic 集成，直接得到可校验的结构化返回值，而非拼接文本
- Agent 组件原子化，Planner、LLMFactory 可单独使用，便于按需定制而非被迫接受整套流程
- 可直接包装 LangChain 工具，并把任意 Python 函数转为 Agent 工具，降低已有工具链的迁移成本
- Apache-2.0 许可，免费自托管，并附带 Streamlit/Gradio 示例帮助快速验证
- 本身不是开箱即用的产品，必须写 Python 并自备模型与搜索服务密钥，才能跑通真实功能
- 功能版图较大（Agent、RAG、Hooks、缓存、终端、Streamlit），文档分散在多个入口，快速判定某项能力仍需查站外文档
- 规划与工具执行链路的输出依赖所接模型质量，README 示例中会出现多轮搜索与修订，token 消耗不可预知
- 未提供版本发布记录或兼容承诺的证据，生产环境中框架 API 稳定性需自行评估
- 使用 Tavily 搜索需额外注册账号与 API 密钥，示例依赖 LangChain 社区包，引入额外依赖
这个 Agent 与同类方案有什么区别？
README 提到 LangChain（复用 TavilySearchResults 等工具）、AutoGen 与 litellm（模型接入层）等生态项目，并把 pne 定位为借鉴社区框架优点、统一开发者共识的轻量替代方案；它强调无需使用 openai sdk，可以直接用 pne.chat 替换 OpenAI 调用。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Promptulate (pne) 当前 | 41 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 513 | 3 个月前 | Python | OpenAI API |
| CaveAgent | 62 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 219 | 1 个月前 | Python | OpenAI API · Claude API |
| AG2：开源智能体操作系统 | 55 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 5k | 1 天前 | Python | OpenAI API |
| AI SDK | 50 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 28k | 今天 | TypeScript | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示框架通过 litellm 调用 100+ 模型，API key 通过环境变量或 model_config 传入，README 与 chat_usage 有基本说明，但没有任何关于权限最小化、工具调用前用户确认、数据流向披露、敏感数据脱敏或回滚机制的文档或代码证据；依赖清单包含 litellm、openai、requests 等大量第三方包，未见漏洞审计或锁定策略说明；外部副作用（工具执行、网络搜索）无确认或撤销路径。因此 least_privilege、user_confirmation、rollback 得 0-1 分，data_flow_transparency、sensitive_data_handling、dependency_security、external_effects 仅因有零散说明得 1 分；source_attribution 因 README 明确标注 Cogit Lab、litellm、LangChain、Tavily 等来源得 2 分。
README 与 chat_usage 对 pne.chat 的用法描述基本一致，但示例中存在不一致（如 Deepseek 示例设置 OPENAI_API_KEY 却用 deepseek/ 前缀，README 与 chat_usage 的模型名写法略有差异）；依赖版本在 pyproject 与 requirements.txt 之间存在漂移（litellm ^1.39.6 vs 1.72.0），且 broadcast-service 固定 1.3.2 等小众包可用性未说明；失败信息方面仅 FAQ 提到 SSLError 与代理配置，未见系统性错误码或异常处理文档。故三项均得 1 分。
README 明确面向 Python 开发者，覆盖聊天、结构化输出、工具、Agent、Streamlit 等多场景，audience_and_scenarios 得 2 分；但能力边界（哪些任务不适合、Agent 规划失败时的行为）仅在示例输出中隐式体现，未系统说明，capability_boundaries 得 1 分；触发精度方面 enable_plan、tools 等参数语义有示例但无精确契约，得 1 分；environment_fit 因声明支持 Python 3.8+、多 OS CI 矩阵、litellm 多提供商，得 2 分。
README 结构清晰、有中英文入口、文档站链接、安装命令与示例，information_architecture 与 install_notes 得 2 分；examples_and_faq 有多个用例与 FAQ，得 2 分；LICENSE 为完整 Apache-2.0 文本，得 3 分；但命名稳定性方面 pne/promptulate 双名并存、beta 模块路径（promptulate.beta）暗示 API 未稳定，得 1 分；known_limitations 仅 FAQ 两条，得 1 分；versioning_changelog 仅有 pyproject 版本号 1.18.4，无 CHANGELOG 文件，得 1 分；maintenance_responsibility 仅有作者邮箱与 Telegram，无治理或维护承诺说明，且发布者未经验证，得 1 分。
output_usability 因结构化输出（Pydantic schema）、流式、原始响应元数据等设计得 2 分；marginal_value 方面框架定位与 LangChain 等重叠，README 自述“借鉴社区智慧”，差异化证据有限，得 1 分；cost_benefit 因依赖较重（litellm、openai、tiktoken 等）且无性能或成本对比数据，得 1 分。
claim_traceability 方面 README 的模型支持表链接到 litellm 文档，但“支持几乎所有模型”等断言无本仓库内验证；cross_source_corroboration 方面 README、chat_usage、测试文件对 pne.chat 与 ToolAgent 的描述可部分互证，但测试仅覆盖初始化与 schema 解析，未覆盖核心调用路径；fact_inference_separation 方面示例输出（如天气、网球冠军）为演示性内容，未标注为示意而非实测。三项均得 1 分。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 框架通过 litellm 调用外部模型，API key 以环境变量或 model_config 明文传入，未见密钥管理或脱敏机制，生产使用需自行封装。
- 工具与 Agent 执行（如 Tavily 搜索、自定义函数）没有用户确认或回滚机制，外部副作用不可撤销，需在应用层加护栏。
- pyproject.toml 与 requirements.txt 的依赖版本不一致（如 litellm ^1.39.6 vs 1.72.0），复现环境时以哪个为准不明确。
- beta 模块路径（promptulate.beta）与 pne/promptulate 双名并存，API 稳定性存疑，升级前应锁定版本。
- 发布者身份未经验证，维护责任与更新路径仅有作者邮箱和 Telegram，企业采用前应评估供应链风险。
- README 中的示例输出为演示性内容，不能作为功能正确性或性能的实测证据。