@salesforce/afv-skills 1.6.9 → 1.7.1

package/skills/developing-agentforce/references/instruction-resolution.md

@@ -0,0 +1,545 @@
+<!-- Parent: adlc-author/SKILL.md -->
+# Instruction Resolution
+
+> How Agent Script instructions are processed at runtime: from static text to dynamic LLM prompts.
+
+---
+
+## 1. Three Phases of Instruction Resolution
+
+Agent Script instructions go through three distinct phases at runtime. Understanding these phases is critical for writing effective instructions and debugging unexpected behavior.
+
+```
+Phase 1: Pre-LLM Setup
+   (deterministic -- runs before the LLM sees anything)
+       |
+       v
+Phase 2: LLM Reasoning
+   (non-deterministic -- LLM processes the assembled prompt)
+       |
+       v
+Phase 3: Post-Action Loop
+   (deterministic -- runs after an action completes, then loops back to Phase 1)
+```
+
+---
+
+## 2. Phase 1: Pre-LLM Resolution
+
+During Phase 1, the Agent Script runtime evaluates deterministic constructs in `instructions: ->` blocks. This happens BEFORE the LLM sees any text.
+
+### What Happens in Phase 1
+
+1. **`if`/`else` evaluation**: Conditions are evaluated against current variable values. Only the matching branch is included in the prompt.
+2. **Variable injection**: `{!@variables.X}` tokens are replaced with current values.
+3. **`run` execution**: Deterministic `run @actions.X` calls execute and their outputs are captured.
+4. **`set` execution**: Variable assignments execute immediately.
+5. **`transition to`**: If reached, the topic switch happens immediately (LLM is never called).
+
+### Phase 1 Example
+
+Given this instruction block:
+
+```
+reasoning:
+   instructions: ->
+      # 1. Post-action check (from previous loop)
+      if @variables.refund_approved == True:
+         | Your refund has been processed. Reference: {!@variables.refund_id}
+         transition to @topic.confirmation
+
+      # 2. Pre-LLM data loading
+      if @variables.data_loaded == False:
+         run @actions.load_customer_profile
+            with customer_id = @variables.customer_id
+            set @variables.risk_score = @outputs.risk_score
+            set @variables.tier = @outputs.tier
+         set @variables.data_loaded = True
+
+      # 3. Dynamic instructions
+      | Customer tier: {!@variables.tier}, Risk score: {!@variables.risk_score}
+
+      if @variables.risk_score >= 80:
+         | HIGH RISK -- Offer full cash refund to retain this customer.
+         | Do NOT offer store credit. Prioritize retention.
+
+      if @variables.risk_score < 80:
+         | STANDARD -- Offer $10 store credit as goodwill.
+         | Only escalate to cash refund if customer insists.
+```
+
+**First turn resolution** (variables at defaults):
+
+- `refund_approved == True` -> False. Skip this block.
+- `data_loaded == False` -> True. Execute `run @actions.load_customer_profile`. Variables now set.
+- Set `data_loaded = True`.
+- Inject `{!@variables.tier}` -> `"gold"`, `{!@variables.risk_score}` -> `85`.
+- `risk_score >= 80` -> True. Include high-risk instructions.
+- `risk_score < 80` -> False. Skip standard instructions.
+
+**What the LLM actually sees**:
+```
+Customer tier: gold, Risk score: 85
+HIGH RISK -- Offer full cash refund to retain this customer.
+Do NOT offer store credit. Prioritize retention.
+```
+
+---
+
+## 3. Phase 2: LLM Processing
+
+In Phase 2, the LLM receives the assembled prompt and produces a response. The LLM sees:
+
+### The 4-Message Prompt Structure
+
+The Agent Script runtime assembles a 4-message prompt for the LLM:
+
+| # | Message Role | Content Source | Purpose |
+|---|---|---|---|
+| 1 | **System** | `system: instructions:` + agent metadata | Global persona, safety rules, capabilities |
+| 2 | **System** | `topic: reasoning: instructions:` (resolved from Phase 1) | Topic-specific operating instructions |
+| 3 | **User/Assistant** | Conversation history (all turns) | Context for the current request |
+| 4 | **System** | Available actions + their descriptions | Tool palette the LLM can choose from |
+
+### What the LLM Decides
+
+Based on the assembled prompt, the LLM:
+
+1. **Selects an action** (if applicable) from the available actions list
+2. **Fills slot parameters** (`...` values) from conversation context
+3. **Generates a text response** to send to the user
+4. **Decides whether to transition** (if a transition action is available and appropriate)
+
+### What the LLM Does NOT See
+
+- Raw `if`/`else` blocks (already resolved in Phase 1)
+- `run` statements (already executed in Phase 1)
+- `set` statements (already executed)
+- `available when` conditions (already evaluated -- hidden actions are simply absent)
+- `after_reasoning` blocks (run after the LLM, not shown to it)
+
+---
+
+## 4. Phase 3: Post-Action Loop
+
+After the LLM selects and executes an action, the system loops back to Phase 1 for **re-resolution**. This is the post-action loop pattern described in the SKILL.md architecture section.
+
+### Loop Sequence
+
+```
+1. Phase 1 resolves instructions (first time)
+2. Phase 2: LLM reasons and selects an action
+3. Action executes -> outputs captured in variables
+4. Phase 1 re-resolves instructions (with updated variables)
+   - Post-action checks at TOP of instructions fire
+   - New data is injected into the prompt
+5. Phase 2: LLM reasons again with updated context
+6. Repeat until: transition, escalation, or no action selected
+```
+
+### Why Post-Action Checks Go at the TOP
+
+Place post-action checks at the TOP of `instructions: ->` so they fire immediately on re-resolution:
+
+```
+reasoning:
+   instructions: ->
+      # POST-ACTION CHECK (at TOP -- fires on re-resolution)
+      if @variables.order_cancelled == True:
+         | Your order has been cancelled successfully.
+         transition to @topic.confirmation
+
+      # These instructions are for the FIRST entry (before action runs)
+      | I can help you cancel your order.
+      | What is your order number?
+```
+
+If the check were at the BOTTOM, the LLM would see the "ask for order number" instructions again even after the cancellation succeeded, causing confusion.
+
+---
+
+## 5. Recommended Instruction Order
+
+Within a `instructions: ->` block, follow this order for maximum clarity:
+
+```
+reasoning:
+   instructions: ->
+      # 1. POST-ACTION CHECKS (deterministic transitions)
+      if @variables.action_completed == True:
+         transition to @topic.next_step
+
+      # 2. PRE-LLM DATA LOADING (deterministic actions)
+      if @variables.data_needed == True:
+         run @actions.load_data
+            with id = @variables.record_id
+            set @variables.loaded_data = @outputs.result
+
+      # 3. CONDITIONAL INSTRUCTIONS (based on state)
+      if @variables.is_verified == True:
+         | Full access granted. You can:
+         | - View account details
+         | - Make changes
+         | - Request refunds
+
+      if @variables.is_verified == False:
+         | Please verify your identity first.
+         | I need your email address and order number.
+
+      # 4. STATIC INSTRUCTIONS (always included)
+      | Be concise and professional.
+      | Always confirm before making changes.
+```
+
+---
+
+## 6. Common Instruction Patterns
+
+### Pattern 1: Security Gate
+
+Prevent access to sensitive actions until identity is verified:
+
+```
+reasoning:
+   instructions: ->
+      if @variables.is_verified == False:
+         | You must verify your identity before I can help with account changes.
+         | Please provide your email address.
+
+      if @variables.is_verified == True:
+         | Identity verified. I can now help with account changes.
+         | What would you like to do?
+
+   actions:
+      update_account: @actions.update_account_info
+         description: "Update account information"
+         available when @variables.is_verified == True
+         with field = ...
+         with value = ...
+```
+
+The `available when` guard hides the action from the LLM until verification passes. The conditional instructions tell the user what to do.
+
+### Pattern 2: Data-Dependent Instructions
+
+Load data first, then tailor instructions based on the result:
+
+```
+reasoning:
+   instructions: ->
+      run @actions.get_account_status
+         with account_id = @variables.account_id
+         set @variables.account_status = @outputs.status
+         set @variables.balance = @outputs.balance
+
+      | Account status: {!@variables.account_status}
+      | Current balance: {!@variables.balance}
+
+      if @variables.account_status == "delinquent":
+         | IMPORTANT: This account is delinquent.
+         | Collect payment before processing any other requests.
+         | Offer payment plan options if customer cannot pay in full.
+
+      if @variables.account_status == "active":
+         | This account is in good standing.
+         | Process requests normally.
+```
+
+### Pattern 3: Action Chaining
+
+Execute one action, then use its output to drive the next:
+
+```
+reasoning:
+   instructions: ->
+      # Post-action check: case was created in previous loop
+      if @variables.case_id != "":
+         | Case {!@variables.case_id} has been created.
+         run @actions.assign_case
+            with case_id = @variables.case_id
+            with priority = @variables.priority
+         transition to @topic.case_confirmation
+
+      | I need to collect some information to create a support case.
+      | What is the issue you're experiencing?
+```
+
+### Pattern 4: Multi-Condition Routing
+
+Route based on multiple variable values:
+
+```
+reasoning:
+   instructions: ->
+      if @variables.intent == "billing" and @variables.is_verified == True:
+         | I can help with your billing question.
+         transition to @topic.billing_support
+
+      if @variables.intent == "billing" and @variables.is_verified == False:
+         | For billing questions, I need to verify your identity first.
+         transition to @topic.identity_verification
+
+      if @variables.intent == "general":
+         | How can I help you today?
+```
+
+---
+
+## 7. Anti-Patterns to Avoid
+
+### Anti-Pattern 1: Nested If Blocks
+
+```
+# WRONG -- Agent Script does not support nested if or else if
+if @variables.tier == "gold":
+   if @variables.is_verified == True:
+      | VIP treatment
+   else:
+      | Verify first
+
+# CORRECT -- Use compound conditions
+if @variables.tier == "gold" and @variables.is_verified == True:
+   | VIP treatment
+
+if @variables.tier == "gold" and @variables.is_verified == False:
+   | Verify first
+```
+
+### Anti-Pattern 2: Post-Action Check at Bottom
+
+```
+# WRONG -- Check at bottom; LLM sees stale instructions on re-resolution
+reasoning:
+   instructions: ->
+      | What is your order number?
+
+      if @variables.order_status != "":
+         transition to @topic.show_status
+
+# CORRECT -- Check at TOP
+reasoning:
+   instructions: ->
+      if @variables.order_status != "":
+         transition to @topic.show_status
+
+      | What is your order number?
+```
+
+### Anti-Pattern 3: Persona in Topic Instructions
+
+```
+# WRONG -- Persona text duplicated in every topic
+reasoning:
+   instructions: |
+      You are a friendly, professional customer service agent.
+      Help the customer with their order.
+
+# CORRECT -- Persona in system instructions, topic has operational instructions only
+system:
+   instructions: |
+      You are a friendly, professional customer service agent.
+
+topic order_support:
+   reasoning:
+      instructions: ->
+         | Help the customer check their order status.
+         | Ask for the order number if not provided.
+```
+
+### Anti-Pattern 4: Using `|` When `->` Is Needed
+
+```
+# WRONG -- Using literal mode when conditionals are needed
+reasoning:
+   instructions: |
+      if @variables.is_verified == True:
+         Show account details.
+
+# The above sends the literal text "if @variables.is_verified == True:" to the LLM!
+
+# CORRECT -- Use procedural mode for conditionals
+reasoning:
+   instructions: ->
+      if @variables.is_verified == True:
+         | Show account details.
+```
+
+### Anti-Pattern 5: Missing Variable Injection Syntax
+
+```
+# WRONG -- Variable name as literal text
+reasoning:
+   instructions: ->
+      | Your order ID is @variables.order_id
+
+# CORRECT -- Use injection syntax
+reasoning:
+   instructions: ->
+      | Your order ID is {!@variables.order_id}
+```
+
+### Anti-Pattern 6: `run` Inside `after_reasoning`
+
+While `run` compiles inside `after_reasoning:`, its runtime behavior is inconsistent across bundle types. Prefer using `run` in `reasoning: instructions: ->` or `reasoning: actions:` instead.
+
+```
+# RISKY -- run in after_reasoning has inconsistent behavior
+after_reasoning:
+   run @actions.log_event
+      with event = "turn_completed"
+
+# SAFER -- Use instructions: -> for deterministic runs
+reasoning:
+   instructions: ->
+      # Post-action logging
+      if @variables.last_action != "":
+         run @actions.log_event
+            with event = @variables.last_action
+```
+
+---
+
+## 8. Syntax Patterns Reference
+
+### Literal Mode (`|`)
+
+Static text passed directly to the LLM. No evaluation occurs:
+
+```
+instructions: |
+   Help the customer with their order.
+   Be professional and concise.
+```
+
+Or with the `|` prefix on each line (inside procedural mode):
+
+```
+instructions: ->
+   | Help the customer with their order.
+   | Be professional and concise.
+```
+
+### Procedural Mode (`->`)
+
+Enables conditionals, variable injection, and deterministic actions:
+
+```
+instructions: ->
+   if @variables.condition == True:
+      | Text shown when condition is true.
+   else:
+      | Text shown when condition is false.
+```
+
+### Variable Injection
+
+```
+| Your order {!@variables.order_id} is {!@variables.status}.
+```
+
+### Deterministic Run
+
+```
+run @actions.load_data
+   with param = @variables.value
+   set @variables.result = @outputs.field
+```
+
+### Deterministic Set
+
+```
+set @variables.counter = @variables.counter + 1
+```
+
+### Deterministic Transition
+
+```
+transition to @topic.next_topic
+```
+
+### Conditional Transition
+
+```
+if @variables.all_collected == True:
+   transition to @topic.confirmation
+```
+
+---
+
+## 9. Programmatic Trace Access
+
+To verify how instructions were resolved at runtime, use the trace files generated by `sf agent preview`.
+
+### Trace File Location
+
+```
+.sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json
+```
+
+### Reading Instruction Resolution from Traces
+
+```bash
+# Extract the resolved instructions that the LLM received
+jq -r '.planTrace.steps[] | select(.type == "LLM_STEP") | .input' \
+  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json
+
+# Extract the LLM's response
+jq -r '.planTrace.steps[] | select(.type == "LLM_STEP") | .output' \
+  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json
+
+# Check which variables were set during resolution
+jq -r '.planTrace.steps[] | select(.type == "ACTION_STEP") | {name: .name, pre: .preVars, post: .postVars}' \
+  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json
+```
+
+### Verifying Phase 1 Resolution
+
+To confirm that `if`/`else` blocks resolved correctly, compare the trace's `LLM_STEP` input against your `instructions: ->` block. The LLM input should contain only the branches that matched, with all `{!@variables.X}` tokens replaced with actual values.
+
+If the trace shows unexpected instruction text:
+1. Check that you used `->` mode (not `|` mode) when conditionals are present
+2. Verify variable values at the time of resolution (check `preVars` on preceding `ACTION_STEP`)
+3. Confirm that `if` conditions use the correct comparison operators
+
+### Using STDM for Production Trace Analysis
+
+For production agents, use the Session Trace Data Model (STDM) in Data Cloud to access trace data programmatically. The STDM captures `LLM_STEP` records with `input` and `output` fields that contain the resolved prompt and LLM response. This is useful for auditing instruction resolution at scale across hundreds of live sessions.
+
+---
+
+## 10. Resolution Across Topic Transitions
+
+When a topic transition occurs (via `@utils.transition to @topic.X` or `transition to @topic.X`), instruction resolution starts fresh in the new topic:
+
+1. The current topic's remaining instructions are NOT processed
+2. The new topic's `before_reasoning:` runs (if present)
+3. The new topic's `reasoning: instructions:` resolves from Phase 1
+4. The LLM receives the new topic's assembled prompt
+
+**Important**: Variables persist across transitions. A variable set in Topic A is available in Topic B. This is how you pass data between topics:
+
+```
+# Topic A: Collect data
+topic collect_info:
+   reasoning:
+      instructions: ->
+         | Please provide your order number.
+      actions:
+         capture_order: @actions.get_order_id
+            with input = ...
+            set @variables.order_id = @outputs.order_id
+
+   after_reasoning:
+      if @variables.order_id != "":
+         transition to @topic.process_order
+
+# Topic B: Use the data
+topic process_order:
+   reasoning:
+      instructions: ->
+         # order_id is available from Topic A
+         | Processing order {!@variables.order_id}...
+         run @actions.get_order_details
+            with order_id = @variables.order_id
+            set @variables.order_status = @outputs.status
+```

