|
| 1 | +# InstructionActionReferences |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Learn how to **reference actions directly** within your reasoning instructions. This technique helps guide the LLM to use specific actions in specific contexts by explicitly mentioning them in the instruction text. Combined with dynamic variable expressions, you can create contextual, targeted prompts that improve action selection accuracy. |
| 6 | + |
| 7 | +## Agent Flow |
| 8 | + |
| 9 | +```mermaid |
| 10 | +%%{init: {'theme':'neutral'}}%% |
| 11 | +graph TD |
| 12 | + A[Start] --> B[Topic Selector] |
| 13 | + B --> C[Case Management Topic] |
| 14 | + C --> D{Evaluate next_open_time} |
| 15 | + D -->|Has Value| E[Outside Business Hours Path] |
| 16 | + E --> F["Instructions mention {[email protected]_case}"] |
| 17 | + F --> G[LLM Calls create_case Action] |
| 18 | + G --> H[Return Case Number to User] |
| 19 | + D -->|No Value| I[Inside Business Hours Path] |
| 20 | + I --> J[Help User Directly] |
| 21 | +``` |
| 22 | + |
| 23 | +## Key Concepts |
| 24 | + |
| 25 | +- **Action References **: `{[email protected]_name}` embeds a reference to the action definition directly in the instruction text, signaling to the LLM that this tool is relevant. |
| 26 | +- **Variable Expressions **: `{[email protected]}` injects dynamic variable values into instructions for contextual prompts. |
| 27 | +- **Procedural If Blocks**: Use `if @variables.name:` to conditionally include different instruction blocks based on variable state. |
| 28 | +- **Targeted Tool Guidance**: By naming actions in instructions, you increase the likelihood the LLM will select the appropriate tool. |
| 29 | + |
| 30 | +## How It Works |
| 31 | + |
| 32 | +### Why Reference Actions in Instructions? |
| 33 | + |
| 34 | +When the LLM receives a list of available actions, it must decide which one to use based on the user's request. By explicitly mentioning an action in the instruction text using `{[email protected]_name}`, you create a stronger association between the context and the tool. This is particularly useful when: |
| 35 | + |
| 36 | +- Multiple actions could apply, but one is preferred in a specific situation |
| 37 | +- You want to ensure a particular workflow is followed |
| 38 | +- The action name alone doesn't fully convey when it should be used |
| 39 | + |
| 40 | +### The Conditional Instruction Pattern |
| 41 | + |
| 42 | +This recipe demonstrates combining action references with procedural logic. The `if` block checks whether `next_open_time` has a value: |
| 43 | + |
| 44 | +```agentscript |
| 45 | +if @variables.next_open_time: |
| 46 | + | We are currently OUTSIDE business hours... |
| 47 | + Create a support case using {[email protected]_case}... |
| 48 | +else: |
| 49 | + | We are currently WITHIN business hours... |
| 50 | +``` |
| 51 | + |
| 52 | +When the condition is true, the instruction block that mentions `create_case` is included, guiding the LLM to use that specific action. |
| 53 | + |
| 54 | +### How Template Expressions Resolve |
| 55 | + |
| 56 | +The `{[email protected]_case}` expression doesn't just insert the action name—it embeds a reference to the full action definition. This gives the LLM richer context about the action's purpose, inputs, and outputs when making its decision. |
| 57 | + |
| 58 | +Similarly, `{[email protected]_open_time}` resolves to the actual variable value (e.g., "9:00 AM Tomorrow"), allowing the agent to communicate dynamic information to the user. |
| 59 | + |
| 60 | +## Key Code Snippets |
| 61 | + |
| 62 | +### Variable Declaration |
| 63 | + |
| 64 | +```agentscript |
| 65 | +variables: |
| 66 | + next_open_time: mutable string = "9:00 AM Tomorrow" |
| 67 | +``` |
| 68 | + |
| 69 | +### Action Definition |
| 70 | + |
| 71 | +```agentscript |
| 72 | +actions: |
| 73 | + create_case: |
| 74 | + description: "Creates a support case" |
| 75 | + inputs: |
| 76 | + subject: string |
| 77 | + description: "Subject of the case" |
| 78 | + outputs: |
| 79 | + case_number: string |
| 80 | + description: "The created case number" |
| 81 | + target: "flow://CreateCase" |
| 82 | +``` |
| 83 | + |
| 84 | +### Conditional Instructions with Action Reference |
| 85 | + |
| 86 | +```agentscript |
| 87 | +reasoning: |
| 88 | + instructions:-> |
| 89 | + | If the user has an issue that requires support, please help them. |
| 90 | +
|
| 91 | + if @variables.next_open_time: |
| 92 | + | We are currently OUTSIDE business hours. Support opens at {[email protected]_open_time}. |
| 93 | + Create a support case using {[email protected]_case} and share the Case Number. |
| 94 | + else: |
| 95 | + | We are currently WITHIN business hours. Support is available now. |
| 96 | + Help the user resolve their issue directly. |
| 97 | + actions: |
| 98 | + create_case: @actions.create_case |
| 99 | + with subject=... |
| 100 | +``` |
| 101 | + |
| 102 | +## Try It Out |
| 103 | + |
| 104 | +### Example Interaction |
| 105 | + |
| 106 | +```text |
| 107 | +Agent: Hi! I can help you create support cases. If the user has an issue that requires support, please help them. |
| 108 | +
|
| 109 | +User: I'm having trouble logging into my account. |
| 110 | +
|
| 111 | +Agent: I understand you're having login issues. Since we're currently outside business hours, I've created a support case for you. |
| 112 | +
|
| 113 | +Your Case Number is 00001234. Our support team will follow up with you when we reopen at 9:00 AM Tomorrow. |
| 114 | +``` |
| 115 | + |
| 116 | +### Behind the Scenes |
| 117 | + |
| 118 | +1. The user describes a login issue |
| 119 | +2. The reasoning block evaluates `next_open_time` and finds it has a value |
| 120 | +3. The conditional instruction mentioning `{[email protected]_case}` is included |
| 121 | +4. The LLM recognizes the action reference and calls `create_case` with an appropriate subject |
| 122 | +5. The flow returns a case number, which the agent shares along with the follow-up time |
| 123 | + |
| 124 | +## What's Next |
| 125 | + |
| 126 | +- **PromptTemplateActions**: Use Salesforce Prompt Templates for more complex generation scenarios. |
| 127 | +- **AdvancedInputBindings**: Learn more ways to bind inputs to actions dynamically. |
| 128 | +- **BeforeAfterReasoning**: Explore pre- and post-action reasoning patterns. |
0 commit comments