kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-09 00:42:46 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge 4848ecc844 into fbf1c040c9

Browse Source
This commit is contained in:
james-enperso 2026-08-07 15:39:58 -04:00 committed by GitHub
commit 39c8ccf0f8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 66 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
skills/agentforce-generate/references/agent-validation-and-debugging.md
View File

@ -421,6 +421,29 @@ For each turn, verify in the trace:
4. **Action outputs used correctly** — Compare `FunctionStep` outputs to the agent's final response. The agent should be using real data from the action, not inventing values.
5. **Persisted state (live preview)** — For actions that write data (create records, update fields), query the backing SObject directly to confirm the write happened. This is ground truth. If no record exists, the action was not invoked regardless of what the trace or chat says — investigate the router first.
> **Traces are only written on the authoring-bundle preview path.** A preview started with
> `--api-name` (the published/activated agent) writes trace files containing exactly `{}` — no
> `plan` array, no `FunctionStep`. Verified on API v67.0 with `sf` CLI 2.145.6. Only
> `sf agent preview start --authoring-bundle <Name>` produces readable traces.
>
> This matters because the two are not always interchangeable: a **service** agent cannot always be
> previewed via `--authoring-bundle` (that path can be unreachable on restricted networks), which
> leaves `--api-name` as the only option — and it yields no trace. In that situation the
> "read the trace after every utterance" rule above cannot be satisfied, so substitute
> **discriminating-value testing**:
>
> - Query ground truth first, then ask the agent about records whose values an LLM could not guess.
> A response matching an arbitrary figure like `$48,077.20` exactly is strong evidence the action
> ran.
> - Better still, target a record that exercises a **distinctive code path** in the action
> implementation. Example: an invocable that falls back to `Date.today().year()` when a record has
> no transactions — if the agent reports that fallback year for such a record, the Apex
> demonstrably executed.
> - Cross-check writes by querying the SObject directly, per item 5 above.
>
> Record which method you used. "Verified by trace" and "verified by discriminating value" are
> different strengths of evidence and should not be reported interchangeably.
### Behavioral Evaluation
Evaluate the agent's behavior like a human would — does this feel like a natural, competent conversation?
@ -453,6 +476,23 @@ Replace `<AGENT_NAME>` with your authoring bundle name (e.g., `Local_Info_Agent`
Traces are available immediately after each `send` — you do NOT need to end the session to read them.
The **published-agent** preview path (`--api-name`) uses a different layout, keyed by **Bot ID**
rather than agent name, and its `traces/*.json` files are empty (`{}`):
```text
.sfdx/agents/<BOT_ID>/sessions/<SESSION_ID>/
├── metadata.json
├── session-meta.json
├── transcript.jsonl # populated — the conversation is still readable
├── turn-index.json
└── traces/
└── <PLAN_ID>.json # written, but contains only {}
```
`transcript.jsonl` is still usable there, so you can review the conversation — you just cannot
confirm `FunctionStep` execution. Use the discriminating-value technique described under
[Trace Evaluation](#trace-evaluation) instead.
### File Structure
**metadata.json** contains session-level information: `sessionId`, `agentId`, `startTime`, and `mockMode` (either `"Mock"` for simulated or `"Live Test"` for live).

26
skills/agentforce-generate/references/complex-data-types.md
View File

@ -15,6 +15,32 @@
> **Key insight:** Bare `number` works in **variable declarations** but **fails at publish** in action inputs/outputs. This is the #1 cause of publish-fix-republish cycles.
> **`sf agent validate` does NOT catch this.** `sf agent validate authoring-bundle` returns
> `success: true` for an action param with the wrong numeric type — the check only runs server-side
> during `sf agent publish`. Do not treat a green validate as evidence your action I/O types are
> correct. When publish rejects the type it returns a **400** whose message names the exact fix,
> e.g.:
>
> ```text
> Validation failed for action 'calculate_interest_paid' due to invalid data type for the input
> parameter 'fiscalYear'. To fix, update the data type to 'object' type and 'complex_data_type_name'
> to 'lightning__integerType' for the input parameter 'fiscalYear'.
> ```
>
> Read that message rather than guessing — it is authoritative for the target you are wiring.
> **Apex `Integer` and Apex `Decimal` behave differently.** Verified against API v67.0 with
> `sf` CLI 2.145.6:
> - Apex **`Integer`** param (input *or* output) as bare `number` → publish **fails** with the 400
> above. Must be `object` + `lightning__integerType`.
> - Apex **`Decimal`** output as bare `number` → publish **succeeds**. Two separate agents wired to
> `apex://` invocables returning `Decimal` published with bare `number` outputs and returned
> correct values at runtime.
>
> So for `apex://` targets, reach for the complex type when the Apex field is an `Integer`. If you
> hit a publish 400 on a `Decimal`, follow the message — but a bare `number` is not automatically
> wrong there.
> **CRITICAL: Target type matters!** The valid `complex_data_type_name` for integer values differs by target type:
> - **Flow targets** (`flow://`): Use `lightning__numberType` (NOT `lightning__integerType`)
> - **Apex targets** (`apex://`): Use `lightning__integerType` (NOT `lightning__numberType`)