fix(utils): include agent name in instruction context variable missing error

When instructions rendering fails due to a missing context variable or
artifact, include the agent name in the KeyError message so developers
can identify which agent failed in multi-agent workflows.

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 973901646

Author: DeanChensj

docs/guides/workflow/parallel_worker/index.md

@@ -65,7 +65,7 @@ analyzer_agent = Agent(
 
 Do not write `{node_input}` in the instruction. Braces in an instruction are
 substituted from session state, and there is no state key by that name, so the
-agent fails with ``KeyError: 'Context variable not found: `node_input`.'``. If you
+agent fails with ``KeyError: "Context variable not found: `node_input` in agent 'analyzer'."``. If you
 want a value from state in the instruction, put it in state first. The parallel
 worker sample does exactly that, writing `topic` in an earlier node and reading
 `{topic}` in the agent.

src/google/adk/utils/instructions_utils.py

@@ -153,7 +153,10 @@ async def _replace_match(match) -> str:
           )
           return ''
         else:
-          raise KeyError(f'Artifact {var_name} not found.')
+          raise KeyError(
+              f"Artifact '{var_name}' not found in agent"
+              f" '{readonly_context.agent_name}'."
+          )
       return str(artifact)
     else:
       if not _is_valid_state_name(var_name):
@@ -171,7 +174,10 @@ async def _replace_match(match) -> str:
           )
           return ''
         else:
-          raise KeyError(f'Context variable not found: `{var_name}`.')
+          raise KeyError(
+              f'Context variable not found: `{var_name}` in agent'
+              f" '{readonly_context.agent_name}'."
+          )
 
   return await _async_sub(_TEMPLATE_VAR_PATTERN, _replace_match, template)
 
@@ -219,7 +225,10 @@ async def _load_artifact(filename: str) -> str:
         filename=filename,
     )
     if artifact is None:
-      raise KeyError(f'Artifact {filename} not found.')
+      raise KeyError(
+          f"Artifact '{filename}' not found in agent"
+          f" '{readonly_context.agent_name}'."
+      )
     return str(artifact)
 
   env = jinja2.Environment(

tests/unittests/utils/test_instructions_utils.py

@@ -129,7 +129,8 @@ async def test_inject_session_state_with_missing_state_raises_key_error():
   )
 
   with pytest.raises(
-      KeyError, match="Context variable not found: `missing_key`."
+      KeyError,
+      match=r"Context variable not found: `missing_key` in agent 'agent'\.",
   ):
     await instructions_utils.inject_session_state(
         instruction_template, invocation_context
@@ -146,7 +147,9 @@ async def test_inject_session_state_with_missing_artifact_raises_key_error():
       artifact_service=mock_artifact_service
   )
 
-  with pytest.raises(KeyError, match="Artifact missing_file not found."):
+  with pytest.raises(
+      KeyError, match=r"Artifact 'missing_file' not found in agent 'agent'\."
+  ):
     await instructions_utils.inject_session_state(
         instruction_template, invocation_context
     )
@@ -232,7 +235,9 @@ async def test_inject_session_state_with_empty_artifact_name_raises_key_error():
       artifact_service=mock_artifact_service
   )
 
-  with pytest.raises(KeyError, match="Artifact  not found."):
+  with pytest.raises(
+      KeyError, match=r"Artifact '' not found in agent 'agent'\."
+  ):
     await instructions_utils.inject_session_state(
         instruction_template, invocation_context
     )
@@ -343,6 +348,22 @@ async def test_inject_session_state_jinja2_artifact():
   assert populated_instruction == "Content: artifact data"
 
 
+@pytest.mark.asyncio
+async def test_inject_session_state_jinja2_missing_artifact_raises_key_error():
+  instruction_template = "Content: {{ artifact('missing_file') }}"
+  mock_artifact_service = MockArtifactService({})
+  invocation_context = await _create_test_readonly_context(
+      artifact_service=mock_artifact_service
+  )
+
+  with pytest.raises(
+      KeyError, match=r"Artifact 'missing_file' not found in agent 'agent'\."
+  ):
+    await instructions_utils.inject_session_state(
+        instruction_template, invocation_context, use_jinja2=True
+    )
+
+
 @pytest.mark.asyncio
 async def test_inject_session_state_jinja2_undefined_variable_raises():
   instruction_template = "Hello {{ missing_var }}!"