OpenAIProvider#

Connect a provider and configure retries, credentials, and transport. See the guide.

class zett_agent.providers.openai.OpenAIProvider(model, api_key, transport=None, *, base_url=None, temperature=None, response=False, retry=RetryOptions(base_delay=0.25, max_delay=8.0, max_retries=3), send_prompt_cache_key=True, extra_headers=None, extra_query=None, extra_body=None, timeout=TimeoutOptions(connect=5.0, first_byte=60.0, idle=600.0))[source]#

Map OpenAI-compatible chat streams to provider-neutral model events.

Parameters:

  • model (str) – Model identifier understood by the configured endpoint.

  • api_key (str) – API credential supplied by the application.

  • transport (httpx.AsyncBaseTransport | None) – Optional HTTPX transport, useful for isolated tests.

  • base_url (str | None) – Compatible API root; None uses the official OpenAI v1 endpoint.

  • temperature (float | None) – Optional sampling temperature passed to the provider.

  • response (bool) – Use the Responses API instead of Chat Completions.

  • retry (RetryOptions) – Exponential backoff applied before the first emitted event only.

  • timeout (TimeoutOptions) – How long the provider may stay silent before the request is given up on: connecting, waiting for the response headers, and between chunks of a response that has started. See TimeoutOptions; a timeout raises ProviderTimeoutError and is not retried.

  • send_prompt_cache_key (bool) – Declare the run’s prompt cache key on every request. Disable it when a compatible endpoint rejects the field.

  • extra_headers (Mapping[str, str] | None) – HTTP headers sent on every request after the adapter’s own, for gateways that route or bill on a header. A header given here replaces the SDK default of the same name.

  • extra_query (Mapping[str, str] | None) – URL query parameters sent on every request, such as the api-version an Azure-style endpoint requires.

  • extra_body (Mapping[str, Any] | None) – JSON fields merged into every request body last, so they add a vendor option the adapter does not model and may override one it does.

Note

Await aclose() when finished. Model capabilities determine support for images, tool choice, and reasoning effort; this adapter does not infer unsupported features from the model name alone.

Examples

Read credentials from the environment and close the client explicitly:

import os

model = OpenAIProvider(
    model=os.environ.get("OPENAI_MODEL", "gpt-5-mini"),
    api_key=os.environ["OPENAI_API_KEY"],
    retry=RetryOptions(max_retries=3),
)
try:
    client = await create_agent(model)
    reply = await client.run("Summarize this module")
finally:
    await model.aclose()

Note

The default HTTP client honors HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY from the process environment.

Note

Both protocols declare prompt_cache_key from cache_key, so each conversation keeps a stable prefix for provider-side prompt caching. Reported cache hits are normalized into cache_read_tokens.

See also

Connect a model provider covers credentials and transport ownership; RetryOptions controls retries before output starts.

async aclose()#

Close the SDK’s owned HTTP connection pool.

Return type:

None

native_deferred_tools: bool = False#

See zett_agent.model.NativeDeferredToolsModel.native_deferred_tools. A provider opts in by overriding this on its class; the default keeps Responses, Chat Completions, Google, and Ollama on the withhold-and-search path.

response: bool = False#

Whether this adapter uses a Responses-style endpoint instead of its provider’s traditional message or chat-completions endpoint. Only the providers read it; the runtime does not.

sync(*, runtime=None)#

Return a context-managed synchronous view; optionally share a runtime.

Omitting runtime creates a new background thread for this view. Passing an existing runtime reuses its loop and leaves its shutdown to the caller. This API is for service entry points, not Extension lifecycle hooks.

Examples

Use a model or tool from a plain function:

with read_file.sync() as read:
    result = read({"path": "README.md"})
Parameters:

runtime (SyncRuntime | None)

Return type:

SyncObject[Self]