如何在 Pi coding agent 会话中使用 PiProvider 调用 Composio 工具-开发者社区

如何在 Pi coding agent 会话中使用 PiProvider 调用 Composio 工具

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

如果你的 TypeScript 项目正在使用@earendil-works/pi-coding-agent搭建 Pi coding agent，需要让它在会话中搜索、执行 Composio 工具，本文给出从安装依赖、创建 Composio 会话，到把 Composio 工具挂进 Pi 会话并用 hooks 拦截调用这条完整路径。PiProvider从@composio/experimental包发布，仅面向 TypeScript 项目；该包是实验性出口，API 可能在版本之间变更或被移除。

安装依赖与配置 API key

在 TypeScript 项目中安装三个包（npm 为例，pnpm / bun / yarn 同理）：

npm install @composio/core @composio/experimental @earendil-works/pi-coding-agent

在.env中配置 Composio 项目 API key：

COMPOSIO_API_KEY=xxxxxxxxx

xxxxxxxxx替换为你在 Composio 平台上的项目 API key。

创建 Composio 会话并生成 Pi 工具

核心流程分三步：创建 session、用createSessionTools生成 Pi 工具、把这些工具交给createAgentSession。完整可运行示例（user_123与callbackUrl需替换，见下文说明）：

import { Composio } from '@composio/core'; import { PiProvider, createPiComposioSystemPrompt } from '@composio/experimental'; import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, } from '@earendil-works/pi-coding-agent'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new PiProvider(), }); const composioSession = await composio.sessions.create('user_123', { toolkits: ['github', 'gmail'], manageConnections: { enable: true, callbackUrl: 'https://your-app.example.com/auth/callback', }, sandbox: { enable: true }, }); const composioTools = composio.provider.createSessionTools({ sessionId: composioSession.sessionId, search: composioSession.search.bind(composioSession), execute: composioSession.execute.bind(composioSession), callbackUrl: 'https://your-app.example.com/auth/callback', includeWorkbenchTools: true, connections: { getToolkitStates: toolkits => composioSession.toolkits({ toolkits }), authorizeToolkit: (toolkit, options) => composioSession.authorize(toolkit, options), }, hooks: { execute: (ctx, next) => { if (ctx.request.toolSlug === 'COMPOSIO_MANAGE_CONNECTIONS') { return ctx.deny('Use composio_manage_connections instead.'); } return next(); }, onAuthLink: async ctx => { await sendConnectionLinkToUser(ctx.url); return { message: 'Connection link sent out-of-band.' }; }, }, }); const loader = new DefaultResourceLoader({ cwd: process.cwd(), agentDir: getAgentDir(), systemPromptOverride: () => createPiComposioSystemPrompt(composioSession.sessionId, { includeWorkbenchTools: true, }), }); await loader.reload(); const { session: piSession } = await createAgentSession({ cwd: process.cwd(), resourceLoader: loader, sessionManager: SessionManager.inMemory(process.cwd()), customTools: composioTools, tools: [ 'composio_search_tools', 'composio_manage_connections', 'composio_execute_tool', 'composio_remote_workbench', 'composio_remote_bash', ], }); await piSession.prompt('Find my open GitHub issues and summarize the blockers.');

示例中有几处需要按自己的应用替换：

'user_123'：Composio 用它做用户隔离标识，文档建议使用不会变化的数据库 UUID 或主键，生产环境不要用default。
callbackUrl：OAuth 回调地址，替换为你应用自己的回调端点。
sendConnectionLinkToUser：你应用中把连接链接投递给用户的函数，文档示例中未给出实现。
toolkits: ['github', 'gmail']：把会话限制在这些 toolkit 内；不传该参数时，会话可发现 Composio 目录中的全部 toolkit。
manageConnections: { enable: true }让模型可以在缺少连接时发起认证；sandbox: { enable: true }是composio_remote_workbench/composio_remote_bash两个远程助手的前提——sandbox 被关闭时，COMPOSIO_REMOTE_WORKBENCH和COMPOSIO_REMOTE_BASH_TOOL不会出现在会话中。

provider 按配置生成这些 Pi 工具：

