From 1b35ee7d622de2fda8ce2cd13537ee0d4a2f7391 Mon Sep 17 00:00:00 2001 From: Mohith Shrivastava Date: Tue, 12 May 2026 15:02:28 -0400 Subject: [PATCH 1/3] feat: add list variables recipe demonstrating iteration pattern Daily standup agent that iterates through a list[string] of questions using an index variable, len() for progress, and @utils.setVariables to advance through the list one question per turn. --- .../listVariables/README.md | 114 ++++++++++++++++++ .../ListVariables/ListVariables.agent | 51 ++++++++ .../ListVariables.bundle-meta.xml | 5 + 3 files changed, 170 insertions(+) create mode 100644 force-app/main/01_languageEssentials/listVariables/README.md create mode 100644 force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent create mode 100644 force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.bundle-meta.xml diff --git a/force-app/main/01_languageEssentials/listVariables/README.md b/force-app/main/01_languageEssentials/listVariables/README.md new file mode 100644 index 0000000..64509e1 --- /dev/null +++ b/force-app/main/01_languageEssentials/listVariables/README.md @@ -0,0 +1,114 @@ +# ListVariables + +## Overview + +This recipe demonstrates how to use **list variables** to store a collection of values and iterate through them one at a time. The agent runs a daily standup by asking questions from a `list[string]`, tracking progress with an index variable and `len()`. + +## Agent Flow + +```mermaid +%%{init: {'theme':'neutral'}}%% +graph TD + A[Start] --> B[start_agent agent_router] + B --> C[Transition to run_standup] + C --> D{question_index < len?} + D -->|Yes| E[Display progress: question N of 3] + E --> F[Ask questions at current index] + F --> G[User answers] + G --> H[LLM calls advance_question] + H --> D + D -->|No| I[All questions complete] + I --> J[Summarize answers] +``` + +## Key Concepts + +- **List declaration with defaults**: Define a `list[string]` pre-populated with values +- **Variable-based index access**: Use `@variables.list[@variables.index]` to access items dynamically +- **`len()` function**: Get the number of items in a list for progress display and loop control +- **Iteration pattern**: Increment an index variable after each turn to walk through the list + +## How It Works + +### Declaring a List Variable + +```agentscript +variables: + questions: mutable list[string] = ["What did you work on yesterday?", "What are you working on today?", "Do you have any blockers?"] + description: "The standup questions to ask the user" + + question_index: mutable number = 0 + description: "Current position in the questions list" +``` + +A list is declared with `list[]` and initialized with values in brackets. Pair it with an index variable to track your position. + +### Accessing a List Item by Variable Index + +```agentscript +| Ask this question: {!@variables.questions[@variables.question_index]} +``` + +Use `@variables.list[@variables.index]` to access the item at a dynamic position. List indexes start at 0. + +### Showing Progress with `len()` + +```agentscript +| Question {!@variables.question_index + 1} of {!len(@variables.questions)}: +``` + +`len(@variables.questions)` returns the number of items (3 in this case). Adding 1 to the zero-based index gives human-friendly numbering. + +### Iterating Without a For Loop + +Agent Script has no `for` loop. Instead, iterate by: + +1. Checking `if @variables.question_index < len(@variables.questions)` +2. Asking the question at the current index +3. Incrementing the index via a `@utils.setVariables` action +4. When the index reaches `len()`, the condition flips and the agent summarizes + +```agentscript +actions: + advance_question: @utils.setVariables + with question_index = @variables.question_index + 1 + description: "Move to the next question after the user answers." +``` + +## Try It Out + +### Example Interaction + +```text +Agent: Good morning! Let's run through your daily standup. + Question 1 of 3: What did you work on yesterday? + +User: I finished the API integration for the billing service. + +Agent: Got it. Question 2 of 3: What are you working on today? + +User: Writing tests for the billing integration and starting the dashboard UI. + +Agent: Nice. Question 3 of 3: Do you have any blockers? + +User: Waiting on design mockups for the dashboard. + +Agent: Thanks! Here's your standup summary: + - Yesterday: Finished billing service API integration + - Today: Writing billing tests, starting dashboard UI + - Blockers: Waiting on dashboard design mockups + Have a productive day! +``` + +## What's Next + +- **[VariableManagement](../variableManagement/)**: Fundamentals of scalar variables (string, number, boolean) +- **[TemplateExpressions](../templateExpressions/)**: More on `{!...}` syntax in instructions +- **[ActionChaining](../../02_actionConfiguration/actionChaining/)**: Populate lists dynamically with `set @variables.list = @outputs.result` + +## Notes + +- List indexes are **zero-based** — the first item is `[0]` +- Lists are global — all subagents can access and modify them +- `len()` can be used in template expressions, conditionals, and `available when` filters +- Supported list types: `list[string]`, `list[number]`, `list[boolean]`, `list[object]` diff --git a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent new file mode 100644 index 0000000..f6a4aeb --- /dev/null +++ b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent @@ -0,0 +1,51 @@ +# ListVariables - Iterating Through a List +# This agent demonstrates how to use list variables to work through a sequence of items + +config: + developer_name: "ListVariables" + agent_label: "ListVariables" + agent_type: "AgentforceEmployeeAgent" + description: "Runs a daily standup by iterating through a list of questions" + +variables: + # A list of strings with default values + questions: mutable list[string] = ["What did you work on yesterday?", "What are you working on today?", "Do you have any blockers?"] + description: "The standup questions to ask the user" + + # An index variable to track position in the list + question_index: mutable number = 0 + description: "Current position in the questions list" + +system: + messages: + welcome: "Good morning! Let's run through your daily standup." + error: "Sorry, something went wrong. Let's try that again." + + instructions: "You are a standup facilitator. Ask each question one at a time, acknowledge the user's answer briefly, then advance to the next question." + +start_agent agent_router: + description: "Routes to the standup subagent" + + reasoning: + instructions:| + Select the tool that best matches the user's message and conversation history. + actions: + go_to_standup: @utils.transition to @subagent.run_standup + description: "Start the daily standup questions." + +subagent run_standup: + description: "Asks standup questions one at a time from the list." + + reasoning: + instructions: -> + if @variables.question_index < len(@variables.questions): + | Question {!@variables.question_index + 1} of {!len(@variables.questions)}: + | Ask this question: {!@variables.questions[@variables.question_index]} + | Wait for the user's answer before advancing. + else: + | All standup questions are complete. + | Summarize what the user shared across all three answers and wish them a productive day. + actions: + advance_question: @utils.setVariables + with question_index = @variables.question_index + 1 + description: "Move to the next question after the user answers." diff --git a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.bundle-meta.xml b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.bundle-meta.xml new file mode 100644 index 0000000..a0018cf --- /dev/null +++ b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.bundle-meta.xml @@ -0,0 +1,5 @@ + + + AGENT + v0.1 + From f99fb104f1db58a63dd50057e798dad0cec9468b Mon Sep 17 00:00:00 2001 From: Mohith Shrivastava Date: Tue, 12 May 2026 15:12:40 -0400 Subject: [PATCH 2/3] fix: simplify agent to single start_agent for reliable list iteration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed the agent_router/subagent split that caused inconsistent topic routing — subsequent turns would stay at the router and skip the advance_question action. Using a single start_agent keeps the agent in the same topic across all turns, ensuring question_index advances reliably via @utils.setVariables. --- .../ListVariables/ListVariables.agent | 23 ++++--------------- 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent index f6a4aeb..e003652 100644 --- a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent +++ b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent @@ -8,11 +8,9 @@ config: description: "Runs a daily standup by iterating through a list of questions" variables: - # A list of strings with default values questions: mutable list[string] = ["What did you work on yesterday?", "What are you working on today?", "Do you have any blockers?"] description: "The standup questions to ask the user" - # An index variable to track position in the list question_index: mutable number = 0 description: "Current position in the questions list" @@ -21,19 +19,9 @@ system: welcome: "Good morning! Let's run through your daily standup." error: "Sorry, something went wrong. Let's try that again." - instructions: "You are a standup facilitator. Ask each question one at a time, acknowledge the user's answer briefly, then advance to the next question." + instructions: "You are a standup facilitator that runs a 3-question daily standup. Ask one question at a time. After the user answers each question, call the advance_question action to move forward. When all questions are done, summarize." -start_agent agent_router: - description: "Routes to the standup subagent" - - reasoning: - instructions:| - Select the tool that best matches the user's message and conversation history. - actions: - go_to_standup: @utils.transition to @subagent.run_standup - description: "Start the daily standup questions." - -subagent run_standup: +start_agent run_standup: description: "Asks standup questions one at a time from the list." reasoning: @@ -41,11 +29,10 @@ subagent run_standup: if @variables.question_index < len(@variables.questions): | Question {!@variables.question_index + 1} of {!len(@variables.questions)}: | Ask this question: {!@variables.questions[@variables.question_index]} - | Wait for the user's answer before advancing. + | After the user answers, call advance_question to move to the next question. else: - | All standup questions are complete. - | Summarize what the user shared across all three answers and wish them a productive day. + | All 3 standup questions are complete. + | Provide a brief summary of what the user shared and wish them a productive day. actions: advance_question: @utils.setVariables with question_index = @variables.question_index + 1 - description: "Move to the next question after the user answers." From adf2286b97a06f48f85f8ca419c4a5548007760f Mon Sep 17 00:00:00 2001 From: Mohith Shrivastava Date: Tue, 12 May 2026 15:18:14 -0400 Subject: [PATCH 3/3] fix: restore start_agent router + subagent pattern for consistency Brings back the standard agent_router -> subagent structure used across all recipes. Added label field and stronger description to the subagent for reliable topic routing across turns. Tested: question_index advances correctly via advance_question action on each turn. --- .../ListVariables/ListVariables.agent | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent index e003652..967e41c 100644 --- a/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent +++ b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent @@ -21,8 +21,19 @@ system: instructions: "You are a standup facilitator that runs a 3-question daily standup. Ask one question at a time. After the user answers each question, call the advance_question action to move forward. When all questions are done, summarize." -start_agent run_standup: - description: "Asks standup questions one at a time from the list." +start_agent agent_router: + description: "Welcome users and begin the standup" + + reasoning: + instructions:| + Select the tool that best matches the user's message and conversation history. If it's unclear, make your best guess. + actions: + go_to_standup: @utils.transition to @subagent.run_standup + description: "Run the daily standup questions one at a time." + +subagent run_standup: + label: "run_standup" + description: "Runs the daily standup by asking questions from a list one at a time and tracking progress." reasoning: instructions: ->