feat: Improve output replacement pattern

Author: achetronic

.agents/AGENTS.md

@@ -66,7 +66,7 @@ magec/
 │   │   ├── recorder.go         # ConversationRecorder + ConversationRecorderSSE (dual-perspective)
 │   │   ├── flowfilter.go       # Flow response filtering by responseAgent
 │   │   ├── sessionensure.go    # Idempotent session creation (prevents overwriting ContextGuard state)
-│   │   └── sessionstate.go     # Seeds outputKey values into session state on creation
+│   │   └── sessionstate.go     # Seeds outputKey values into session state for {{agent.output:key}} resolution
 │   ├── clients/                # Client type registry + runtime
 │   │   ├── provider.go         # Provider interface: Type(), DisplayName(), ConfigSchema()
 │   │   ├── registry.go         # Register(), ValidateConfig() with oneOf support
@@ -234,7 +234,8 @@ log:
 - **A2A protocol**: Agents/flows with `A2A.Enabled` get JSON-RPC endpoints via `a2a-go` + ADK `adka2a`. Agent cards auto-generated with capabilities and skills. SSE streaming for responses
 - **Dual-perspective conversation recording**: Middleware chains recorder twice: "admin" perspective (all events, before FlowResponseFilter) and "user" perspective (filtered, after). Each conversation has a `ParentID` linking the pair
 - **Store dual-copy pattern**: Store maintains `rawData` (unexpanded, with `${VAR}` refs) and `data` (env-expanded). API responses use raw data, runtime uses expanded. Secret values injected as env vars before expansion
-- **Session middleware**: `SessionEnsure` prevents overwriting existing sessions (protects ContextGuard summaries). `SessionStateSeed` injects empty outputKey values so flow agents don't fail on template vars
+- **Session middleware**: `SessionEnsure` prevents overwriting existing sessions (protects ContextGuard summaries). `SessionStateSeed` injects empty outputKey values so `{{agent.output:key}}` references in flow agent prompts resolve correctly
+- **InstructionProvider pattern**: Agents use `InstructionProvider` instead of static `Instruction` strings to bypass ADK's built-in `{variable}` substitution (which conflicts with curly braces in prompts, JSON examples, scripts, etc). Magec resolves its own `{{agent.output:key}}` pattern from session state inside the provider. Plain `{text}` in prompts is never touched
 - **Flow wrapAgent pattern**: Same agent can appear in multiple flow steps — `wrapAgent()` creates uniquely-named delegate agents to satisfy ADK's single-parent constraint
 
 ### Design Philosophy

server/agent/agent.go

@@ -24,6 +24,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"regexp"
 	"strconv"
 	"strings"
 	"time"
