platform-tracing-agentforce-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Platform Tracing — Agentforce Configure

Platform Tracing — Agentforce配置

Generate AgentforcePlatformTracingSettings metadata to enable or disable forwarding of Agentforce agent execution trace spans to Data Cloud's ingestion pipeline. This is a singleton Settings type with one boolean field introduced in API v68.0 (Spring '25).

生成AgentforcePlatformTracingSettings元数据，以启用或禁用将Agentforce代理执行追踪跨度转发至Data Cloud的数据摄入管道。这是API v68.0（Spring '25版本）中新增的单例Settings类型，仅包含一个布尔字段。

Scope

适用范围

In scope: Generating
```
AgentforcePlatformTracing.settings-meta.xml
```
to enable or disable Agentforce agent tracing.
Out of scope: Platform Tracing for TraceSpanEvent (use
```
platform-tracing-configure
```
). Event Log Files. Change Data Capture. Org permission provisioning. Data Cloud provisioning.

包含场景：生成
```
AgentforcePlatformTracing.settings-meta.xml
```
文件以启用或禁用Agentforce代理追踪。
排除场景：为TraceSpanEvent配置Platform Tracing（使用
```
platform-tracing-configure
```
技能）、事件日志文件、变更数据捕获（Change Data Capture）、组织权限配置、Data Cloud配置。

Prerequisites

前置条件

Before generating, inform the user of these requirements. The skill cannot check org state, but deploying without these prerequisites means the setting has no effect:

Data Cloud must be provisioned in the org — trace spans are forwarded to Data Cloud's ingestion pipeline. Without Data Cloud, there is no destination for the spans.
PlatformObservability
org permission must be active — this permission gates the feature. It is provisioned (not settable via metadata).
API version 68.0+ — the
```
AgentforcePlatformTracingSettings
```
type was introduced in Spring '25. Orgs on older API versions will not recognize it.

If the user reports the setting isn't working after deploy, the most likely cause is a missing prerequisite above.

在生成元数据前，需告知用户以下要求。本技能无法检查组织状态，但如果不满足这些前置条件，部署后的设置将无法生效：

组织中必须已配置Data Cloud —— 追踪跨度会转发至Data Cloud的数据摄入管道。若未配置Data Cloud，追踪跨度将没有接收目标。
必须激活
PlatformObservability
组织权限 —— 该权限是此功能的访问门槛，需通过配置获取（无法通过元数据设置）。
API版本需为68.0及以上 ——
```
AgentforcePlatformTracingSettings
```
类型是在Spring '25版本中引入的。使用旧版API的组织无法识别该类型。

如果用户反馈部署后设置未生效，最可能的原因是缺少上述前置条件之一。

Clarifying Questions

确认问题

Before generating, confirm with the user if not already clear:

Enable or disable? (Which state do you want for Agentforce agent tracing?)

No other clarification needed — this is a singleton type with one boolean field.

在生成前，若用户未明确说明，需确认以下内容：

是启用还是禁用？（您希望Agentforce代理追踪处于哪种状态？）

无需其他确认——此为单例类型，仅包含一个布尔字段。

Required Inputs

必填输入

Gather or infer before proceeding:

Desired state:
```
true
```
(enable) or
```
false
```
(disable)

Defaults unless specified:

If user says "enable" or "turn on": set to
```
true
```
If user says "disable" or "turn off": set to
```
false
```

If the user provides a clear request, generate immediately without unnecessary back-and-forth.

在执行前需收集或推断以下信息：

期望状态：
```
true
```
（启用）或
```
false
```
（禁用）

默认规则（除非用户指定）：

若用户说“启用”或“打开”：设置为
```
true
```
若用户说“禁用”或“关闭”：设置为
```
false
```

若用户已明确需求，直接生成即可，无需多余沟通。

Workflow

工作流程

Warn about prerequisites — inform the user that this feature requires Data Cloud and the
```
PlatformObservability
```
org permission.

Read the template — load

assets/AgentforcePlatformTracing-template.xml

Generate the settings file — replace
```
{ENABLED}
```
with
```
true
```
or
```
false
```
based on the user's desired state.
Place the file — output to
```
settings/AgentforcePlatformTracing.settings-meta.xml
```
in the project's source directory.

告知前置条件 —— 提醒用户此功能需要Data Cloud和
```
PlatformObservability
```
组织权限。

加载模板 —— 读取

