Composio 平台分页指南端点级限制与 cursor 分页的完整实践【免费下载链接】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本指南以 Composio 平台的官方分页文档为核心讲解其“分页上限随端点而定”的设计原则并以 auth configs 列表接口GET /api/v3/auth_configs与GET /api/v3.1/auth_configs为实例深入说明如何通过next_cursor驱动的 cursor 分页完整遍历数据。读完本文你将掌握 Composio 各资源列表的正确分页姿势、SDK 内置的分页工具用法以及如何规避文档描述与实际部署行为不一致的坑。核心原则分页限制是端点特定的Composio 平台不存在一个全局统一的 page-size 上限。资源列表、目录、Tool Router、日志、计费billing等不同类别的端点可以各自定义不同的单页大小而 toolkit 的 actions 还会额外继承 provider第三方服务商特定的分页规则。因此在接入任何列表接口之前正确做法是先检查该端点的精确 schema字段定义、是否携带cursor/limit参数再通过真实请求验证线上行为实际返回多少条、next_cursor何时为空最后才在代码里固化分页假设——不要凭经验假设“所有接口都是每页 100 条”或“所有接口都支持同样的 limit”。这条原则在 SDK 源码中同样有体现Composio 的 TypeScript SDK 在 ts/packages/core/src/utils/pagination.ts 中封装了统一的getAllPages工具它内部固定以limit: 100发起请求MAX_LIMIT_ALLOWED_BY_API 100并通过next_cursor不断翻页直到取完。也就是说客户端默认请求 100 条但服务端端点仍可能按自己的上限钳制返回数量——这正是“端点特定限制”在客户端与服务端两侧的完整表现。auth configs 列表每页最多 50 条文档明确给出了当前2026-07-16 时间戳标注的公开指南实测限制GET /api/v3/auth_configs每页最多返回 50 个auth configsGET /api/v3.1/auth_configs同样最多返回 50 个。对应中文文档docs/kb/source/platform/pagination/public.md平台分页总览见 docs/api-overviews/auth-configs.mdx。必须完成的翻页循环拿到每一页响应后需要从响应中读取next_cursor字段将其作为下一次请求的cursor查询参数传入重复以上两步直到next_cursor为空null/undefined/ 空字符串为止。伪代码形态如下cursor null loop: response GET /api/v3/auth_configs?cursorcursor process(response.items) if response.next_cursor is empty: break cursor response.next_cursor文档/运行时不一致不要跳过 cursor 分页部分由 schema 自动生成的接口描述文档可能宣称 auth_configs 接口支持更大的单页限制例如 100 甚至更多。但已部署的端点仍会把每一页钳制到 50 条。文档给出的处理建议是把这种“文档宣传值 运行时实际值”的偏差视为产品问题product issue在集成侧则把它当作一个明确信号——绝不能因为文档写着更大的 limit 就跳过 cursor 分页。正确姿势永远是信任next_cursor逐页拉取直到游标耗尽。从源码理解 cursor 分页的完整链路TypeScript SDKgetAllPages的类型安全翻页工具Composio 的 TypeScript SDK 在 ts/packages/core/src/utils/pagination.ts 提供了开箱即用的全量拉取工具getAllPagesexport async function getAllPagesTFn extends ( params: PaginationParams ) Promise{ items: Arrayunknown; next_cursor?: string | null }, (fetchFn: TFn): PromiseArrayExtractItemTypeAwaitedReturnTypeTFn { const allItems []; let cursor: string | null | undefined undefined; const MAX_LIMIT_ALLOWED_BY_API 100; while (true) { const params { ...(cursor ! undefined { cursor }), limit: MAX_LIMIT_ALLOWED_BY_API, }; const response await fetchFn(params); allItems.push(...response.items); if (!response.next_cursor) break; // 游标为空即停止 cursor response.next_cursor; } return allItems; }它的关键行为与单元测试一一对应首次请求不携带cursor只带limit: 100测试should not include cursor in first request后续请求携带cursor值为上一页的next_cursor测试should include cursor in subsequent requestsnext_cursor为null或undefined均视为翻页结束should stop pagination when next_cursor is null等用例支持空items但仍有游标、游标含特殊字符、超长游标、多页合并后保持元素顺序等边界场景请求抛错时异常会向上传播由调用方处理重试与错误should handle async fetch function errors。典型用法来自该文件注释中的示例import { getAllPages } from ./utils/pagination; // 拉取全部工具列表类型自动推断 const allTools await getAllPages((params) client.tools.list({ ...params, tool_slugs: tool1,tool2, }) );值得注意getAllPages请求limit: 100但 auth_configs 端点实际返回 50 条——这一组合正好印证了文档反复强调的“端点限制优先于客户端请求值”SDK 靠游标机制保证了无论服务端返回多少条都不会丢数据。响应字段的蛇形/驼峰转换auth configs 列表响应的原始字段是蛇形命名snake_caseSDK 在 ts/packages/core/src/utils/transformers/authConfigs.ts 中将其转换为 SDK 风格export function transformAuthConfigListResponse(response) { return { items: response.items.map(transformAuthConfigRetrieveResponse), nextCursor: response.next_cursor ?? null, // next_cursor - nextCursor totalPages: response.total_pages, }; }也就是说直接调用 HTTP API 时你看到的是next_cursor/total_pages而通过 TypeScript SDK 的高层接口使用时字段名会变成nextCursor/totalPages。理解这一层转换能避免在“读 SDK 文档”与“读 OpenAPI 文档”之间切换时产生困惑。Python SDK透传cursor查询参数Python SDK 侧auth configs 的列表操作定义在 python/composio/core/models/auth_configs.pyclass AuthConfigs(Resource): def list(self, **query: te.Unpack[auth_config_list_params.AuthConfigListParams]): Lists authentication configurations based on provided filter criteria. return self._client.auth_configs.list(**query)list()将cursor、limit等查询参数原样透传给底层 HTTP 客户端因此分页循环在 Python 中同样遵循“把上一页next_cursor作为下一页cursor”的通用模式from composio import Composio client Composio() cursor None all_configs [] while True: response client.auth_configs.list(cursorcursor, limit50) all_configs.extend(response.items) if not response.next_cursor: break cursor response.next_cursor同样的 cursor 模式也贯穿其他资源例如 Tool Router 的会话文件列表在 python/composio/core/models/tool_router_session_files.py 中接收cursor参数并返回FileListResponse含items与next_cursorTool Router 会话列表在 python/composio/core/models/tool_router_session.py 中同样基于next_cursor做多页拼装。实战检查清单无论使用 REST 直连还是 SDK接入任意 Composio 列表接口时建议按以下清单核对确认端点上限查阅该端点的 schema 或实际发一次请求记录真实单页条数如 auth_configs 为 50携带游标翻页每一页都读取next_cursorSDK 侧为nextCursor非空则作为cursor继续请求直到游标为空不要硬编码信任文档数字若文档声称的 limit 大于实际返回条数以运行时行为为准并把偏差反馈为产品问题边界场景自测空列表、单页即止、恰好一页满、多页数据、游标特殊字符等情况均可参考 ts/packages/core/test/utils/pagination.test.ts 中的用例设计自己的测试优先复用 SDK 工具TypeScript 侧可直接使用getAllPages完成全量拉取避免手写循环遗漏终止条件。小结Composio 的分页设计围绕“端点特定限制 cursor 游标翻页”展开没有全局 page-sizeauth configs 列表实测每页 50 条Tool Router、日志、计费等其他端点则各有各的规则。无论文档如何描述正确的集成方式始终是信任next_cursor并完整翻页——这一点既有官方文档背书docs/kb/source/platform/pagination/public.md也有 SDK 源码与测试用例的完整实现佐证是构建可靠、不丢数据的 Agent 集成的基础能力。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Composio 平台分页指南：端点级限制与 cursor 分页的完整实践
Composio 平台分页指南端点级限制与 cursor 分页的完整实践【免费下载链接】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本指南以 Composio 平台的官方分页文档为核心讲解其“分页上限随端点而定”的设计原则并以 auth configs 列表接口GET /api/v3/auth_configs与GET /api/v3.1/auth_configs为实例深入说明如何通过next_cursor驱动的 cursor 分页完整遍历数据。读完本文你将掌握 Composio 各资源列表的正确分页姿势、SDK 内置的分页工具用法以及如何规避文档描述与实际部署行为不一致的坑。核心原则分页限制是端点特定的Composio 平台不存在一个全局统一的 page-size 上限。资源列表、目录、Tool Router、日志、计费billing等不同类别的端点可以各自定义不同的单页大小而 toolkit 的 actions 还会额外继承 provider第三方服务商特定的分页规则。因此在接入任何列表接口之前正确做法是先检查该端点的精确 schema字段定义、是否携带cursor/limit参数再通过真实请求验证线上行为实际返回多少条、next_cursor何时为空最后才在代码里固化分页假设——不要凭经验假设“所有接口都是每页 100 条”或“所有接口都支持同样的 limit”。这条原则在 SDK 源码中同样有体现Composio 的 TypeScript SDK 在 ts/packages/core/src/utils/pagination.ts 中封装了统一的getAllPages工具它内部固定以limit: 100发起请求MAX_LIMIT_ALLOWED_BY_API 100并通过next_cursor不断翻页直到取完。也就是说客户端默认请求 100 条但服务端端点仍可能按自己的上限钳制返回数量——这正是“端点特定限制”在客户端与服务端两侧的完整表现。auth configs 列表每页最多 50 条文档明确给出了当前2026-07-16 时间戳标注的公开指南实测限制GET /api/v3/auth_configs每页最多返回 50 个auth configsGET /api/v3.1/auth_configs同样最多返回 50 个。对应中文文档docs/kb/source/platform/pagination/public.md平台分页总览见 docs/api-overviews/auth-configs.mdx。必须完成的翻页循环拿到每一页响应后需要从响应中读取next_cursor字段将其作为下一次请求的cursor查询参数传入重复以上两步直到next_cursor为空null/undefined/ 空字符串为止。伪代码形态如下cursor null loop: response GET /api/v3/auth_configs?cursorcursor process(response.items) if response.next_cursor is empty: break cursor response.next_cursor文档/运行时不一致不要跳过 cursor 分页部分由 schema 自动生成的接口描述文档可能宣称 auth_configs 接口支持更大的单页限制例如 100 甚至更多。但已部署的端点仍会把每一页钳制到 50 条。文档给出的处理建议是把这种“文档宣传值 运行时实际值”的偏差视为产品问题product issue在集成侧则把它当作一个明确信号——绝不能因为文档写着更大的 limit 就跳过 cursor 分页。正确姿势永远是信任next_cursor逐页拉取直到游标耗尽。从源码理解 cursor 分页的完整链路TypeScript SDKgetAllPages的类型安全翻页工具Composio 的 TypeScript SDK 在 ts/packages/core/src/utils/pagination.ts 提供了开箱即用的全量拉取工具getAllPagesexport async function getAllPagesTFn extends ( params: PaginationParams ) Promise{ items: Arrayunknown; next_cursor?: string | null }, (fetchFn: TFn): PromiseArrayExtractItemTypeAwaitedReturnTypeTFn { const allItems []; let cursor: string | null | undefined undefined; const MAX_LIMIT_ALLOWED_BY_API 100; while (true) { const params { ...(cursor ! undefined { cursor }), limit: MAX_LIMIT_ALLOWED_BY_API, }; const response await fetchFn(params); allItems.push(...response.items); if (!response.next_cursor) break; // 游标为空即停止 cursor response.next_cursor; } return allItems; }它的关键行为与单元测试一一对应首次请求不携带cursor只带limit: 100测试should not include cursor in first request后续请求携带cursor值为上一页的next_cursor测试should include cursor in subsequent requestsnext_cursor为null或undefined均视为翻页结束should stop pagination when next_cursor is null等用例支持空items但仍有游标、游标含特殊字符、超长游标、多页合并后保持元素顺序等边界场景请求抛错时异常会向上传播由调用方处理重试与错误should handle async fetch function errors。典型用法来自该文件注释中的示例import { getAllPages } from ./utils/pagination; // 拉取全部工具列表类型自动推断 const allTools await getAllPages((params) client.tools.list({ ...params, tool_slugs: tool1,tool2, }) );值得注意getAllPages请求limit: 100但 auth_configs 端点实际返回 50 条——这一组合正好印证了文档反复强调的“端点限制优先于客户端请求值”SDK 靠游标机制保证了无论服务端返回多少条都不会丢数据。响应字段的蛇形/驼峰转换auth configs 列表响应的原始字段是蛇形命名snake_caseSDK 在 ts/packages/core/src/utils/transformers/authConfigs.ts 中将其转换为 SDK 风格export function transformAuthConfigListResponse(response) { return { items: response.items.map(transformAuthConfigRetrieveResponse), nextCursor: response.next_cursor ?? null, // next_cursor - nextCursor totalPages: response.total_pages, }; }也就是说直接调用 HTTP API 时你看到的是next_cursor/total_pages而通过 TypeScript SDK 的高层接口使用时字段名会变成nextCursor/totalPages。理解这一层转换能避免在“读 SDK 文档”与“读 OpenAPI 文档”之间切换时产生困惑。Python SDK透传cursor查询参数Python SDK 侧auth configs 的列表操作定义在 python/composio/core/models/auth_configs.pyclass AuthConfigs(Resource): def list(self, **query: te.Unpack[auth_config_list_params.AuthConfigListParams]): Lists authentication configurations based on provided filter criteria. return self._client.auth_configs.list(**query)list()将cursor、limit等查询参数原样透传给底层 HTTP 客户端因此分页循环在 Python 中同样遵循“把上一页next_cursor作为下一页cursor”的通用模式from composio import Composio client Composio() cursor None all_configs [] while True: response client.auth_configs.list(cursorcursor, limit50) all_configs.extend(response.items) if not response.next_cursor: break cursor response.next_cursor同样的 cursor 模式也贯穿其他资源例如 Tool Router 的会话文件列表在 python/composio/core/models/tool_router_session_files.py 中接收cursor参数并返回FileListResponse含items与next_cursorTool Router 会话列表在 python/composio/core/models/tool_router_session.py 中同样基于next_cursor做多页拼装。实战检查清单无论使用 REST 直连还是 SDK接入任意 Composio 列表接口时建议按以下清单核对确认端点上限查阅该端点的 schema 或实际发一次请求记录真实单页条数如 auth_configs 为 50携带游标翻页每一页都读取next_cursorSDK 侧为nextCursor非空则作为cursor继续请求直到游标为空不要硬编码信任文档数字若文档声称的 limit 大于实际返回条数以运行时行为为准并把偏差反馈为产品问题边界场景自测空列表、单页即止、恰好一页满、多页数据、游标特殊字符等情况均可参考 ts/packages/core/test/utils/pagination.test.ts 中的用例设计自己的测试优先复用 SDK 工具TypeScript 侧可直接使用getAllPages完成全量拉取避免手写循环遗漏终止条件。小结Composio 的分页设计围绕“端点特定限制 cursor 游标翻页”展开没有全局 page-sizeauth configs 列表实测每页 50 条Tool Router、日志、计费等其他端点则各有各的规则。无论文档如何描述正确的集成方式始终是信任next_cursor并完整翻页——这一点既有官方文档背书docs/kb/source/platform/pagination/public.md也有 SDK 源码与测试用例的完整实现佐证是构建可靠、不丢数据的 Agent 集成的基础能力。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考