Quickstart
==========

Configure the SDK and resolve a platform-managed agent handle. Depending on your system design, you can use the SDK in **Runtime-bound (Dual Sync)** or **Runtime-less (Single Sync)** mode:

.. tab-set::

   .. tab-item:: Mode 1: Runtime-bound (Long-Running Server)

      .. code-block:: python

         import os
         from taimoe.platform import init, taimoe

         # Initialize, perform the first sync, and start background polling.
         registry = init(
             runtime_name="hr-prod-runtime",
             platform_url="https://taimoe.example.com",
             api_key=os.environ["TAIMOE_VIRTUAL_KEY"],
             framework="google-adk",
         )

         # The global handle is now bound to this Registry.
         agent_cfg = taimoe.agent("hr_searcher")

   .. tab-item:: Mode 2: Runtime-less (Short-Lived or Client-Side)

      .. code-block:: python

         from taimoe.platform import init, taimoe

         # Initialize direct, per-Agent configuration sync.
         init(
             platform_url="https://taimoe.example.com",
             api_key="...",  # Prefer TAIMOE_VIRTUAL_KEY in production.
             poll_interval_seconds=60,
         )

         # 2. Automatically sync and subscribe to the agent
         agent_cfg = taimoe.agent("hr_searcher")


Framework Integrations
======================

The returned handle exposes platform-managed values such as ``model``, ``instruction``,
``tools``, and ``generation_config`` to dynamically configure agents.

Google ADK
----------

With the ADK integration extra installed, feed the dynamic config directly into your Google ADK agent:

.. code-block:: python

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

   from my_app.tools import search_orders

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

   root_agent = LlmAgent(
       name="hr_searcher",
       model=handle.model,
       instruction=handle.instruction,
       tools=[tool_registry[tool_id] for tool_id in handle.tools],
       before_agent_callback=handle.refresh_callback,
   )

The ``instruction`` callable resolves on every model call. The ``before_agent_callback`` refreshes Model, Tools, and generation settings from the local cache before the Agent executes. Platform tool values are names or IDs; resolve them to actual ADK tool objects through your application registry before passing them to ``LlmAgent``.

See ``contributing/samples/adk_quickstart.py`` in the repository for a fully runnable sample.

Next steps
==========

* :doc:`configuration` explains initialization, environment variables, sync modes, and failure behavior.
* :doc:`adk-integration` explains which Agent fields are live and when callbacks are required.
* :doc:`runtime-discovery` exposes your Runtime and Agent manifests to the Platform.
* :doc:`observability` adds traces, spans, decorators, and the OpenTelemetry bridge.
* :doc:`rest-client` covers the typed sync/async API client and canonical errors.