package/skills/{agentforce-development → developing-agentforce}/references/known-issues.md

@@ -31,10 +31,10 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Workaround**: Move test definitions to a separate directory outside the main deploy path, or use `--metadata` flag to deploy specific types instead of `--source-dir`.
   ```bash
   # Instead of:
-  sf project deploy start --source-dir force-app -o TARGET_ORG
+  sf project deploy start --json --source-dir force-app -o TARGET_ORG
 
   # Use targeted deployment:
-  sf project deploy start --metadata AiAuthoringBundle:MyAgent -o TARGET_ORG
+  sf project deploy start --json --metadata AiAuthoringBundle:MyAgent -o TARGET_ORG
   ```
 - **Open Questions**: Will Salesforce optimize `AiEvaluationDefinition` deploy performance in a future release?
 
@@ -87,9 +87,9 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
   sf bot version list
 
   # ✅ New commands (for Agent Script):
-  sf project retrieve start --metadata Agent:MyAgent
-  sf agent validate authoring-bundle --api-name MyAgent
-  sf agent publish authoring-bundle --api-name MyAgent
+  sf project retrieve start --json --metadata Agent:MyAgent
+  sf agent validate authoring-bundle --json --api-name MyAgent
+  sf agent publish authoring-bundle --json --api-name MyAgent
   ```
 - **Open Questions**: Will Salesforce unify the `sf bot` and `sf agent` command families?
 
@@ -102,14 +102,14 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Symptom**: Tests created in the Agent Testing Center UI cannot be retrieved via `sf project retrieve start`. Old test XML format references `bot`/`version` fields that don't exist in Agent Script. No metadata type or CLI command exists for new-style agent tests.
 - **Root Cause**: The Agent Testing Center was originally built for Einstein Bots. The test metadata schema hasn't been updated for Agent Script's `AiAuthoringBundle` structure. The `AiEvaluationDefinition` type exists but doesn't correspond to the Testing Center's UI-created tests.
 - **Workaround**:
-  1. Use YAML test spec files managed in source control (see `/sf-ai-agentforce-testing` skill)
+  1. Use YAML test spec files managed in source control (see `/testing-agentforce` skill)
   2. Treat UI-created tests as ephemeral / org-specific
   3. Use the Connect API directly to run tests programmatically
 - **Open Questions**:
   - Will a new metadata type be introduced for Agent Script tests?
   - Can `AiEvaluationDefinition` be used with Agent Script agents?
   - Is there a roadmap for test portability?
-- **References**: See `references/custom-eval-investigation.md` in `sf-ai-agentforce-testing` for related findings on custom evaluation data structure issues.
+- **References**: See `references/custom-eval-investigation.md` in `testing-agentforce` for related findings on custom evaluation data structure issues.
 
 ---
 
@@ -246,12 +246,12 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Root Cause**: The `connection messaging:` DSL block only generates a `Messaging` plannerSurface during compilation. There is no `connection customerwebclient:` DSL syntax — attempting it causes `ERROR_HTTP_404` on publish. The compiler has no mechanism to auto-generate `CustomerWebClient`.
 - **Impact**: Every publish overwrites the GenAiPlannerBundle, dropping any manually-added `CustomerWebClient` surface. This requires a post-publish patch after EVERY publish.
 - **Workaround — 6-Step Post-Publish Patch Workflow:**
-  1. `sf agent publish authoring-bundle --api-name AgentName -o TARGET_ORG --json` → creates new version (e.g., v22)
-  2. `sf project retrieve start --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG --json` → retrieve compiled bundle
+  1. `sf agent publish authoring-bundle --json --api-name AgentName -o TARGET_ORG` → creates new version (e.g., v22)
+  2. `sf project retrieve start --json --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG` → retrieve compiled bundle
   3. Manually add second `<plannerSurfaces>` block to the XML with `<surfaceType>CustomerWebClient</surfaceType>` (copy the existing `Messaging` block, change surfaceType and surface fields)
-  4. `sf agent deactivate --api-name AgentName -o TARGET_ORG` → deactivate agent (deploy fails while active)
-  5. `sf project deploy start --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG --json` → deploy patched bundle
-  6. `sf agent activate --api-name AgentName -o TARGET_ORG` → reactivate agent
+  4. `sf agent deactivate --json --api-name AgentName -o TARGET_ORG` → deactivate agent (deploy fails while active)
+  5. `sf project deploy start --json --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG` → deploy patched bundle
+  6. `sf agent activate --json --api-name AgentName -o TARGET_ORG` → reactivate agent
 - **Patch XML Example:**
   ```xml
   <!-- Add this AFTER the existing Messaging plannerSurfaces block -->
