Google ADK Integration
======================

Install the ADK extra and initialize Taimoe before constructing an Agent:

.. code-block:: bash

   pip install "taimoe-platform[adk]"

.. code-block:: python

   from google.adk.agents import LlmAgent
   from taimoe.platform import init, taimoe

   init(
       platform_url="https://platform.example.com",
       api_key="...",
       runtime_name="support-prod",
       framework="google-adk",
   )

   handle = taimoe.agent("support")
   tool_registry = {"search_orders": search_orders}

   agent = LlmAgent(
       name="support",
       model=handle.model,
       instruction=handle.instruction,
       tools=[tool_registry[name] for name in handle.tools],
       before_agent_callback=handle.refresh_callback,
   )

Live configuration behavior
---------------------------

=======================  ================================================================
Field                    Behavior
=======================  ================================================================
``instruction``          Callable instruction provider; ADK resolves it on every model call.
``model``                Snapshot at construction; the refresh callback updates it later.
``tools``                Names or IDs, not ADK tool objects; resolve them in application code.
``generation_config``    Dictionary of configured values; absent keys mean provider defaults.
``refresh_callback``     Refreshes model, tools, and generation settings before execution.
=======================  ================================================================

Hard-coded Agent fields remain owned by application code. Taimoe only governs
fields that the application reads from the handle.

Automatic instrumentation
-------------------------

``init(instrument=None)`` instruments ADK only when ``google.adk`` has already
been imported. Pass ``instrument=True`` to force patching or ``False`` to
disable it. Instrumentation routes supported ADK Gemini calls through the
Taimoe Gateway and emits model/tool telemetry. Patching is process-wide and
idempotent.

Tool resolution boundary
------------------------

The Platform currently synchronizes tool identifiers, not executable Python
objects. Keep the identifier-to-object registry in application code. This
preserves the deployment's code and credential boundary while allowing the
Platform to select from approved tools.