Ogx Client Python Library

The Interactive Agent CLI uses AgentEventLogger to visualize the lifecycle of an agent interaction. When running the CLI, you can observe:

• Turn lifecycle: The transition from TurnStarted to TurnCompleted.
• Inference steps: Visual indicators of when the model is actively thinking or generating text.
• Tool execution steps: Real-time updates when server-side tools (e.g., knowledge_search or file_search) are being executed.
• Step metadata: Information regarding whether tools are being executed server_side or client_side.
• Real-time streaming: Text generation appearing as it happens.

List methods are paginated. The library provides two ways to handle this:

1. Auto-pagination: Use the returned iterator to automatically fetch subsequent pages as you iterate.
2. Manual pagination: Use .has_next_page(), .next_page_info(), or .get_next_page() for granular control over page fetching.

# Auto-pagination (Sync)
for response in client.responses.list():
    print(response)

# Auto-pagination (Async)
async for response in client.responses.list():
    print(response)

# Manual pagination (Async)
first_page = await client.responses.list()
if first_page.has_next_page():
    next_page = await first_page.get_next_page()

In API responses, a field that is explicitly null or missing entirely will both result in None in the library. To distinguish between them, check if the field name exists in the .model_fields_set attribute of the response model.

if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.')
  else:
    print('Got json like {"my_field": null}.')

Install the pre-release version of the ogx_client library from PyPI using pip.

pip install '--pre ogx_client'

Use OgxClient for synchronous API calls. You can provide an api_key as a keyword argument, but it is recommended to set the OGX_CLIENT_API_KEY environment variable in a .env file to avoid storing secrets in source control.

from ogx_client import OgxClient

client = OgxClient()

models = client.models.list()

For asynchronous applications, import AsyncOgxClient and await your API calls. The functionality is identical to the synchronous client.

import asyncio
from ogx_client import AsyncOgxClient

client = AsyncOgxClient()

async def main() -> None:
    models = await client.models.list()

asyncio.run(main())

The library uses the standard Python logging module. You can enable logging by setting the OGX_CLIENT_LOG environment variable to info or debug (for more verbose output).

$ export OGX_CLIENT_LOG=info

The library closes connections automatically when the client is garbage collected. However, for better resource management, you should manually close the client using .close() or use the client as a context manager.

from ogx_client import OgxClient

with OgxClient() as client:
  # make requests here
  ...

# HTTP client is now closed

By default, the async client uses httpx. To use aiohttp for improved concurrency performance, install the aiohttp extra and pass DefaultAioHttpClient() to the client constructor.

pip install '--pre ogx_client[aiohttp]'

import asyncio
from ogx_client import DefaultAioHttpClient
from ogx_client import AsyncOgxClient

async def main() -> None:
    async with AsyncOgxClient(
        http_client=DefaultAioHttpClient(),
    ) as client:
        models = await client.models.list()

asyncio.run(main())

You can customize the underlying httpx client by passing a DefaultHttpxClient to the OgxClient constructor. This allows you to configure proxies, custom transports, and base URLs. You can also apply per-request configurations using .with_options().

import httpx
from ogx_client import OgxClient, DefaultHttpxClient

client = OgxClient(
    # Or use the `OGX_CLIENT_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# Per-request customization
client.with_options(http_client=DefaultHttpxClient(...))