The Giotto Python SDK provides a high-level interface for Giotto API requests. This reference covers configuration, Responses API requests, deferred requests, orchestration-event streaming, Chat Completions compatibility, and asynchronous usage.
For a minimal end-to-end example, begin with Quick start: Make your first API request with Python.
Feature availability
| Feature | Giotto Cloud | On-prem |
|---|---|---|
| Responses API | Supported | Supported |
| Deferred polling | Supported | Supported |
| Image uploads in Responses requests | Supported | Supported |
| Orchestration-event streaming | Supported | Supported |
| Chat Completions compatibility | Supported | Supported |
| Async client | Supported | Supported |
| Define and deploy agent topologies | Not available | Supported |
| True token-by-token streaming | Not supported | Not supported |
| Embeddings | Not supported | Not supported |
Installation
The SDK requires Python (3.10 or later).
pip install g-client --index-url "https://pip-install:gldt-6Hsbe5WSz3ywYXnEMR_s@gitlab.com/api/v4/projects/80522333/packages/pypi/simple"
Configuration
Environment variables
Environment variables are recommended for local development and deployed applications:
export GIOTTO_BASE_URL="https://cloud.giotto.ai/api" export GIOTTO_KEYCLOAK_BASE_URL="https://cloud.giotto.ai/keycloak" export GIOTTO_REALM="giotto" export GIOTTO_CLIENT_ID="<YOUR_CLIENT_ID>" export GIOTTO_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
from g_client import GiottoClient client = GiottoClient()
Explicit configuration
You can pass settings directly when required:
from g_client import GiottoClient
client = GiottoClient(
base_url="https://cloud.giotto.ai/api",
keycloak_base_url="https://cloud.giotto.ai/keycloak",
realm="giotto",
client_id="<YOUR_CLIENT_ID>",
client_secret="<YOUR_CLIENT_SECRET>",
)Do not hard-code production secrets. Use a secrets manager or environment variables.
Responses API
For a normal text request, the client sends the input to /orch/orchestrate, receives a request_id, and polls /orch/fetch/{request_id} until it receives a terminal event such as request_completed or request_failed. The high-level method handles this polling by default.
Create a response
response = client.responses.create(
model="giotto-alto",
instructions="You are a concise technical assistant.",
input="How do I check whether a Python object is an instance of a class?",
effort="medium",
)
print(response.output_text)The documented reasoning-effort values are medium and high. When omitted, the client uses medium.
Inspect the response
print(response.id) print(response.status) print(response.output_text) print(response.to_dict()) print(response.to_json(indent=2))
Start a request without waiting
started = client.responses.create(
model="giotto-alto",
input="Write a short product description.",
poll=False,
)
print(started.request_id)
completed = client.responses.wait(started.request_id)
print(completed.output_text)Stream orchestration events
stream = client.responses.create(
model="giotto-alto",
input="Compute 123 * 456 using the Python tool.",
stream=True,
)
for event in stream:
print(event.seq, event.kind, event.service_name, event.notes)
completed = stream.get_final_response()
print(completed.output_text)This reports normalized orchestration events, such as model calls, handoffs, tool calls, tool results, and the terminal event. It does not stream generated text token by token.
You can inspect stream.events while iterating and stream.final_response after the terminal event.
Upload an image
Pass an image path using files. The client sends the request as multipart/form-data:
response = client.responses.create(
model="giotto-alto",
input="Describe the attached image.",
files=["bar-chart-example.png"],
)
print(response.output_text)See the image use case for a sample image and a tested question.
Chat Completions compatibility
Use this interface when adapting code that already expects chat completions:
completion = client.chat.completions.create(
model="giotto-alto",
messages=[
{"role": "developer", "content": "Answer concisely."},
{"role": "user", "content": "What is a Python context manager?"},
],
)
print(completion.choices[0].message.content)For new integrations, prefer client.responses.create().
The compatibility layer folds developer and system messages into instructions and serializes user and assistant messages into conversation text before using the same orchestrator flow.
Async client
import asyncio
from g_client import AsyncGiottoClient
async def main() -> None:
async with AsyncGiottoClient() as client:
response = await client.responses.create(
model="giotto-alto",
input="Explain async I/O in one paragraph.",
)
print(response.output_text)
asyncio.run(main())Deferred async request
started = await client.responses.create(
model="giotto-alto",
input="Write a short product description.",
poll=False,
)
completed = await client.responses.wait(started.request_id)
print(completed.output_text)Async event streaming
stream = await client.responses.create(
model="giotto-alto",
input="Compute 123 * 456 using the Python tool.",
stream=True,
)
async for event in stream:
print(event.seq, event.kind, event.service_name, event.notes)
completed = await stream.get_final_response()
print(completed.output_text)On-prem Agents API
Not available on Giotto Cloud. Defining agent graphs, generating backend YAML, and deploying agent topologies are on-prem features. See the on-prem Agents API reference for configuration and deployment details.
Read the on-prem Agents API reference.
Current limitations
- Event streaming is polling-backed orchestration-event streaming, not token-by-token output.
- Embeddings are not currently supported by the Responses API.
- Available tools and models depend on the account or deployed orchestrator.
Comments
0 comments
Please sign in to leave a comment.