composio_search_tools：搜索 Composio，拿到精确的 tool slug 和 schema。
composio_manage_connections：检查连接状态，为缺失的 toolkit 发起认证。
composio_execute_tool：按精确 slug 执行 Composio 工具。
composio_remote_workbench：在 Composio 沙箱里运行 Python，需要includeWorkbenchTools: true。
composio_remote_bash：在沙箱文件系统里运行简短 bash 命令，需要includeWorkbenchTools: true（该选项默认关闭）。

这几个助手名可以通过createSessionTools的names选项重命名，常量定义在PI_COMPOSIO_SESSION_TOOL_NAMES上。

用 hooks 拦截每次助手调用

hooks 是 Pi provider 区别于其他 provider 的机制：每个助手调用都经过(ctx, next)形式的中间件。await next()执行默认行为；直接返回一个值会替换模型看到的结果；ctx.deny(reason)拦截调用并返回模型可见的错误。ctx.request可改写，ctx.context只读。

const composioTools = composio.provider.createSessionTools({ sessionId: composioSession.sessionId, search: composioSession.search.bind(composioSession), execute: composioSession.execute.bind(composioSession), hooks: { search: (ctx, next) => { ctx.request.toolkits = ctx.request.toolkits?.map(toolkit => toolkit === 'slack' ? 'slackbot' : toolkit ); return next(); }, execute: async (ctx, next) => { if (ctx.request.toolSlug.startsWith('COMPOSIO_')) { return ctx.deny('Meta tools are blocked.'); } const result = await next(); const file = await saveLargeOutput(result); return file ? { message: `Output saved to ${file}` } : result; }, remoteBash: (ctx, next) => { if (ctx.request.command.includes('rm -rf')) { return ctx.deny('Destructive bash commands are blocked.'); } return next(); }, onAuthLink: async (ctx, next) => { await sendConnectionLinkToUser(ctx.url); return shouldShowLinkToModel(ctx) ? next() : { message: 'Connection link sent out-of-band.' }; }, }, });

可用的 hook 按PiSessionHooks定义，各自包装一个环节：

Hook	包装对象
`search`	工具发现；可改写`query`或`toolkits`
`manageConnections`	连接检查与认证
`execute`	工具执行；可改写`toolSlug`、`args`、`account`
`remoteWorkbench`	远程 Python 助手
`remoteBash`	远程 bash 助手
`onAuthLink`	结果中出现的任意认证链接

每个ctx.request都有完整类型，编辑器能给出精确字段提示。ctx.deny也可以从包入口以denyPiToolCall(reason)的形式导入使用。

验证集成是否生效

文档给出的验证方式就是发起一次真实 prompt：

await piSession.prompt('Find my open GitHub issues and summarize the blockers.');

模型会依次经过composio_search_tools找到工具 slug，再经composio_execute_tool执行。仓库中的单元测试 pi.test.ts 固定了这条路由行为，可作为核对基准：composio_search_tools调用等价于session.search({ query, toolkits })；composio_execute_tool调用等价于session.execute(toolSlug, args, { account })；开启includeWorkbenchTools: true后，composio_remote_workbench会以COMPOSIO_REMOTE_WORKBENCH这个 slug 执行，并自动带上session_id。

另外注意一个来自会话文档的边界：session meta tools 只能在 tool-router 会话内执行，绕过会话直接用tools.execute()执行会报"can only be called inside a tool-router session"。Pi provider 的连接管理走的是session.toolkits()+session.authorize()，内部不会去执行COMPOSIO_MANAGE_CONNECTIONS，所以上面示例里的executehook 才会拦截直接指向该 meta tool 的调用。

限制与后续操作

PiProvider位于实验性包@composio/experimental，接口可能在版本之间变化。
多轮对话中不要重复create：保存 session ID，用composio.use(sessionId)复用同一个会话，工具、认证和沙箱状态都会保留。
会话配置项（toolkits 过滤、connectedAccounts账号选择、sandbox 关闭等）详见 Configuring Sessions；会话模型本身见 What is a session?。
需要更多 hook 字段和类型定义时，可直接查 pi/types.ts。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考