Provide Out-of-the-Box Integration for a Popular Templating Framework

[Jacksunwei]

ADK includes a minimal templating mechanism for the LlmAgent#instruction field. To avoid imposing a specific dependency, it uses the InstructionProvider interface, allowing developers to integrate their preferred templating framework.

However, this flexibility requires developers to create their own integrations for popular frameworks, leading to duplicated effort. To improve the developer experience, we should offer official, out-of-the-box support for widely-used templating engines.

This issue tracks the creation of the first community-driven integration with a popular framework.

---

Potential use cases to support:

• Support templating of nested values in instruction template adk-python#575

[Jainish-S]

Hi @Jacksunwei & @hangfei,

I propose implementing an out-of-the-box integration for Jinja2 (for now).

Solution

This is the interface which would support all the templates

from __future__ import annotations

from abc import ABC
from abc import abstractmethod
from typing import Any
from typing import Dict
from typing import TYPE_CHECKING

if TYPE_CHECKING:
  from google.adk.agents.readonly_context import ReadonlyContext


class BaseTemplateProvider(ABC):
  """Base class for template-based instruction providers.

  This class provides common functionality for all templating engines,
  including state extraction and error handling patterns.

  Subclasses must implement the `_render_template` method to integrate
  with their specific templating engine.
  """

  def __init__(self, template: str):
    """Initialize the template provider.

    Args:
        template: The template string to render.
    """
    self.template = template

  async def __call__(self, context: ReadonlyContext) -> str:
    """Render the template with session state from context.

    This method is called by the ADK framework to generate dynamic
    instructions for agents.

    Args:
        context: The readonly context containing session state.

    Returns:
        The rendered instruction string.
    """
    render_context = self._extract_context(context)
    return await self._render_template(render_context)

  def _extract_context(self, context: ReadonlyContext) -> Dict[str, Any]:
    """Extract rendering context from ADK's ReadonlyContext.

    This method provides access to:
    - Session state variables
    - User ID
    - Session ID
    - App name

    Args:
        context: The readonly context from ADK.

    Returns:
        Dictionary of variables available for template rendering.
    """
    # Access the invocation context to get session information
    invocation_context = context._invocation_context
    session = invocation_context.session

    # Build the render context with session state and metadata
    render_context = dict(context.state)

    # Add session metadata as special variables
    render_context['__session_id__'] = session.id
    render_context['__user_id__'] = session.user_id
    render_context['__app_name__'] = session.app_name

    return render_context

  @abstractmethod
  async def _render_template(self, context: Dict[str, Any]) -> str:
    """Render the template using the specific templating engine.

    Subclasses must implement this method to integrate with their
    templating engine (Jinja2, Mako, Mustache, Django, etc.).

    Args:
        context: Dictionary of variables for template rendering.

    Returns:
        The rendered template string.

    Raises:
        Any templating engine-specific exceptions.
    """
    pass

For now we could implement a Jinja2InstructionProvider class that adheres to the InstructionProvider protocol. It will accept a template string or file path and render it using the session state injected via ReadonlyContext.

Here is a rough sketch of the implementation:

class Jinja2InstructionProvider:
    def __init__(self, template_str: str = None, template_path: str = None, default_context: dict = None):
        self.env = jinja2.Environment()
        self.default_context = default_context or {}
        # Logic to load template from str or path...
        self.template = ... 

    def __call__(self, context: ReadonlyContext) -> str:
        render_context = self.default_context.copy()
        
        # Inject session state into the template context
        if hasattr(context, 'state'):
            render_context.update(context.state)
            
        return self.template.render(render_context)

This would allow users to write instructions like:

You are an assistant for {{ user.name }}.
{% if user.is_admin %}
You have admin access.
{% endif %}

If this approach aligns with the project's goals, I can start working on the PR immediately.

EDIT: I have added the support, should I raise a PR or review the commit in my fork and can make changes according to suggestions