platform-agenticsetup-categories-get

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

platform-agenticsetup-categories-get

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

从已连接的 Salesforce 组织中获取 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
```
单独处理
权限集分配 → 参考 assigning-permission-set 技能

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.

Agent 需要：

一个已连接的组织（已通过
```
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. 调用 Categories 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`	当需要理解完整响应结构和字段描述时