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/* 只接受来自回环地址的请求。跨站表单提交也发不进来,因为接口要求一个自定义请求头。
它用自己的密钥
代理不需要单独的模型密钥——它复用你已有的上游密钥、轮询和故障切换逻辑。如果配置里存在管理密钥,代理会使用管理密钥;普通的模型密钥无权调用编程相关的端点。