@@ -170,12 +171,12 @@ func New(ctx context.Context, agents []store.AgentDefinition, backends []store.B
 		instruction := buildInstruction(agentDef, mcpServerMap, skillMap, filepath.Join("data", "skills"), memorySvc)
 
 		agentCfg := llmagent.Config{
-			Name:        agentDef.ID,
-			Model:       llmModel,
-			Description: agentDef.Name,
-			Instruction: instruction,
-			Toolsets:    toolsets,
-			OutputKey:   agentDef.OutputKey,
+			Name:                agentDef.ID,
+			Model:               llmModel,
+			Description:         agentDef.Name,
+			InstructionProvider: makeInstructionProvider(instruction),
+			Toolsets:            toolsets,
+			OutputKey:           agentDef.OutputKey,
 		}
 
 		adkAgent, err := llmagent.New(agentCfg)
@@ -582,3 +583,26 @@ func buildInstruction(agentDef store.AgentDefinition, mcpServerMap map[string]st
 
 	return instruction
 }
+
+var stateVarRegex = regexp.MustCompile(`\{\{agent\.output:([a-zA-Z_][a-zA-Z0-9_]*)\}\}`)
+
+func makeInstructionProvider(template string) llmagent.InstructionProvider {
+	if !stateVarRegex.MatchString(template) {
+		return func(_ agent.ReadonlyContext) (string, error) {
+			return template, nil
+		}
+	}
+	return func(ctx agent.ReadonlyContext) (string, error) {
+		return stateVarRegex.ReplaceAllStringFunc(template, func(match string) string {
+			sub := stateVarRegex.FindStringSubmatch(match)
+			if len(sub) < 2 {
+				return match
+			}
+			val, err := ctx.ReadonlyState().Get(sub[1])
+			if err != nil || val == nil {
+				return ""
+			}
+			return fmt.Sprintf("%v", val)
+		}), nil
+	}
+}

server/middleware/sessionstate.go

@@ -13,7 +13,7 @@ import (
 // SessionStateSeed intercepts session creation requests (POST to
 // /apps/{app}/users/{user}/sessions/{session}) and injects empty outputKey
 // values into the session state. This ensures that flow agents referencing
-// {outputKey} template variables in their system prompts don't fail when
+// {{agent.output:outputKey}} template variables in their system prompts don't fail when
 // sessions are created by the Voice UI or other API clients that don't
 // pre-seed the state themselves.
 func SessionStateSeed(next http.Handler, dataStore *store.Store) http.Handler {

website/content/docs/agents.md

@@ -48,14 +48,14 @@ If you leave the system prompt empty, Magec uses a default prompt that makes the
 
 ### Output Key
 
-The **output key** is used when the agent participates in a [flow](/docs/flows/). It saves the agent's output under a named key in the flow's shared state. Other agents in the same flow can then reference that output using `{key_name}` in their own prompts.
+The **output key** is used when the agent participates in a [flow](/docs/flows/). It saves the agent's output under a named key in the flow's shared state. Other agents in the same flow can then reference that output using `{{agent.output:key_name}}` in their own prompts.
 
-For example, if a "researcher" agent has `outputKey: research_results`, a later "writer" agent can include `{research_results}` in its prompt to access what the researcher found.
+For example, if a "researcher" agent has `outputKey: research_results`, a later "writer" agent can include `{{agent.output:research_results}}` in its prompt to access what the researcher found.
 
 | Field | Description |
 |-------|-------------|
 | `systemPrompt` | The full instruction text. Supports multi-line, markdown, examples, and any formatting you want. |
-| `outputKey` | Named key for flow data passing. Other agents in the same flow can reference it with `{key_name}`. |
+| `outputKey` | Named key for flow data passing. Other agents in the same flow can reference it with `{{agent.output:key_name}}`. |
 
 ## LLM
 

website/content/docs/flows.md

@@ -71,9 +71,11 @@ Each step receives the accumulated output of all previous steps as context. The
 
 1. Give an agent an `outputKey` in its [configuration](/docs/agents/) (e.g., `research_results`)
 2. The agent's output is saved under that key in the flow's shared state
-3. Later agents can reference it with `{research_results}` in their system prompt
+3. Later agents can reference it with `{{agent.output:research_results}}` in their system prompt
 4. Magec replaces the placeholder with the actual output at runtime
 
+> **Note:** Magec uses `{{agent.output:variable}}` instead of `{variable}` for state references. This avoids conflicts with curly braces in your prompts, JSON examples, or any other content that uses `{` and `}`.
+
 This lets you build precise data pipelines. A "researcher" outputs structured findings, a "writer" references those findings in its prompt, a "reviewer" references both. Each agent sees exactly the context it needs.
 
 In parallel steps, all branches receive the same input. Their outputs are concatenated and passed to whatever comes next.

website/public/docs/agents/index.html

@@ -214,8 +214,8 @@ <h3 id="output-key">
   Output Key
   <a class="heading-anchor" href="#output-key" aria-label="Link to this section">#</a>
 </h3>
-<p>The <strong>output key</strong> is used when the agent participates in a <a href="/docs/flows/">flow</a>. It saves the agent&rsquo;s output under a named key in the flow&rsquo;s shared state. Other agents in the same flow can then reference that output using <code>{key_name}</code> in their own prompts.</p>
-<p>For example, if a &ldquo;researcher&rdquo; agent has <code>outputKey: research_results</code>, a later &ldquo;writer&rdquo; agent can include <code>{research_results}</code> in its prompt to access what the researcher found.</p>
+<p>The <strong>output key</strong> is used when the agent participates in a <a href="/docs/flows/">flow</a>. It saves the agent&rsquo;s output under a named key in the flow&rsquo;s shared state. Other agents in the same flow can then reference that output using <code>{{agent.output:key_name}}</code> in their own prompts.</p>
+<p>For example, if a &ldquo;researcher&rdquo; agent has <code>outputKey: research_results</code>, a later &ldquo;writer&rdquo; agent can include <code>{{agent.output:research_results}}</code> in its prompt to access what the researcher found.</p>
 <table>
   <thead>
       <tr>
@@ -230,7 +230,7 @@ <h3 id="output-key">
       </tr>
       <tr>
           <td><code>outputKey</code></td>
-          <td>Named key for flow data passing. Other agents in the same flow can reference it with <code>{key_name}</code>.</td>
+          <td>Named key for flow data passing. Other agents in the same flow can reference it with <code>{{agent.output:key_name}}</code>.</td>
       </tr>
   </tbody>
 </table>
@@ -305,11 +305,11 @@ <h2 id="skills">
 <p>While the <strong>system prompt</strong> defines who the agent is, skills define <strong>what it knows</strong>. An agent with a &ldquo;Return Policy&rdquo; skill and a &ldquo;Product Catalog&rdquo; skill becomes a capable customer support representative without you having to cram everything into one massive prompt.</p>
 <p>Skills are especially powerful when shared across agents. Update a product catalog skill once, and every agent that uses it sees the change.</p>
 <p>For a deeper comparison of when to use skills vs. creating specialized agents, see <a href="/docs/skills-vs-agents/">Skills vs. Agents</a>.</p>
-<h2 id="context-guard-hahahugoshortcode9s4hbhb">
+<h2 id="context-guard-hahahugoshortcode66s4hbhb">
   Context Guard 
 <span class="docs-badge">Experimental</span>
 
-  <a class="heading-anchor" href="#context-guard-hahahugoshortcode9s4hbhb" aria-label="Link to this section">#</a>
+  <a class="heading-anchor" href="#context-guard-hahahugoshortcode66s4hbhb" aria-label="Link to this section">#</a>
 </h2>
 <p>Long conversations eventually hit the model&rsquo;s token limit and fail. Context Guard watches the conversation size and automatically summarizes older messages before that happens. Recent messages stay untouched.</p>
 <p>You set it up per-agent inside the <strong>LLM</strong> section. Two strategies:</p>

website/public/docs/flows/index.html

@@ -238,9 +238,11 @@ <h3 id="how-data-flows-between-agents">
 <ol>
 <li>Give an agent an <code>outputKey</code> in its <a href="/docs/agents/">configuration</a> (e.g., <code>research_results</code>)</li>
 <li>The agent&rsquo;s output is saved under that key in the flow&rsquo;s shared state</li>
-<li>Later agents can reference it with <code>{research_results}</code> in their system prompt</li>
+<li>Later agents can reference it with <code>{{agent.output:research_results}}</code> in their system prompt</li>
 <li>Magec replaces the placeholder with the actual output at runtime</li>
 </ol>
+<blockquote>
+<p><strong>Note:</strong> Magec uses <code>{{agent.output:variable}}</code> instead of <code>{variable}</code> for state references. This avoids conflicts with curly braces in your prompts, JSON examples, or any other content that uses <code>{</code> and <code>}</code>.</p></blockquote>
 <p>This lets you build precise data pipelines. A &ldquo;researcher&rdquo; outputs structured findings, a &ldquo;writer&rdquo; references those findings in its prompt, a &ldquo;reviewer&rdquo; references both. Each agent sees exactly the context it needs.</p>
 <p>In parallel steps, all branches receive the same input. Their outputs are concatenated and passed to whatever comes next.</p>
 <h2 id="response-agents">