OpenAI Service Client

Source: examples/clients/openai_service_client.py

Introduction

For hosted deployments, OpenAI platform docs and the Responses API capture production invocation behavior, while function-calling guidance clarifies structured tool invocation expectations. This example shows the direct OpenAI service client contract with traceable request/response handling.

Technical Implementation

  1. Configure Tracer with JSONL + console output so each run emits machine-readable traces and lifecycle logs.

  2. Build the runtime surface (public APIs only) and execute OpenAIServiceLLMClient.generate(...) with a fixed request_id.

  3. Construct LLMRequest inputs and call generate through the selected client implementation.

  4. Print a compact JSON payload including trace_info for deterministic tests and docs examples.

        flowchart LR
    A["Input prompt or scenario"] --> B["main(): runtime wiring"]
    B --> C["OpenAIServiceLLMClient.generate(...)"]
    C --> D["LLMRequest/LLMResponse contracts wrap provider behavior"]
    C --> E["Tracer JSONL + console events"]
    D --> F["ExecutionResult/payload"]
    E --> F
    F --> G["Printed JSON output"]
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6from design_research_agents import AzureOpenAIServiceLLMClient, LLMResponse, OpenAIServiceLLMClient, Tracer
 7from design_research_agents.llm import LLMMessage, LLMRequest
 8
 9
10def _build_payload() -> dict[str, object]:
11    assert AzureOpenAIServiceLLMClient.__name__ == "AzureOpenAIServiceLLMClient"
12    # Build the hosted OpenAI client using public runtime APIs, then execute one representative request.
13    with OpenAIServiceLLMClient(
14        name="openai-prod",
15        default_model="gpt-4o-mini",
16        api_key_env="OPENAI_API_KEY",
17        api_key="example-key-for-config-demo",
18        base_url="https://api.openai.com/v1",
19        max_retries=4,
20        model_patterns=("gpt-4o-mini", "gpt-4o-*"),
21    ) as client:
22        description = client.describe()
23        prompt = "In one sentence, when should engineering teams use multi-agent design critique?"
24        response = client.generate(
25            LLMRequest(
26                messages=(
27                    LLMMessage(role="system", content="You are a concise engineering design assistant."),
28                    LLMMessage(role="user", content=prompt),
29                ),
30                model=client.default_model(),
31                temperature=0.0,
32                max_tokens=120,
33            )
34        )
35        llm_call = {
36            "prompt": prompt,
37            "response_text": response.text,
38            "response_model": response.model,
39            "response_provider": response.provider,
40            "response_has_text": bool(response.text.strip()),
41        }
42        response_contract = LLMResponse(
43            text=response.text,
44            model=response.model,
45            provider=response.provider,
46        )
47        return {
48            "client_class": description["client_class"],
49            "default_model": description["default_model"],
50            "llm_call": llm_call,
51            "llm_response_contract_preview": {
52                "model": response_contract.model,
53                "provider": response_contract.provider,
54            },
55            "backend": description["backend"],
56            "capabilities": description["capabilities"],
57            "server": description["server"],
58        }
59
60
61def main() -> None:
62    """Run traced OpenAI service client call payload."""
63    # Fixed request id keeps traces and docs output deterministic across runs.
64    request_id = "example-clients-openai-service-call-001"
65    tracer = Tracer(
66        enabled=True,
67        trace_dir=Path("artifacts/examples/traces"),
68        enable_jsonl=True,
69        enable_console=True,
70    )
71    payload = tracer.run_callable(
72        agent_name="ExamplesOpenAIServiceClientCall",
73        request_id=request_id,
74        input_payload={"scenario": "openai-service-client-call"},
75        function=_build_payload,
76    )
77    assert isinstance(payload, dict)
78    payload["example"] = "clients/openai_service_client.py"
79    payload["trace"] = tracer.trace_info(request_id)
80    # Print the results
81    print(json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=True))
82
83
84if __name__ == "__main__":
85    main()

Expected Results

Run Command

PYTHONPATH=src python3 examples/clients/openai_service_client.py

Example output captured with DRA_EXAMPLE_LLM_MODE=deterministic (timestamps, durations, and trace filenames vary by run):

{
  "backend": {
    "api_key_env": "OPENAI_API_KEY",
    "base_url": "https://api.openai.com/v1",
    "default_model": "gpt-4o-mini",
    "kind": "openai_service",
    "max_retries": 4,
    "model_patterns": [
      "gpt-4o-mini",
      "gpt-4o-*"
    ],
    "name": "openai-prod"
  },
  "capabilities": {
    "json_mode": "prompt+validate",
    "max_context_tokens": null,
    "streaming": false,
    "tool_calling": "best_effort",
    "vision": false
  },
  "client_class": "OpenAIServiceLLMClient",
  "default_model": "gpt-4o-mini",
  "example": "clients/openai_service_client.py",
  "llm_call": {
    "prompt": "In one sentence, when should engineering teams use multi-agent design critique?",
    "response_has_text": true,
    "response_model": "gpt-4o-mini",
    "response_provider": "example-test-monkeypatch",
    "response_text": "Use multi-agent critique when decisions have high risk and need diverse failure analysis."
  },
  "llm_response_contract_preview": {
    "model": "gpt-4o-mini",
    "provider": "example-test-monkeypatch"
  },
  "server": null,
  "trace": {
    "request_id": "example-clients-openai-service-call-001",
    "trace_dir": "artifacts/examples/traces",
    "trace_path": "artifacts/examples/traces/run_20260222T162206Z_example-clients-openai-service-call-001.jsonl"
  }
}

References