The toolchain and the dev loop

You now have the four control surfaces and the rules for a trustworthy backing action. Before we start hunting bugs in lessons 8 through 10, you need to know the dev loop. Every iteration is small.

Step 0: set the target org

sf config get target-org --json
# if empty:
sf config set target-org <alias>

Step 1: edit the .agent file

4-space indents, booleans capitalized (True/False), strings double-quoted. with email = ... means the LLM fills in.

Step 2: validate compilation

sf agent validate authoring-bundle --json --api-name <api_name>

Step 3: deploy backing Apex

sf project deploy start --json \
    --metadata ApexClass:VerifyCustomer

For each new class, also add it to the agent user's permission set (see lesson 8).

Step 4: live preview against the bundle

SID=$(sf agent preview start --json --use-live-actions \
        --authoring-bundle <api_name> | jq -r .result.sessionId)

sf agent preview send --json --authoring-bundle <api_name> \
    --session-id $SID -u "<test utterance>"

sf agent preview end --json --authoring-bundle <api_name> --session-id $SID

--use-live-actions is essential. Without it, Apex is never actually called and you are testing the LLM rather than the system.

Step 5: read traces

Covered in detail in the next lesson. Briefly: the trace is a JSON file under .sfdx/agents/<api_name>/sessions/<sid>/traces/<plan_id>.json.

Step 6: ship when green

sf agent publish authoring-bundle --json --api-name <api_name>
sf agent activate --json --api-name <api_name>

Every publish creates a permanent version. Do not publish during inner- loop iteration. Publish only when you are happy with the build.

Step 7: verify the published agent

Use --api-name (not --authoring-bundle) to test what end users will hit:

sf agent preview start --json --api-name <api_name>

If behavior differs from --authoring-bundle, your published version is older than your local edits.