如何在 Composio 会话中用 session.authorize() 生成 Connect Link 并完成聊天外的预授权-开发者社区

如何在 Composio 会话中用 session.authorize() 生成 Connect Link 并完成聊天外的预授权

【免费下载链接】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

如果你的 Agent 用户在开始聊天前就应该完成账号授权——例如 onboarding 流程、设置页连接管理，或在任务执行前做连接预检——Composio 提供了session.authorize()方法：它在会话上按需生成一条 Connect Link（托管授权页 URL），你负责把该链接引导给用户，授权完成后再校验连接状态。本文基于仓库中的 Manual auth management 文档和相关 SDK 参考，给出从创建会话到验证连接的完整操作路径，适用于 Python 与 TypeScript 两种 SDK。

前置条件：

已安装 Composio SDK，并拥有 Composio API key（Python 中通过Composio(api_key=...)传入，TypeScript 中通过new Composio({ apiKey: ... })传入）；
一个稳定的user_id：Authentication 文档要求使用数据库主键或 UUID 这类不会变化的标识，避免使用邮箱，生产环境禁止使用default；
要预授权的 toolkit slug，例如gmail、github。

创建会话并生成 Connect Link

在会话上调用session.authorize("<toolkit_slug>")，返回一个 connection request 对象，其中的redirect_url（Python）/redirectUrl（TypeScript）就是 Connect Link。

session = composio.create(user_id="user_123") connection_request = session.authorize("gmail") print(connection_request.redirect_url) # https://connect.composio.dev/link/ln_abc123

import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123"); const connectionRequest = await session.authorize("gmail"); console.log(connectionRequest.redirectUrl); // https://connect.composio.dev/link/ln_abc123

上例输出中的ln_abc123为文档示例，实际链接每次生成时不同。把这个 URL 交给用户——可以渲染在你自己的连接 UI 里、发邮件或在设置页展示——用户打开后在 Composio 托管页面上完成登录，凭据不经过你的应用或模型。

等待授权完成：wait_for_connection

拿到 redirect URL 后，用同一个 connection request 对象等待用户完成授权：

connected_account = connection_request.wait_for_connection(60000) print(f"Connected: {connected_account.id}")

const connectedAccount = await connectionRequest.waitForConnection(60000); console.log(`Connected: ${connectedAccount.id}`);

该方法会持续轮询 Composio API，直到连接进入ACTIVE状态（返回 connected account）、进入FAILED或EXPIRED等终态（抛出错误），或超过超时时间（抛出超时错误）。文档说明默认超时为 60 秒，上面的代码块展示了显式传入参数等待的用法。

控制授权完成后的回跳地址

默认情况下用户授权后停留在 Composio 页面。如果要把用户带回你的应用，在authorize()传入callback_url/callbackUrl，并可以自带 query 参数携带上下文：

connection_request = session.authorize( "gmail", callback_url="https://your-app.com/callback?user_id=user_123&source=onboarding" )

const connectionRequest = await session.authorize("gmail", { callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding", });

授权完成后，Composio 会保留你已有的参数，并追加两个参数再重定向到该地址：

Parameter	Description
`status`	`success`或`failed`
`connected_account_id`	新创建的 connected account 的 ID

文档示例（示例结果，实际值不同）：

https://your-app.com/callback?user_id=user_123&source=onboarding&status=success&connected_account_id=ca_abc123

在你的回调页读取status与connected_account_id，即可区分授权成功或失败，并把 account ID 记录到自己的数据库中。

验证连接状态

除了等待方法本身的返回值，还可以用session.toolkits()查看会话内所有 toolkit 及其连接状态，作为预授权流程的核对手段：

toolkits = session.toolkits() for toolkit in toolkits.items: status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected" print(f"{toolkit.name}: {status}")

const toolkits = await session.toolkits(); toolkits.items.forEach((toolkit) => { console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`); });

输出中能看到对应 toolkit 的 connected account ID 说明已连接，否则显示Not connected。注意只有ACTIVE状态的连接可用于执行工具；如果连接停留在INITIATED，说明用户打开了 Connect Link 但没有完成授权——此时需要重新引导用户访问该链接完成认证。

关闭聊天内授权提示，把授权完全交给自己的 UI

会话默认包含COMPOSIO_MANAGE_CONNECTIONSmeta-tool，会在聊天中提示用户授权。既然你要做聊天外的预授权，应把它关掉，避免两套授权入口并存：

session = composio.create( user_id="user_123", manage_connections=False, )

const session = await composio.create("user_123", { manageConnections: false, });

完整流程：预检必备 toolkit 再启动 Agent

文档给出的典型模式是：在启动 Agent 前检查所有必需连接，缺哪个补授权哪个。以下代码块来自文档，your-api-key与user_123需替换为你自己的 API key 和用户标识：

from composio import Composio composio = Composio(api_key="your-api-key") required_toolkits = ["gmail", "github"] session = composio.create( user_id="user_123", manage_connections=False, # Disable in-chat auth prompts ) toolkits = session.toolkits() connected = {t.slug for t in toolkits.items if t.connection.is_active} pending = [slug for slug in required_toolkits if slug not in connected] print(f"Connected: {connected}") print(f"Pending: {pending}") for slug in pending: connection_request = session.authorize(slug) print(f"Connect {slug}: {connection_request.redirect_url}") connection_request.wait_for_connection() print("All toolkits connected!")

import { Composio } from "@composio/core"; const composio = new Composio({ apiKey: "your-api-key" }); const requiredToolkits = ["gmail", "github"]; const session = await composio.create("user_123", { manageConnections: false, // Disable in-chat auth prompts }); const toolkits = await session.toolkits(); const connected = toolkits.items .filter((t) => t.connection?.connectedAccount) .map((t) => t.slug); const pending = requiredToolkits.filter((slug) => !connected.includes(slug)); console.log("Connected:", connected); console.log("Pending:", pending); for (const slug of pending) { const connectionRequest = await session.authorize(slug); console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`); await connectionRequest.waitForConnection(); } console.log("All toolkits connected!");

TypeScript 版本中connected的判定基于connection?.connectedAccount是否存在，而 Python 版本基于is_active，两者语义略有差异；以你实际使用的 SDK 为准。

边界与已知状态

用户关闭 Connect Link 未完成授权时，连接保持在INITIATED状态直到过期；Authenticating Tools 文档说明INITIATED状态的连接会在 10 分钟后自动过期，之后需要重新生成 Connect Link。
wait_for_connection抛出错误时对应连接进入终态（如FAILED）或超时；FAILED的常见原因包括用户在 OAuth 中拒绝授权、授权码无效或 auth config 配置错误，可检查status_reason字段后重试。
若某个 toolkit 的授权流程需要额外参数（如 Zendesk 的subdomain），session.authorize()之外的直接 SDK 路径composio.connected_accounts.link()/composio.connectedAccounts.link()支持传入更完整的 auth 配置，参见 Authenticating Tools。
仓库中还有一个更精简的官方示例：Python 版 authorize.py（创建限定github、gmail的会话后调用session.authorize("github")并等待连接，成功打印 Connected Account ID 与 Status，失败打印错误）和 TypeScript 版 authorize.ts。