platform-agentsetup-categories-fetch

platform-agentsetup-categories-fetch

从已连接的 Salesforce 组织获取 Agentic Setup Categories Connect API 的提示词类别。

范围

范围内：

• 通过 SF CLI 调用 GET /services/data/{apiVersion}/agenticsetup/categories
• 传递 fetchPrompts 查询参数以包含嵌套提示词
• 解析并展示 JSON 响应（类别、标签、提示词）
• 处理错误（功能已禁用时的 403、身份验证失败）

范围外 — 委派给其他工具：

• 创建或修改提示词类别 → 此 API 不支持（只读）
• 组织身份验证设置 → 单独使用 sf org login
• 权限集分配 → assigning-permission-set

---

必需输入

Agent 需要：

• 一个已连接的组织（已通过 sf org login 完成身份验证）
• 可选：是否包含嵌套提示词（fetchPrompts=true）
• 可选：目标 API 版本（默认：v67.0）。如果用户指定了版本，请在 URL 中将 v67.0 替换为该版本。

---

工作流

1. 验证组织连接

sf org display --json

确认组织已通过身份验证并提取实例 URL。如果未设置默认组织，请询问用户要通过 --target-org 指定哪个组织。

2. 调用 Categories API

基本调用（仅类别）：

sf api request rest /services/data/v67.0/agenticsetup/categories --method GET

包含嵌套提示词：

sf api request rest "/services/data/v67.0/agenticsetup/categories?fetchPrompts=true" --method GET

3. 解析并展示响应

API 返回一个包含 categories 数组的 JSON 对象。每个类别都有 name、label 和 prompts 字段。完整的响应结构，以及 fetchPrompts=true 和 fetchPrompts=false 时的示例，请参阅 references/api-response-schema.md。

清晰地展示结果：

• 列出类别及其名称和标签
• 如果使用了 fetchPrompts=true，则在每个类别下显示嵌套提示词
• 指出 prompts 数组为空的类别（表示该类别下没有提示词）

4. 处理错误

错误	含义	操作
Success (exit 0)	200 OK	解析并显示结果
FUNCTIONALITY_NOT_ENABLED	此组织/用户未启用该功能	告知用户需要启用 Agentic Setup Categories 功能 — 检查 Setup > Einstein/Agentforce
INVALID_SESSION_ID	会话已过期	使用 sf org login 重新进行身份验证
NOT_FOUND	未找到端点	API 版本过旧，或此组织尚未部署该功能

---

规则 / 约束

规则	原因
始终使用 sf api request rest — 绝不要使用 curl 或原始 HTTP	curl 会绕过 ~/.sfdx 会话令牌，并要求手动设置 Authorization 标头，因此不可靠
绝不要使用 SOQL 查询	类别不属于标准对象 — 只能通过此 Connect REST API 获取
绝不要生成文件（LWC、Apex、XML）	这是数据获取任务，而非代码生成任务
除非用户另有指定，否则默认使用 v67.0	这是引入该端点的最低版本
除非用户提出要求，否则不要传递 fetchPrompts	可减小负载；提示词可能很长
类别按标签排序	API 会按字母顺序返回 — 不要重新排序
提示词按文本排序	每个类别中的提示词都按字母顺序排列

---

输出要求

完成时，请展示：

1. 返回的类别数量
2. 类别列表 — 每个类别的名称和标签
3. 提示词（如果用户要求）— 按类别嵌套展示
4. 遇到的任何错误及建议的修复方法

---

参考文件索引

文件	何时阅读
references/api-response-schema.md	需要了解完整响应结构和字段说明时