@@ -301,16 +301,16 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Workaround**: Use `sf project retrieve start --metadata "TypeName:ApiName"` instead of SOQL. For querying agent status/versions via SOQL, use `BotDefinition` and `BotVersion` sObjects.
   ```bash
   # ❌ WRONG — these are NOT sObjects
-  sf data query --query "SELECT Id FROM GenAiPlannerBundle" -o ORG --json
-  sf data query --query "SELECT Id FROM AiAuthoringBundle" -o ORG --json
+  sf data query --json --query "SELECT Id FROM GenAiPlannerBundle" -o ORG
+  sf data query --json --query "SELECT Id FROM AiAuthoringBundle" -o ORG
 
   # ✅ CORRECT — use Metadata API
-  sf project retrieve start --metadata "GenAiPlannerBundle:MyAgent_v1" -o ORG --json
-  sf project retrieve start --metadata "AiAuthoringBundle:MyAgent" -o ORG --json
+  sf project retrieve start --json --metadata "GenAiPlannerBundle:MyAgent_v1" -o ORG
+  sf project retrieve start --json --metadata "AiAuthoringBundle:MyAgent" -o ORG
 
   # ✅ CORRECT — query sObjects for agent info
-  sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName = 'MyAgent'" -o ORG --json
-  sf data query --query "SELECT Id, VersionNumber, Status FROM BotVersion WHERE BotDefinition.DeveloperName = 'MyAgent'" -o ORG --json
+  sf data query --json --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName = 'MyAgent'" -o ORG
+  sf data query --json --query "SELECT Id, VersionNumber, Status FROM BotVersion WHERE BotDefinition.DeveloperName = 'MyAgent'" -o ORG
   ```
 - **Open Questions**: None — this is by design.
 

