Metadata-Version: 2.4
Name: chatsee-google-adk
Version: 0.1.0
Summary: ChatSee connector for Google ADK — capture every agent run with one plugin.
Maintainer-email: ChatSee <contact@chatsee.ai>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: chatsee-ai>=0.14.0
Requires-Dist: google-adk>=2.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: chatsee-connector-testing; extra == "dev"

# chatsee-google-adk

ChatSee connector for Google ADK (Agent Development Kit).

```bash
pip install chatsee-google-adk
```

```python
from google.adk.apps import App
from chatsee_google_adk import instrument_google_adk

chatsee = instrument_google_adk(agent_id="...", tenant_id="...")
app = App(name="support", root_agent=agent, plugins=[chatsee.plugin])
```

That is the whole integration. The handle's `.plugin` is an ADK `BasePlugin`,
and it works the same on a `Runner(plugins=[...])`. `chatsee-ai` is installed
for you as a dependency.

## What it captures

Per turn: the user's message, the agent's answer, the root agent's
instruction as the system prompt, every tool call with its arguments, result
and duration, and **one model call per model call** with the usage ADK
reported for it.

## No per-agent wiring

ADK fires plugin callbacks globally — every agent, every sub-agent, every
model call and tool in the run goes past this one plugin. A multi-agent app
needs no extra registration, and adding a sub-agent later changes nothing.

Every callback returns `None`, which is ADK's "carry on" — the plugin only
reads what goes past and never alters a response, a tool result or the flow.

## The part worth knowing

**One ADK run is one ChatSee turn**, emitted from `after_run_callback` — one
`runner.run_async` call, one user message. Not `after_agent_callback`, which
fires once per sub-agent and would split a single turn into several.

Two consequences worth knowing:

* **A failed run still produces a turn.** ADK skips `after_run` when a run
  raises, so the connector also emits from `on_run_error_callback`, with the
  error attached. Otherwise a failing agent would simply go quiet.
* **Streaming does not inflate the model-call count.** `after_model` fires
  once per chunk; partial responses are ignored and only the final aggregated
  response counts, so one call stays one call rather than dozens.

## Sessions and users

By default each turn uses ADK's own `session.id` and `user_id`, so a reused
ADK session is one ChatSee conversation — usually what you want.

To override, pass `user_id=` / `conversation_id=` to `instrument_google_adk`,
or call `chatsee.set_session(conversation_id)` to pin every later turn to one
conversation. `chatsee.stats()` reports turns emitted, capture failures and
runs in flight.

## Guarantees

* **Fails open.** Every callback is wrapped; a failure inside capture is
  logged and swallowed. ADK re-raises plugin exceptions into the run, so this
  matters more here than elsewhere — ChatSee can never break your agent.
* **Idempotent.** Instrumenting twice with the same identity returns the first
  handle rather than registering a second plugin.
* **Concurrency-safe.** Runs are keyed by `invocation_id`, so one Runner
  serving several users at once does not mix them up, and the send happens off
  the event loop so one turn's POST does not stall the others.

All three are enforced by the contract suite, not just intended.

## Tests

No network, no API key, no dev tenant — ADK is stubbed, ChatSee is not.

```bash
pip install -e python/connectors/_shared
pip install -e python/connectors/frameworks/google-adk
pytest python/connectors/frameworks/google-adk/tests -q
```
