ADK (Agent Development Kit)

The ADK service (cosmos-adk-v3) is the agent execution engine of the Cosmos platform. Built on FastAPI and Google ADK 2.13, it runs agents, manages conversation sessions, generates skills, and streams responses. It integrates with MCP for tools and supports multi-agent hierarchies, guardrails, client-side tool execution, test sessions, and real-time streaming.

Why It Matters

Every agent turn in Cosmos, whether it starts in the Frontend, Chat, Voice, Cosmos Code, or a consumer app such as JumpStart, is executed by ADK. ADK is the one place that assembles an agent's tools, skills, guardrails, and prompt into a runnable Google ADK agent, and the one place that enforces per-turn identity, project scope, PII masking, content filtering, cost limits, and rate limits before an LLM call happens.

Architecture

V1 and V2 share core modules: agent_builder (recursive multi-agent tree construction), app_factory (App and Runner factory with plugins), client_proxy_toolset (client-side tool execution), skill_manager (Configurator skills to ADK SkillToolset), image_utils (DMS image resolution), and pii_utils (streaming PII demasking).

Agent turn flow: ADK authenticates the caller, checks that the requested user_id matches the token subject, authorizes adk.agent.execute against the organization (or against the project when a project ID is supplied), loads the agent, app, or prompt-only configuration, resolves MCP tools, attaches client-defined tools and skills, builds the Google ADK runner, and streams protocol events back to the caller. Fatal setup or runtime errors are sent as error events with fatal: true before the WebSocket closes.

Plugin pipeline

app_factory.build_app() registers plugins in this order (some only when their feature is configured):

Key Capabilities