package/skills/{agentforce-development → developing-agentforce}/references/production-gotchas.md

@@ -185,7 +185,7 @@ process_order: @actions.create_order
 
 KNOWN BUG: Chained actions with Prompt Templates don't properly map inputs using `Input:Query` format.
 
-For prompt template action definitions, input binding syntax, and grounded data patterns, see [references/action-prompt-templates.md](../references/action-prompt-templates.md).
+For prompt template action definitions, input binding syntax, and grounded data patterns, see [Action Prompt Templates](action-prompt-templates.md).
 
 ## Latch Variable Pattern for Topic Re-entry
 
@@ -250,10 +250,31 @@ Failed to retrieve components using source tracking:
 [SfError [UnsupportedBundleTypeError]: Unsupported Bundle Type: AiAuthoringBundle
 
 # ✅ WORKAROUND - Use CLI directly:
-sf project retrieve start -m AiAuthoringBundle:MyAgent
-sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG
+sf project retrieve start --json -m AiAuthoringBundle:MyAgent
+sf agent publish authoring-bundle --json --api-name MyAgent -o TARGET_ORG
 ```
 
+## `@inputs` Scope Lifecycle (Silent Failure)
+
+`@inputs` is only available in `with` directives during action invocation. Using `@inputs` in a post-action `set` causes **silent runtime failure** — the action executes but the `set` silently drops, leaving the variable unchanged. No trace error; the FunctionStep shows no output capture.
+
+```agentscript
+# WRONG — silent failure, @inputs out of scope after action executes
+run @actions.get_station_status
+    with station_name = ...
+    set @variables.station = @inputs.station_name   # FAILS SILENTLY
+
+# RIGHT — use @outputs (if action echoes the value) or capture input before the call
+set @variables.station = @variables.selected_station  # capture before
+run @actions.get_station_status
+    with station_name = @variables.station
+    set @variables.status = @outputs.status           # @outputs is valid here
+```
+
+**Diagnosis:** A FunctionStep that completes with no output capture (set directives dropped) indicates an `@inputs` scope violation. The action succeeds — only the assignment fails.
+
+Similarly, `@outputs` is only available in `set` and `if` directives immediately following the action invocation — not in instructions, pipe lines, or later actions.
+
 ## Reserved `@InvocableVariable` Keywords
 
 Certain common words cannot be used as `@InvocableVariable` names in Apex classes called by Agent Script. Using them causes "SyntaxError: Unexpected '{keyword}'" during agent script compilation. (Validated March 2026)