返回博客

Pi Agent:能做什么,不能做什么

内置的编程代理有哪些工具、边界在哪里,以及"工作目录不是沙箱"这句话具体意味着什么。

Free Router 里内置了 Pi 编程代理。它直接复用你已经配好的网关配置,不需要再单独准备一套模型密钥。

它有哪些工具

代理开箱可用的工具是:

read · write · edit · bash · grep · find · ls · web_search

前七个是内置的,web_search 是通过 Exa 提供的自定义工具,需要配置 EXA_API_KEY。前七个足以覆盖“读代码 → 改文件 → 跑测试”这一整条链路。

默认的思考等级是 high。它注册的是那四个网关模型 ID,provider 名叫 free-router,协议是 OpenAI Chat Completions——也就是说,代理和你的应用走的是同一个入口。

明确的边界

这些限制写在代码里,不是可以绕过的软性建议:

限制 值
最多会话数 12
同时运行的任务 1
会话存储 仅内存
助手消息长度上限 80000 字符
工具输出默认截断 24000 字符

同一时间只跑一个任务,再开一个会收到 409。会话只存在于内存里:刷新 Web 界面不会丢,重启服务会清空,但已经改过的文件不会回来。

默认工作目录是项目根目录,可以用 PI_AGENT_WORKSPACE 改。

工作目录不是沙箱

这句提示值得展开讲,因为它是最容易被误解的地方。

代理的工具以你的本机用户权限执行。 工作目录只是用来解析相对路径的,不是安全边界。

也就是说,用你的用户能读的文件它就能读,能写的地方它就能写,能执行的命令它就能执行。没有额外的权限收缩,没有路径白名单。

结论很简单:在你信任的本机环境里使用它。 如果你需要真正的隔离,容器或者一个权限受限的用户才是合适的工具,Pi Agent 不是。

它怎么被调用

Rust 后端在首次打开代理时,会在随机端口上拉起一个 Node 进程,只绑定回环地址,并用一次性的 32 字节十六进制令牌(PI_BRIDGE_TOKEN,每个桥接实例重新生成)做鉴权。

Node 侧的 HTTP 接口是一份固定白名单:GET /status、GET|POST /sessions、GET|DELETE /sessions/:id、POST /sessions/:id/prompt、POST /sessions/:id/abort。其余路径一律拒绝,Rust 侧还会再校验一遍。关闭由 Rust 关闭 Node 的 stdin 触发。

如果没有设置 GATEWAY_API_KEY,/api/agent/* 只接受来自回环地址的请求。跨站表单提交也发不进来,因为接口要求一个自定义请求头。

它用自己的密钥

代理不需要单独的模型密钥——它复用你已有的上游密钥、轮询和故障切换逻辑。如果配置里存在管理密钥,代理会使用管理密钥;普通的模型密钥无权调用编程相关的端点。