Python types

This page is the type index for the Python SDK; the client, agent, and session objects are documented on RealtimeClient (Python), audio I/O on Audio (Python). Unless a row says otherwise, every name here is a root import: from cosmo_ai import .... The submodules cosmo_ai.tools, cosmo_ai.skills, cosmo_ai.hooks, cosmo_ai.mcp, and cosmo_ai.audio carry the deeper surfaces noted below.

from cosmo_ai import RealtimeClient, TokenSource, AudioConfig, ThinkingLevel
from cosmo_ai import GeminiModel
from cosmo_ai.tools import ClientToolJob

client = RealtimeClient(token=TokenSource.endpoint("https://your-backend.example.com/token"))
agent = client.agent(
    model=GeminiModel(thinking_level=ThinkingLevel.LOW),
    audio=AudioConfig(output=False),
)

Token sources

A TokenSource is the credential shape for distributed apps: it fetches a fresh minted token, caches it, and re-fetches when less than 60 seconds of life remain; a session start rejected with HTTP 401 drops the cache. Pass one as token= to RealtimeClient.

Credential resolution

A zero-argument RealtimeClient() resolves a credential itself. The environment variables involved:

The CredentialsError family reports what went wrong, on the shared .code / .message shape:

Model

model= takes a model id or provider alias as a plain string, or one provider-discriminated block. A knob only exists on the provider that honors it, and the block names the provider itself — the provider tag defaults to the class's value and always serializes, so you never write it — meaning a model that disagrees with its knobs is unrepresentable. All five classes are root imports.

model_id pins the concrete model within the block's provider; leave it unset to run that provider's default, and a model_id belonging to another provider is rejected at session start. RealtimeModel, the union alias that annotates the model= parameter, is also a root import — as is RealtimeModelBlock for the block alone.

ThinkingLevel (Gemini only): MINIMAL / LOW / MEDIUM / HIGH (wire values minimal, low, medium, high).

GrokReasoningEffort (Grok only): HIGH / NONE (wire values high, none).

OpenAILiveReasoningEffort (GPT Live only): MINIMAL / LOW / MEDIUM / HIGH (wire values minimal, low, medium, high). OpenAILiveVerbosity: LOW / MEDIUM / HIGH. OpenAILiveToolChoice: AUTO / REQUIRED / NONE. OpenAILiveServiceTier: AUTO / DEFAULT / FLEX / PRIORITY. All four are root imports.

Tool types

The tools= parameter type is Sequence[AgentTool] — a plain union of the authorable tool classes. WebSearchTool, ExamineImageTool, DetectObjectsTool, PointAtObjectTool, and EndCallTool are zero-config server-tool opt-ins (each carries only its kind; unknown fields are a validation error), all root imports. The deeper authoring surface lives in cosmo_ai.tools:

Session and event types

Supporting types carried on session state and events:

Verification and telephony types

Types resolved by client.verify(), client.mint_token(), and session.dial():

Gemini tool response policies

GeminiToolResponsePolicy(behavior="non_blocking", scheduling="when_idle") lets a tool run while the agent continues speaking. Set GeminiModel.tool_response_policy for the default and tool_response_overrides for a mapping from declared tool names to replacement policies. The default remains blocking. Scheduling accepts when_idle (answer after current speech), silent (absorb without speaking), or interrupt (interrupt speech to answer).

from cosmo_ai import GeminiModel, GeminiToolResponsePolicy

model = GeminiModel(
    model_id="gemini-3.8-live",
    tool_response_overrides={
        "lookup": GeminiToolResponsePolicy(behavior="non_blocking", scheduling="when_idle"),
    },
)

gemini-3.8-live-extended-thinking defaults to non-blocking tools, accepts low, medium or high thinking, and rejects minimal, blocking policies and explicit scheduling. An utterance can finish while the model is still thinking. Use non-blocking tools for independent lookups; keep actions that must finish before further speech blocking on standard Gemini Live. Existing background job tools keep their separate acknowledgement and completion contract.