platform-agenticsetup-categories-get

platform-agenticsetup-categories-get

从已连接的 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. 处理错误

错误	含义	操作
成功（退出代码 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	需要了解完整响应结构和字段说明时