runtime-services

# Runtime Services Use this sub-skill when a task is about ADK execution services rather than agent design: `Runner`, `InMemoryRunner`, `App`, session persistence, memory, artifacts, plugins, telemetry, code executors, execution environments, event storage, lifecycle cleanup, or service migration cautions. ## Route Here - Create or debug a `Runner`/`InMemoryRunner`, including `run`, `run_async`, `run_live`, `run_debug`, `close`, and `auto_create_session` behavior. - Choose between `InMemorySessionService`, `SqliteSessionService`, `DatabaseSessionService`, or cloud-backed session/memory/artifact services. - Explain why events, state, memory, artifacts, or live audio blobs were or were not persisted. - Add an app-level `BasePlugin` that observes model/tool/user/event callbacks while preserving runner-owned event persistence. - Configure OpenTelemetry/logging, `TelemetryConfig`, or `google_adk` logger behavior. - Attach a code executor or execution environment and assess local/container/cloud safety trade-offs. - Diagnose optional dependency failures such as missing SQLAlchemy for DB sessions or missing extension/cloud packages. ## Route Elsewhere - Agent, tool, callback, schema, model, or sub-agent construction belongs in [agent-construction](../agent-construction/SKILL.md). - `Workflow` graph/node/edge/resume design belongs in [workflow-orchestration](../workflow-orchestration/SKILL.md). - CLI servers, app discovery, YAML config, and deployment commands belong in [cli-configuration-deployment](../cli-configuration-deployment/SKILL.md). - Evaluation metrics, eval sets, and `adk test`/`adk eval` assertion design belongs in [evaluation-debugging](../evaluation-debugging/SKILL.md). ## Working Path 1. Identify which service owns the symptom: runner lifecycle, session event persistence, memory ingestion/search, artifact storage, plugin callback order, telemetry export, or code execution. 2. Confirm installation assumptions: `google-adk` 2.3.0, import root `google.adk`, Python 3.10+, and optional extras absent unless installed explicitly. 3. Use in-memory services for focused local tests; switch to persistent services only after checking dependencies, URLs/paths, concurrency, migrations, and credential requirements. 4. Keep event persistence runner-owned: stream events through `Runner.run_async`/`run_live` and let the configured session service append non-partial events. 5. Close long-lived services with `await runner.close()` or `async with Runner(...)` when plugins, toolsets, or database engines need cleanup. ## References And Scripts - [API Reference](references/api-reference.md): constructor signatures, core methods, imports, service contracts, optional extras, and lifecycle notes. - [Service Patterns](references/service-patterns.md): safe recipes for runner setup, persistence choices, plugins, telemetry, memory/artifacts, and code execution. - [Troubleshooting](references/troubleshooting.md): symptom-driven fixes for DB extras, event persistence, plugin callback order, blocking tools, code executors, credentials, and migrations. - [Runtime Services Diagnostic](scripts/check_runtime_services.py): safe local script that prints base runtime imports/signatures and reports optional DB-extra availability without touching databases or credentials. ## Safety Defaults - Prefer `InMemoryRunner` or explicit `Runner(..., session_service=InMemorySessionService())` for examples and unit tests. - Treat `InMemorySessionService`, `InMemoryMemoryService`, and `InMemoryArtifactService` as development/test services, not multi-process production stores. - Do not run destructive migrations or open user databases as a first diagnostic; inspect optional imports and backup plans before migration. - Treat `UnsafeLocalCodeExecutor` and `LocalEnvironment` as high-trust local-only surfaces because model-generated code or shell commands can affect the host. - Do not assume base install includes DB, extension, MCP, GCP, or cloud service dependencies.