Sign in

Python SDK — Test ADK Agents

End-to-end Python SDK smoke test for authenticating, resolving service URLs, and calling a deployed ADK agent

sdkpythonadktestingsmoke-testonboarding

Updated 2026-11-03

Verified 2026-11-03

Use this guide when a new developer wants to verify that Python can authenticate with Cosmos and call a deployed ADK agent.

The most common first-test failures are configuration issues:

  • COSMOS_GATEWAY_URL is pointed at one service host, usually ADK.
  • Python cannot validate the local corporate/internal certificate chain.
  • ADK receives an arbitrary user_id such as user-123 instead of the authenticated Cosmos user id from the token.

Prerequisites

  • Python 3.10 or later.
  • cosmos-sdk-python installed.
  • A Cosmos user that can access the target organization.
  • A deployed agent id and agent version.
  • Direct service URLs for User Service, Configurator, and ADK, or one real gateway URL that routes all service prefixes.

Install

bash
pip install git+https://github.com/ey-org/cosmos-sdk-python.git@develop
pip install python-dotenv

Configure .env

Prefer direct service URLs when the deployment exposes service-specific hosts.

bash
COSMOS_EMAIL=user@example.com
COSMOS_PASSWORD=your-password
COSMOS_ORG_ID=your-org-uuid

COSMOS_USER_SERVICE_URL=https://user.example.com
COSMOS_CONFIGURATOR_SERVICE_URL=https://configurator.example.com
COSMOS_ADK_SERVICE_URL=https://adk.example.com
COSMOS_STORAGE_SERVICE_URL=https://storage.example.com

COSMOS_AGENT_ID=your-agent-uuid
COSMOS_AGENT_VERSION=1.0

COSMOS_VERIFY_TLS=true

COSMOS_STORAGE_SERVICE_URL is optional for a simple ADK call, but most real integrations use Storage/DMS soon after the first smoke test.

If your deployment provides one real gateway instead of direct service hosts, set COSMOS_GATEWAY_URL and omit the direct service URL variables.

Service URL Rules

Use COSMOS_GATEWAY_URL only for a real gateway that routes service prefixes:

bash
COSMOS_GATEWAY_URL=https://cosmos.example.com/cosmos

The SDK derives:

text
user         -> https://cosmos.example.com/cosmos/user
configurator -> https://cosmos.example.com/cosmos/configurator
adk          -> https://cosmos.example.com/cosmos/adk

Do not set COSMOS_GATEWAY_URL to one service host such as https://adk.example.com. That makes the SDK derive invalid URLs like https://adk.example.com/user.

When in doubt, set the direct service URLs and do not set COSMOS_GATEWAY_URL.

Smoke Test Script

Create test_adk.py:

python
import asyncio
import os

from dotenv import load_dotenv

from cosmos_sdk import CosmosClient, build_service_endpoints_from_env


load_dotenv()


def env_bool(name: str, default: bool = True) -> bool:
    value = os.getenv(name)
    if value is None:
        return default
    return value.strip().lower() not in {"0", "false", "no", "off"}


async def main() -> None:
    services = build_service_endpoints_from_env()
    gateway_url = os.getenv("COSMOS_GATEWAY_URL") or None
    if not gateway_url:
        missing = sorted({"user", "configurator", "adk"} - services.keys())
        if missing:
            raise RuntimeError(f"Missing service URL env vars for: {', '.join(missing)}")

    client = await CosmosClient.from_credentials(
        os.environ["COSMOS_EMAIL"],
        os.environ["COSMOS_PASSWORD"],
        org_id=os.environ["COSMOS_ORG_ID"],
        services=services,
        gateway_url=gateway_url,
        verify_tls=env_bool("COSMOS_VERIFY_TLS", True),
    )

    try:
        claims = client.auth.decode_token()
        conversation_user_id = claims.sub or claims.user_id
        if not conversation_user_id:
            raise RuntimeError("Could not resolve user id from access token")

        result = await client.adk.converse(
            query="What can this agent help with?",
            user_id=conversation_user_id,
            agent_id=os.environ["COSMOS_AGENT_ID"],
            agent_version=os.getenv("COSMOS_AGENT_VERSION", "1.0"),
            channel="chat",
        )

        print(result["response"]["content"])
        print("Session:", result["session_id"])
    finally:
        await client.close()


asyncio.run(main())

Run:

bash
python test_adk.py

Existing Token Variant

Use this when your application already has a Cosmos access token.

python
client = CosmosClient.from_token(
    os.environ["COSMOS_ACCESS_TOKEN"],
    org_id=os.environ["COSMOS_ORG_ID"],
    services=services,
    verify_tls=env_bool("COSMOS_VERIFY_TLS", True),
)

claims = client.auth.decode_token()
conversation_user_id = claims.sub or claims.user_id

Pass the same conversation_user_id to ADK calls.

Expected Output

A successful call prints the agent response and a session id:

text
I can help with ...
Session: 4b7e...

ADK creates and reuses sessions by user_id plus agent/app identity.

Troubleshooting

ErrorLikely CauseFix
No URL configured for service "user"Missing COSMOS_USER_SERVICE_URL, and no real COSMOS_GATEWAY_URL was provided.Add direct service URLs or a real gateway URL.
Login calls https://adk.../userCOSMOS_GATEWAY_URL points at the ADK host.Remove COSMOS_GATEWAY_URL; set COSMOS_ADK_SERVICE_URL and the other direct service URLs.
CERTIFICATE_VERIFY_FAILEDPython does not trust the local corporate/internal CA chain.Install the root CA into Python's trust store. For local smoke tests only, set COSMOS_VERIFY_TLS=false.
Token user is not authorized for the requested conversation userADK user_id does not match the authenticated user id in the token.Decode the token and use claims.sub or claims.user_id. Do not use email or user-123.
Token is not authorized to execute ADK agentLogin worked, but the user lacks permission for the target agent/app.Grant the user access to the agent/app or test with an authorized account.

Next Steps