a2ui-project / a2ui-project/a2ui

adk session: KeyError: 'Context variable not found: expression' when using adk run with A2UI agents

Aperta
#1,388 4 commenti 0 reazioni 1 assegnatario Rivendicata da @gspencergoog Vedi su GitHub
component: standard catalog specification P1 status: needs review type: bug
Lingua principale
TypeScript
Stelle
16.4k
Fork
1.3k
Merge medio
3g 15h
PR unite (30g)
134

Descrizione

## Description

When running an A2UI-enabled agent using `adk run`, the CLI crashes with a `KeyError` as soon as the first user message is sent.

```
KeyError: 'Context variable not found: `expression`.'
```

Full traceback excerpt:

```
File ".../google/adk/utils/instructions_utils.py", line 124, in inject_session_state
return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
File ".../google/adk/utils/instructions_utils.py", line 122, in _replace_match
raise KeyError(f'Context variable not found: `{var_name}`.')
KeyError: 'Context variable not found: `expression`.'
```

---

## Steps to Reproduce

1. Create an ADK agent that uses `A2uiSchemaManager.generate_system_prompt()` with `include_schema=True` to build its instruction.
2. Expose `root_agent` at module level so it is compatible with `adk run`.

```python
# agent.py
root_agent = LlmAgent(
model=Gemini(model="gemini-2.0-flash"),
name="my_agent",
instruction=schema_manager.generate_system_prompt(
role_description="...",
include_schema=True,
include_examples=True,
),
tools=[...],
)
```

3. Run the agent:

```bash
adk run path/to/my_agent
```

4. Type any message and press Enter → crash.

---

## Root Cause

The `BasicCatalog` JSON schema bundled at `agent_sdks/python/src/a2ui/assets/0.9/basic_catalog.json` contains the following text in the description of the `formatString` function:

```
The value string can contain interpolated expressions in the `${expression}` format.
```

When `generate_system_prompt()` is called with `include_schema=True`, this description is embedded verbatim into the agent's `instruction` string.

When `adk run` processes the first user message, the ADK framework calls `inject_session_state()` in `instructions_utils.py`. This function scans the full instruction string with the regex `r'{+[^{}]*}+'`. It matches `{expression}`, strips the braces to extract `"expression"`, validates it as a Python identifier (which passes), looks it up in the active session state dict (which is empty because `adk run` manages sessions internally), and raises a `KeyError`.

The key line in the ADK source:

```python
# google/adk/utils/instructions_utils.py
return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
```

---

## Why Existing A2A Server Samples Are Unaffected

The existing A2A-based samples (e.g. `samples/agent/adk/restaurant_finder/`) manually create the ADK session and inject a dummy variable before running:

```python
# restaurant_finder/agent.py
session_state = {"base_url": self.base_url, "expression": "{expression}"}
session = await runner.session_service.create_session(
...,
state=session_state,
)
```

This satisfies the ADK template engine — it finds `"expression"` in the state and silently replaces the tag. `adk run` manages sessions internally and provides no hook to pre-seed the session state before the first message, so this workaround is not available when using the CLI.

---

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

The issue is in the ADK framework's instruction processing. Look at `google/adk/utils/instructions_utils.py`, specifically the `inject_session_state` function and the regex pattern `r'{+[^{}]*}+'`. The problem is triggered by the `{expression}` string in the A2UI schema description from `agent_sdks/python/src/a2ui/assets/0.9/basic_catalog.json`. You need to modify the template engine or the schema description to avoid this false match. Test by running an A2UI agent with `adk run` and sending a message to ensure it no longer crashes.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python, typescript
Ambito
backend-api-design, cli
Tipo di issue
Bug
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Attiva
Chiarezza
Specificata chiaramente
Idoneità per principianti
65/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.