Phase 3 edits the `.agent` file directly using the Edit tool. No intermediate markdown conversion step. After editing, validate and publish the authoring bundle.
---
## Pre-Flight: Verify Action Target Availability
Before making any `.agent` file edits, verify that all action targets actually exist and are registered in the org.
**Step 1 -- Extract all action targets from the `.agent` file:**
**Step 2 -- Query GenAiFunction records in the org:**
```bash
sf data query --json -q "SELECT DeveloperName, MasterLabel, InvocableActionDeveloperName FROM GenAiFunction WHERE IsActive = true" -o <ORG_ALIAS>
```
**Step 3 -- Compare and flag missing targets:**
```bash
# For flow:// targets
sf flow list -o <ORG_ALIAS> --json | python3 -c "import json,sys; flows=[f['ApiName'] for f in json.load(sys.stdin)['result']]; print('\n'.join(flows))"
# For apex:// targets
sf data query --json -q "SELECT Name FROM ApexClass WHERE Name IN ('ClassName1','ClassName2')" -o <ORG_ALIAS>
```
**Step 4 -- Present options to user if targets are missing:**
1.**Deploy missing targets first** -- Use `Section 17 of /developing-agentforce` to generate stubs, then `Section 18 of /developing-agentforce` to deploy
2.**Remove unresolvable actions** -- Delete from `.agent` file and focus on routing/instruction improvements
3.**Register via Agent Builder UI** -- For targets that exist but aren't registered as `GenAiFunction`
4.**Proceed anyway** -- If the planned fix only touches routing logic or instructions
**Guideline:** If 50%+ of action targets are missing or unregistered, pivoting to routing and instruction fixes is usually the most pragmatic path.
**WARNING:** Do NOT use `flow://` syntax directly in `.agent` file action `target:` URIs as a workaround -- the Agent Script lexer does not support URI prefixes in target fields.
---
## .agent File Structure
The `.agent` file uses Agent Script -- a tab-indented DSL that compiles to Agentforce metadata:
```
system:
instructions: "Agent-level system prompt (persona, guardrails)"
| `Agent Configuration Gap` | Action not called | `topic <name>: reasoning: actions:` and `reasoning: instructions:` | Add action definition under `actions:` and mention it in `instructions:` |
| Yes | No | Deploy/register: use `Section 18 of /developing-agentforce` or register via Agent Builder UI |
| No | N/A | Scaffold first: use `Section 17 of /developing-agentforce` to generate stub, then deploy |
| Can't deploy now | N/A | Pivot to routing fixes: remove action from `.agent`, focus on instructions and transitions |
---
## Principles for Effective Topic Instructions
Good instructions are specific, imperative, and action-named. Poor instructions are persona descriptions or generic guidance reused across topics.
1.**Name the action explicitly** -- "Use `@actions.schedule_test_drive` to book the appointment" not "help the user book"
2.**State the pre-condition** -- "Only handle scheduling after the customer's name and email have been collected"
3.**State what to do after** -- "After scheduling completes, confirm the date/time and transition to follow_up"
4.**Scope tightly** -- "This topic handles test drive scheduling only. For vehicle specs or pricing, do not answer -- the user should be routed to general_support"
5.**Keep persona out of instructions** -- persona belongs in `system: instructions:` (agent-level), not per-topic reasoning instructions
6.**One responsibility per topic** -- if the instruction covers 3 distinct tasks, split into 3 topics
**Before / after example** (identical instructions -> distinct instructions):
*Before (generic persona text, same across all topics):*
```
reasoning:
instructions: |
You are Nova, a friendly Tesla support assistant. Greet customers warmly,
help them with their needs, and guide them toward scheduling a test drive.
description: "Move to test drive scheduling after info collected"
available when @variables.customer_name != ""
```
---
## Regression Prevention
When editing topic instructions, follow these principles:
1.**Establish a baseline BEFORE editing** -- Run the test utterance 3 times before making changes. Record the pass rate.
2.**Make minimal, targeted edits** -- Change only the specific instruction line that addresses the identified issue. Do NOT expand terse instructions into verbose ones unless the terse version was causing a specific documented failure.
3.**Avoid instruction expansion** -- Adding more text to instructions does NOT always help. Prefer:
- Adding a single action reference: "Use `@actions.X` to look up..."
- Adding a single constraint: "Do not proceed until the customer provides..."
4.**Test immediately after each edit** -- Run the same test utterances. If pass rate drops, revert the change immediately.
5.**One fix per publish cycle** -- Do not batch multiple instruction changes into a single publish.
6.**Check cross-topic dependencies before editing** -- Before changing Topic A, identify variable dependencies, transition chains, and shared variable mutations:
```bash
grep -n 'set @variables\.' "$AGENT_FILE"
grep -n 'with .* = @variables\.' "$AGENT_FILE"
grep -n '@utils.transition to @topic\.' "$AGENT_FILE"
```
7.**Test adjacent topics after each fix** -- Include at least one cross-topic test to confirm the fix didn't cause spillover routing.
8.**Verify start_agent routing after topic removal** -- If removing a dead hub or merging topics, verify `start_agent > reasoning > actions:` still has transition actions to all remaining topics.
- **Adding an `available when` guard**: Add guard condition to action definition
IMPORTANT: Agent Script uses **tabs** for indentation, not spaces.
**Step 3 -- Show the diff:**
```bash
cd <project-root>&& git diff <AGENT_FILE>
```
---
## Validate, Deploy, Publish, and Activate
After editing the `.agent` file, use this deployment chain. **Never update `GenAiPluginInstructionDef` or other agent metadata directly** -- always edit the `.agent` file and re-deploy.
```bash
# Step 1: Validate (dry run)
sf agent validate authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>
```
If validation fails: fix syntax errors, deploy missing targets, or resolve duplicate names.
```bash
# Step 2: Publish (compiles, deploys metadata, and activates)
sf agent publish authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>
```
**If publish fails**, use the deploy + activate fallback:
```bash
# Step 3a: Deploy the bundle
sf project deploy start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>
# Step 3b: Activate
sf agent activate --json --api-name <AGENT_API_NAME> -o <org>
```
> **Warning: deploy + activate is an incomplete fallback.** `sf project deploy start` stores the bundle metadata but does **NOT** propagate topic-level `reasoning: actions:` blocks to live `GenAiPluginDefinition` records. Always verify with `--authoring-bundle` preview.
**Never use the Tooling API to patch `GenAiPluginInstructionDef` or other BPO objects directly.**
---
## Verify
**Immediate** -- run the Phase 2 scenarios that returned `[CONFIRMED]` before the fix. All should now return `[NOT REPRODUCED]`. Use `--authoring-bundle` to get trace-level verification:
```bash
sf agent preview start --json --authoring-bundle <BundleName> -o <org> | tee /tmp/verify_start.json
After applying fixes, re-run safety review on the modified `.agent` file. Optimization fixes can inadvertently introduce safety regressions:
- Relaxing `available when` guards may expose actions that should be gated
- Expanding topic descriptions may cause the agent to handle out-of-scope requests
- Changing instructions to be more permissive may weaken guardrails
- Adding literal instructions with tool names may bypass safety boundaries
**Run the safety review** from `Section 15 of /developing-agentforce` (Identity, User Safety, Data Handling, Content Safety, Fairness, Deception, Scope). Focus especially on:
1.**Scope boundaries** -- Did the fix widen the agent's scope beyond what's appropriate?
2.**Guard conditions** -- Did relaxing `available when` expose sensitive actions?
3.**Instruction safety** -- Do new/modified instructions maintain appropriate guardrails?
4.**Escalation paths** -- Are escalation paths still intact after topic restructuring?
**If any new BLOCK finding is introduced by the fix:** revert and find an alternative fix. Do NOT deploy an agent with new safety violations.
---
## Update Testing Center Test Cases
After fixing issues, create or update test cases in Testing Center format:
```yaml
# tests/<AgentApiName>-regression.yaml
name: "<AgentApiName> Regression Tests"
subjectType: AGENT
subjectName: <AgentApiName>
testCases:
- utterance: "<exactutterancefromPhase2scenario>"
expectedTopic: <topic_that_should_handle_this>
expectedActions:
-<action_that_should_fire>
- utterance: "<anotherfailingutterance>"
expectedTopic: <expected_topic>
expectedOutcome: "Agent should <expectedbehaviordescription>"
```
**Key format rules:**
-`expectedActions` is a **flat string list**: `["action_a"]`, NOT objects
-`subjectName` is the agent's `DeveloperName` (API name without `_vN` suffix)
-`expectedOutcome` uses LLM-as-judge evaluation
**Deploy and run:**
```bash
sf agent test create --json \
--spec tests/<AgentApiName>-regression.yaml \
--api-name <AgentApiName>_Regression \
--force-overwrite \
-o <org>
sf agent test run --json \
--api-name <AgentApiName>_Regression \
--wait 10 \
--result-format json \
-o <org> | tee /tmp/regression_run.json
# ALWAYS use --job-id, NOT --use-most-recent which is broken