assets/AgentforcePlatformTracing-template.xml

文件。

生成设置文件 —— 根据用户期望状态，将模板中的
```
{ENABLED}
```
替换为
```
true
```
或
```
false
```
。
放置文件 —— 将生成的文件输出至项目源码目录下的
```
settings/AgentforcePlatformTracing.settings-meta.xml
```
。

Rules / Constraints

规则/约束

Constraint	Rationale
Singleton — only one file per org, one boolean field	The metadata type has exactly one instance. Deploying the file sets the org-wide preference.
XML namespace must be `http://soap.sforce.com/2006/04/metadata`	Any other namespace causes deploy failure.
File must be named `AgentforcePlatformTracing.settings-meta.xml`	SFDX source format convention for this Settings type.
Only include `enableAgentforcePlatformTracing` field	No other fields exist on this type.
Requires API v68.0+	Older orgs reject the metadata type entirely.

约束条件	原因
单例——每个组织仅一个文件，仅一个布尔字段	该元数据类型仅有一个实例。部署此文件将设置组织级别的偏好。
XML命名空间必须为 `http://soap.sforce.com/2006/04/metadata`	使用其他命名空间会导致部署失败。
文件必须命名为 `AgentforcePlatformTracing.settings-meta.xml`	这是SFDX源码格式中此Settings类型的约定命名。
仅包含 `enableAgentforcePlatformTracing` 字段	该类型不存在其他字段。
需要API v68.0及以上版本	旧版组织会直接拒绝该元数据类型。

Gotchas

常见问题

Issue	Resolution
Deploy succeeds but tracing doesn't activate	Org lacks `PlatformObservability` permission or Data Cloud is not provisioned. These are provisioned, not settable via metadata.
`AgentforcePlatformTracingSettings` type not recognized	Org or tooling is on API version < 68.0. Update `sfdx-project.json` sourceApiVersion.
User confuses this with Platform Tracing (TraceSpanEvent)	Clarify: this sends Agentforce agent execution spans to Data Cloud. For TraceSpanEvent publishing, use the `platform-tracing-configure` skill.

问题	解决方案
部署成功但追踪未激活	组织缺少 `PlatformObservability` 权限或未配置Data Cloud。这些需通过配置获取，无法通过元数据设置。
无法识别 `AgentforcePlatformTracingSettings` 类型	组织或工具使用的API版本低于68.0。请更新 `sfdx-project.json` 中的sourceApiVersion。
用户混淆此功能与Platform Tracing（TraceSpanEvent）	明确说明：此功能是将Agentforce代理执行跨度发送至Data Cloud。若需配置TraceSpanEvent发布，请使用 `platform-tracing-configure` 技能。

Output Expectations

输出预期

Deliverables:

settings/AgentforcePlatformTracing.settings-meta.xml

Before delivering, verify:

XML namespace is exactly
```
http://soap.sforce.com/2006/04/metadata
```

File is named

AgentforcePlatformTracing.settings-meta.xml

Only
```
enableAgentforcePlatformTracing
```
is present (no extra fields)

交付物：

settings/AgentforcePlatformTracing.settings-meta.xml

交付前需验证：

XML命名空间完全为
```
http://soap.sforce.com/2006/04/metadata
```

文件命名为

AgentforcePlatformTracing.settings-meta.xml

仅包含
```
enableAgentforcePlatformTracing
```
字段（无额外字段）

Cross-Skill Integration

跨技能集成

Need	Delegate to
Enable TraceSpanEvent publishing (Platform Tracing)	`platform-tracing-configure` skill
Query or analyze existing Agentforce agent trace data in Data Cloud	`agentforce-observe` skill
Set up Change Data Capture	`integration-eventing-cdc-configure` skill
Configure ManagedEventSubscription	`integration-eventing-subscription-configure` skill

需求	委托至
启用TraceSpanEvent发布（Platform Tracing）	`platform-tracing-configure` 技能
查询或分析Data Cloud中已有的Agentforce代理追踪数据	`agentforce-observe` 技能
设置变更数据捕获	`integration-eventing-cdc-configure` 技能
配置ManagedEventSubscription	`integration-eventing-subscription-configure` 技能

Reference File Index

参考文件索引

File	When to read
`assets/AgentforcePlatformTracing-template.xml`	Step 2 — template for generating the settings file

文件	读取时机
`assets/AgentforcePlatformTracing-template.xml`	步骤2——用于生成设置文件的模板