Add Responses API example and documentation

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rushitat

README.md

@@ -31,6 +31,7 @@ The Gradient SDK provides clients for:
 * DigitalOcean API
 * Gradient Serverless Inference
 * Gradient Agent Inference
+* **Responses API** — `client.responses` for structured request/response with tools (e.g. GPT 5.2 Pro, 5.1 Codex Max). See `examples/responses_tool_calling.py`.
 
 The full API of this library can be found in [api.md](api.md).
 

examples/responses_tool_calling.py

@@ -0,0 +1,81 @@
+"""
+Example: Responses API with tool (function) calling
+
+Demonstrates using client.responses.create() with a function tool: send a user
+message, handle a function_call in the output, append the function result as
+function_call_output, call create again, and print the final text.
+
+Requires GRADIENT_MODEL_ACCESS_KEY in the environment (e.g. from a .env file).
+"""
+
+import os
+from gradient import Gradient, ResponsesModels
+from gradient.types.responses.response_create_response import ResponseOutputFunctionCall
+
+# Load .env if available (e.g. python-dotenv)
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+MODEL_ACCESS_KEY = os.environ.get("GRADIENT_MODEL_ACCESS_KEY")
+if not MODEL_ACCESS_KEY:
+    raise SystemExit("Set GRADIENT_MODEL_ACCESS_KEY in the environment to run this example.")
+
+client = Gradient(model_access_key=MODEL_ACCESS_KEY)
+
+# One function tool: get_weather
+get_weather_tool = {
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get the current weather for a city.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "city": {"type": "string", "description": "City name"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
+            },
+            "required": ["city"],
+        },
+    },
+}
+
+# Initial conversation: single user message
+input_messages: list[dict] = [
+    {"type": "message", "role": "user", "content": "What's the weather in New York?"},
+]
+
+# First call: model may return a function_call
+response = client.responses.create(
+    model=ResponsesModels.GPT_5_1_CODEX_MAX,
+    input=input_messages,
+    tools=[get_weather_tool],
+    tool_choice="auto",
+)
+
+# If the model returned a function call, append it and the tool result, then call again
+for item in response.output:
+    if isinstance(item, ResponseOutputFunctionCall):
+        input_messages.append({
+            "type": "function_call",
+            "id": item.id,
+            "name": item.name,
+            "arguments": item.arguments,
+        })
+        # Simulated tool result (in a real app you would call your function here)
+        input_messages.append({
+            "type": "function_call_output",
+            "call_id": item.id,
+            "output": '{"temperature": 22, "unit": "celsius", "conditions": "sunny"}',
+        })
+        response = client.responses.create(
+            model=ResponsesModels.GPT_5_1_CODEX_MAX,
+            input=input_messages,
+            tools=[get_weather_tool],
+            tool_choice="auto",
+        )
+        break
+
+print("Assistant:", response.output_text.strip() or "(no text)")

src/gradient/resources/responses/responses.py

@@ -58,7 +58,8 @@ def create(
         Create a response from the Responses API (POST /v1/responses).
 
         Args:
-            model: Model ID (e.g. openai-gpt-5.2-pro).
+            model: Model ID. Use ``ResponsesModels`` (e.g. ``ResponsesModels.GPT_5_2_PRO``)
+                for recommended model IDs.
             input: List of input items: user messages, function_call, function_call_output.
             tools: Optional list of tools the model may call.
             max_output_tokens: Maximum tokens to generate.
@@ -135,7 +136,8 @@ async def create(
         Create a response from the Responses API (POST /v1/responses).
 
         Args:
-            model: Model ID (e.g. openai-gpt-5.2-pro).
+            model: Model ID. Use ``ResponsesModels`` (e.g. ``ResponsesModels.GPT_5_2_PRO``)
+                for recommended model IDs.
             input: List of input items: user messages, function_call, function_call_output.
             tools: Optional list of tools the model may call.
             max_output_tokens: Maximum tokens to generate.