platform-agentsetup-categories-fetch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

platform-agentsetup-categories-fetch

Fetch prompt categories from the Agentic Setup Categories Connect API on a connected Salesforce org.

从已连接的Salesforce org上的Agentic Setup Categories Connect API获取提示类别。

Scope

适用范围

In scope:

Calling

GET /services/data/{apiVersion}/agenticsetup/categories

via SF CLI

Passing the
```
fetchPrompts
```
query parameter to include nested prompts
Parsing and presenting the JSON response (categories, labels, prompts)
Handling errors (403 when feature is disabled, auth failures)

Out of scope — delegate elsewhere:

Creating or modifying prompt categories → not supported via this API (read-only)
Org authentication setup → use
```
sf org login
```
separately
Permission set assignment → assigning-permission-set

适用范围：

通过SF CLI调用

GET /services/data/{apiVersion}/agenticsetup/categories

接口

传递
```
fetchPrompts
```
查询参数以包含嵌套提示
解析并展示JSON响应（类别、标签、提示）
处理错误（功能禁用时返回403、认证失败）

不适用范围 — 委托至其他技能：

创建或修改提示类别 → 此API不支持（只读）
组织认证设置 → 单独使用
```
sf org login
```
权限集分配 → 分配权限集技能

Required Inputs

必要输入

The agent needs:

A connected org (already authenticated via
```
sf org login
```
)
Optionally: whether to include nested prompts (
```
fetchPrompts=true
```
)
Optionally: target API version (default: v67.0). Replace
```
v67.0
```
in the URL with the user-specified version if provided.

智能体需要：

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

Workflow

工作流程

1. Verify org connectivity

1. 验证组织连接性

bash

sf org display --json

Confirm the org is authenticated and extract the instance URL. If no default org is set, ask the user which org to target with

--target-org

bash

sf org display --json

确认组织已完成认证并提取实例URL。如果未设置默认组织，询问用户使用

--target-org

指定目标组织。

2. Call the Categories API

2. 调用类别API

Basic call (categories only):

bash

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

With nested prompts:

bash

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

基础调用（仅类别）：

bash

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

包含嵌套提示：

bash

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

3. Parse and present the response

3. 解析并展示响应

The API returns a JSON object with a

categories

array. Each category has

name

label

, and

prompts

fields. See

references/api-response-schema.md

for the full response structure and examples for both

fetchPrompts=true

and

fetchPrompts=false

Present the results clearly:

List categories with their name and label
If
```
fetchPrompts=true
```
was used, show nested prompts under each category
Note any categories with empty
```
prompts
```
arrays (means no prompts exist for that category)

API返回一个包含

categories

数组的JSON对象。每个类别包含

name

、

label

和

prompts

字段。完整的响应结构及

fetchPrompts=true

和

fetchPrompts=false

的示例请查看

references/api-response-schema.md

。

清晰展示结果：

列出每个类别的名称和标签
如果使用了
```
fetchPrompts=true
```
，在每个类别下展示嵌套提示
标注任何
```
prompts
```
数组为空的类别（表示该类别下无提示）

4. Handle errors

4. 错误处理

Error	Meaning	Action
Success (exit 0)	200 OK	Parse and display results
`FUNCTIONALITY_NOT_ENABLED`	Feature not enabled for this org/user	Tell user the Agentic Setup Categories feature needs to be enabled — check Setup > Einstein/Agentforce
`INVALID_SESSION_ID`	Session expired	Re-authenticate with `sf org login`
`NOT_FOUND`	Endpoint not found	API version too old or feature not deployed to this org

错误	含义	操作
成功（退出码0）	200 OK	解析并展示结果
`FUNCTIONALITY_NOT_ENABLED`	该组织/用户未启用此功能	告知用户需要启用Agentic Setup Categories功能——检查Setup > Einstein/Agentforce
`INVALID_SESSION_ID`	会话已过期	使用 `sf org login` 重新认证
`NOT_FOUND`	端点未找到	API版本过旧或该组织未部署此功能

Rules / Constraints

规则/约束

Rule	Rationale
Always use `sf api request rest` — never curl or raw HTTP	curl bypasses `~/.sfdx` session tokens and requires manual Authorization headers, making it brittle
NEVER use SOQL queries	Categories are NOT in standard objects — only available via this Connect REST API
NEVER generate files (LWC, Apex, XML)	This is a data-fetching task, not a code generation task
Default to v67.0 unless user specifies	This is the min-version where the endpoint was introduced
Don't pass fetchPrompts unless asked	Reduces payload size; prompts can be large
Categories are sorted by label	The API returns them alphabetically — don't re-sort
Prompts are sorted by text	Within each category, prompts come alphabetically

规则	理由
始终使用 `sf api request rest` — 绝不使用curl或原生HTTP	curl会绕过 `~/.sfdx` 会话令牌，需要手动添加Authorization头，稳定性差
绝不使用SOQL查询	类别不属于标准对象 — 仅可通过此Connect REST API获取
绝不生成文件（LWC、Apex、XML）	这是数据提取任务，而非代码生成任务
除非用户指定，否则默认使用v67.0	这是该端点引入的最低版本
除非用户要求，否则不传递fetchPrompts参数	减少负载大小；提示内容可能较大
类别按标签排序	API返回结果已按字母顺序排列 — 请勿重新排序
提示按文本排序	在每个类别内，提示按字母顺序返回

Output Expectations

输出预期

When finishing, present:

Number of categories returned
Category list — name and label for each
Prompts (if requested) — nested under their category
Any errors encountered with suggested fixes

完成任务后，展示：

返回的类别数量
类别列表 — 每个类别的名称和标签
提示内容（如果用户要求） — 嵌套在对应类别下
遇到的错误及建议修复方案

Reference File Index

参考文件索引

File	When to read
`references/api-response-schema.md`	When you need to understand the full response structure and field descriptions

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