First agent

Use Python 3.11 or newer. Create a virtual environment and install the version shown by this documentation:

python3 -m venv .venv
.venv/bin/python -m pip install "zhivex-ai-sdk==0.24.0"

Verify the runtime without a provider

Save this as agent.py and run .venv/bin/python agent.py. The mock model is a Beta evaluation helper; Agent and run_agent are Stable runtime APIs. This example makes no network calls and is executed against the installed wheel when the documentation snapshot is regenerated and verified in CI.

import asyncio

from zhivex_ai import Agent, run_agent
from zhivex_ai.evals import GenerateResult, create_mock_language_model


async def main() -> None:
    model = create_mock_language_model(
        responses=[GenerateResult(text="Ready", finish_reason="stop")]
    )
    result = await run_agent(agent=Agent(name="assistant", model=model), prompt="Check readiness.")
    assert result.text == "Ready"


asyncio.run(main())

Connect a provider

Set OPENAI_API_KEY and ZHIVEX_MODEL in your server environment. Choose a model available to your account. Save the following as live_agent.py and run it with the same Python environment. This example performs a billable model call; the documentation build checks its syntax and public imports without executing it.

import asyncio
import os

from zhivex_ai import Agent, aclose_default_clients, create_openai, run_agent


async def main() -> None:
    try:
        provider = create_openai()
        result = await run_agent(
            agent=Agent(name="assistant", model=provider(os.environ["ZHIVEX_MODEL"])),
            prompt="Give me a short API launch checklist.",
        )
        print(result.text)
    finally:
        await aclose_default_clients()


asyncio.run(main())

Use environment configuration or a secret manager. Keep credentials out of code and browser bundles. For tools, persistence, approvals and limits, continue to Agents and Production.

Optional realtime transport

The default WebSocket transport now requires the realtime extra:

.venv/bin/python -m pip install "zhivex-ai-sdk[realtime]==0.24.0"

Realtime remains Experimental. Ordinary text and agent applications do not need this extra. The Beta zhivex init CLI can scaffold a durable application; its generated code still needs application-owned authorization and storage policy.