• V2 streaming protocol: per-request model overrides, client-defined tools with callback execution, tool approvals, mid-conversation tool updates, multi-agent hierarchies, test sessions, negotiated voice turns (cosmos.voice.v2, required for channel: voice), and PII streaming demasking. See the Converse API.
• Guardrails: app-level PII configuration and content filtering, with agent-level content filter overrides. Prompt-only V2 sessions can opt in to the organization default guardrails with use_org_default_guardrails.
• Client-side tool execution: ClientProxyToolset turns client JSON Schema tool definitions into ADK function tools, sends tool_call events, and waits for tool_result (120 seconds by default; V2 clients can set client_tool_timeout_seconds up to 3600). Pending calls are cancelled on disconnect.
• Tool approvals: tools configured with requires_approval in Configurator pause the turn with an approval_required event. The client answers with approval_decision; no answer within 300 seconds denies the call.
• Skills: Google ADK SkillToolset with progressive disclosure (list_skills, load_skill, load_skill_resource, run_skill_script). Skills can be attached per request in the V2 start event, and metadata.cosmos_knowledge_base_ids loads the referenced knowledge base collections.
• Skill generation: POST /api/v1/adk/skills/generate proposes reusable skills from a conversation, an agent prompt (including sub-agents), or a free-text description.
• Context window and compaction: ADK alone owns these settings; clients do not send them. The window is the root agent's context_window_tokens (minimum 8192) or the model's standard window from provider_capabilities.yaml, capped at the model maximum, with 128K for unknown models. The input window reserves the smaller of the maximum output tokens and half the window. Compaction starts at 80 percent of the input window unless the agent sets token_threshold, and the budget guard blocks at 85 percent. Compaction interval, overlap, invocations to keep, and event retention (default 30) come from the agent configuration. Clients can also request compaction with POST /sessions/{session_id}/compact.
• Prompt caching (Anthropic-family models): per-agent prompt_caching (system prompt breakpoint) and prompt_caching_history (history-tail breakpoint, 1 hour TTL). A null value means on. The PROMPT_CACHING_ENABLED master switch, plus PROMPT_CACHING_SYSTEM_ENABLED and PROMPT_CACHING_HISTORY_ENABLED, control the feature per environment.
• Dynamic thinking: when an agent sets dynamic_thinking_enabled and CLASSIFIER_ROUTING_ENABLED is on, ADK classifies each query through cosmos-classifier-v3 (/v1/classify, 1.5 second timeout) and picks a thinking mode and reasoning effort within the model's limits. Classifier failures keep the saved configuration.
• Headroom compression: an optional compression proxy for Anthropic and Azure Claude providers. It applies only when the agent sets headroom_compression_enabled: true and HEADROOM_ROUTING_ENABLED is on. It is independent of prompt caching.
• Project scope: callers can send X-Project-Id (or project_id in a V1 or V2 start body). ADK authorizes the project, stores it as the server-owned session scope, and forwards it to MCP as X-Project-Id so tools such as knowledge_base authorize each target against the project.
• Test sessions: AI Testing Workspace sessions start with a test_session selection, store an immutable snapshot, expose redacted traces, and support evaluation (POST /sessions/{session_id}/evaluate, enabled by ADK_TEST_EVALUATE_ENABLED=true). See the Sessions API.
• Evaluation and analyzer runs: eval-agent/*, reviews/*, evals/experiments/*, and evals/agents/{id}/auto-setup/ routes run analyzers, experiments, and review workflows.

API Overview

→ Full API reference: ADK API

Configuration

The server.py entrypoint dispatches on the mode environment variable: webserver (default, FastAPI and Uvicorn), celery, background_job, or consumer. In Kubernetes every mode runs under opentelemetry-instrument, which exports traces to Azure Monitor (Application Insights) through APPLICATIONINSIGHTS_CONNECTION_STRING. The image installs dependencies into /app/.venv.

Key dependencies: google-adk 2.13.0 (installed from a compatibility wheel with widened OpenTelemetry bounds), fastapi 0.141.1, litellm 1.103.8, mcp 2.x, SQLAlchemy 2.0.43, celery 5.6.0, PyJWT 2.15.0, faster-whisper 1.2.1, and azure-monitor-opentelemetry 1.8.11.

Supported LLM providers: google_ai, vertex_ai, azure_openai, azure_claude, aws_claude, azure_ai (Azure AI Foundry serverless models), smallest_ai, and inhouse. Model credentials come from the organization's BYOT configuration in Configurator.

Data Model

Sessions and events are stored in PostgreSQL through the Google ADK database session service. Sessions are keyed by (app_name, user_id, id), where app_name is the app code (agent_<uuid> or app_<uuid>, with hyphens replaced by underscores). Events belong to a session and carry content, usage metadata, and turn markers. Async requests and analyzer runs have their own tables. See the Sessions API for the exposed shapes.

Integration Points

Troubleshooting

• "No agent with agent id" error: verify the agent version exists in Configurator (GET /api/v1/agents/<id>/versions/) and that ADK can reach CONFIGURATOR_SERVICE_URL.
• MCP tools not loading: check the service OAuth variables (COSMOS_SERVICE_CLIENT_ID, COSMOS_SERVICE_CLIENT_SECRET) and MCP health (curl http://localhost:8102/health/). Re-provision with ./manage.sh dev setup-tokens if needed.
• V1 WebSocket closes with 4401 or 4403: the handshake needs a valid bearer token (4401), and the token must be authorized for the organization in the start event (4403).
• Voice start rejected with INVALID_REQUEST: V2 voice sessions must send voice_protocol: "cosmos.voice.v2".
• Kafka consumer not processing events: check docker logs cosmos-dev-adk-consumer, confirm Kafka is running, and restart with ./manage.sh dev restart adk-consumer.
• PII masking not working: confirm PII is enabled in the app's guardrails and that PII_REDACTOR_SERVICE_URL is reachable.
• Rate limiting errors: check provider_rate_limits in organization settings and the Redis sliding window (redis-cli KEYS "cosmos:rate_limit:tpm:*").

Changelog

See ADK Changelog for verified documentation and service-surface changes.