Converse API — ADK

API reference for running agent turns on ADK. For architecture and configuration, see ADK.

All paths are relative to the ADK service root (port 8103 locally) under the base path /api/v1/adk. Base URLs, the Authorization and X-Org-Id headers, and the error envelope are described in API conventions, Authentication, Required headers, and Errors.

ADK also accepts these optional headers on authenticated routes:

For normal user tokens, every user_id in a body or query must equal the authenticated user (the token sub or user_id claim); otherwise ADK returns 403. A denied organization or project returns 403, and an unavailable authorization service returns 503.

Endpoints

Session endpoints are documented in the Sessions API.

Sync Converse

POST /api/v1/adk/converse/

Runs one turn against an agent or app and returns when the response is complete. Requires adk.agent.execute.

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sequenceNumber": 1,
  "events": [],
  "response": {"content": "Hello! How can I help?"}
}

If the agent or app version does not exist, ADK returns 404 with {"session_id": null, "response": "No agent with agent id: ... exists."}.

curl -X POST http://localhost:8103/api/v1/adk/converse/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "agent_version": "1.0", "user_id": "YOUR_USER_ID", "query": "What is the weather in London?"}'

Add Event

POST /api/v1/adk/add-event/

Appends an event to an existing session. Chat and Voice use it to complete the caller's own session. Requires authentication.

Returns 404 when the session is not in the caller's organization or belongs to a different app, and 422 when state_delta contains keys callers cannot set.

Direct LLM Call

POST /api/v1/adk/call_llm/

Calls a model directly through LiteLLM with the organization's BYOT credentials, without an agent.

The response is the LiteLLM chat completion object. For azure_ai models, ADK adapts the request to the Azure AI Foundry serverless API (for example, it renames max_tokens where needed and drops stream_options.include_usage).

WebSocket V1

WS /api/v1/adk/converse_stream/

The V1 stream remains for Chat. New clients should use V2.

The handshake requires Authorization: Bearer <token>. A missing or invalid token, or a token without a resolvable user, closes the socket with code 4401. X-Project-Id on the handshake is a fallback; browser clients send project_id in the start body.

start event

ADK resumes the user's latest non-completed session for the same app code, or creates a new one, and replies before agent setup finishes:

{"session_id": "SESSION_ID", "app_code": "agent_AGENT_ID", "user_id": "YOUR_USER_ID", "response": "Conversation Stream Setup"}

query event: {"event": "query", "query": "...", "images": [], "language": "en", "sequenceNumber": 2}. The server streams {"session_id": "...", "response": {"content": "...", "is_final": false}} frames and ends with is_final: true. Errors and cost notices arrive as {"response": "<message>"}. When a session or period cost limit is reached, the socket closes with code 4000.

WebSocket V2

WS /api/v1/adk/converse/v2

The recommended streaming endpoint. It supports client-defined tools, tool approvals, per-request prompt and model overrides, skills, extra knowledge base collections, test sessions, and negotiated voice turns. The handshake requires Authorization and X-Org-Id; X-Project-Id is optional.

Client events

start creates or resumes a session and may carry the first query.

Context window and compaction settings are not client fields; ADK ignores them if sent.

{
  "event": "start",
  "user_id": "YOUR_USER_ID",
  "org_id": "YOUR_ORG_ID",
  "agent_id": "AGENT_ID",
  "agent_version": "1.0",
  "query": "What is the price of AAPL?",
  "tools": [{
    "name": "get_stock_price",
    "description": "Get the current stock price",
    "input_schema": {"type": "object", "properties": {"ticker": {"type": "string"}}, "required": ["ticker"]}
  }]
}

Other client events

Server events

Error codes: INVALID_REQUEST, FORBIDDEN, UNAVAILABLE, MANIFEST_MISMATCH, INVALID_APPROVAL, SESSION_NOT_FOUND, NO_SESSION, SESSION_SCOPE_MISMATCH, SESSION_INIT_FAILED, TURN_BUSY, AGENT_NOT_FOUND, AGENT_ERROR, UNSUPPORTED_TEST_AGENT, NO_LLM_CONFIG, MODEL_UNAVAILABLE, MODEL_TIMEOUT, RATE_LIMITED, CONTEXT_WINDOW_EXCEEDED, PROVIDER_HISTORY_INVALID, HISTORY_UNAVAILABLE, GUARDRAILS_UNAVAILABLE, CONFIGURATION_DRIFT, RESOURCE_UNAVAILABLE, TOOL_APPROVAL_TIMEOUT, PERIOD_COST_LIMIT, SESSION_COST_LIMIT, INTERNAL_ERROR.

Skill Generation

POST /api/v1/adk/skills/generate

Proposes skills from a conversation, an agent prompt, or a description. Requires the skill-generation permission.

The response is {"proposals": [...], "summary": "..."}. Each proposal has name, description, instructions, allowed_tools, resources (references, assets, and scripts maps of file name to content), metadata (cosmos_knowledge_base_ids, category), and rationale.

Async Requests

Async requests run on a Celery worker. All three routes require authentication; non-superusers only see their own requests.

Submit

POST /api/v1/adk/async/requests/ returns 201 with {request_id, status, created_at}. The body takes the Sync Converse fields plus session_id, callback_url, callback_method (GET, POST, PUT, or PATCH; default POST), and callback_headers. ADK returns 400 when neither an agent nor an app is given and 404 when the version does not exist.

Status

GET /api/v1/adk/async/requests/{request_id}/status/

List

GET /api/v1/adk/async/requests/?status=completed&limit=20&offset=0

Query parameters: user_id (must be the caller unless superuser), status, limit (1 to 100, default 20), offset (default 0). The response is {total, limit, offset, requests}, newest first; each item has request_id, status, query, created_at, started_at, completed_at, and session_id.

Health Check

GET /health/ on the service root returns {"status": "ok"} without authentication.