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..967e41c --- /dev/null +++ b/force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent @@ -0,0 +1,49 @@ +# 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: + 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" + +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 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: "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: -> + if @variables.question_index < len(@variables.questions): + | Question {!@variables.question_index + 1} of {!len(@variables.questions)}: + | Ask this question: {!@variables.questions[@variables.question_index]} + | After the user answers, call advance_question to move to the next question. + else: + | 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 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 +