Python SDK

The Gumloop Python SDK ships two clients:

Gumloop — the modern resource client used for chat completions, agents, sessions, MCP, skills, artifacts, and teams.
GumloopClient — the legacy flows client used to start saved automations and poll for outputs. Emits a DeprecationWarning at construction.

Pick Gumloop for new code. Use GumloopClient only if you need run_flow against an existing saved automation.

Installation

uv add gumloop

Chat completions

client.chat.completions.create(...) is an OpenAI-compatible chat surface that routes to every model Gumloop supports (Anthropic, OpenAI, Google Gemini, OpenRouter routes). The streaming variant returns an iterator of ChatStreamChunk; the unary variant returns a ChatResult.

model must be a concrete model. gumloop-chew — the Auto router — picks a model instead of being one. Use client.models.route(...) (or POST /models/route) to get the model it would choose, then pass that here. Requires a current gumloop package that includes the models resource.

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

result = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Capital of Canada?"}],
)
print(result.choices[0].message.content)

Streaming

for chunk in client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Write a haiku about Toronto."}],
    stream=True,
):
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Structured output

Pass response_format={"type": "json_schema", "json_schema": {...}} to constrain the response to a JSON Schema. The SDK accepts the same shape the OpenAI API documents.

result = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Return JSON with the capital of Canada."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "answer",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"capital": {"type": "string"}},
                "required": ["capital"],
                "additionalProperties": False,
            },
        },
    },
)
print(result.choices[0].message.content)  # '{"capital":"Ottawa"}'

Image generation

Request an image-generation model such as gpt-image-2.5-flare or gemini-*-image-preview with modalities=["image", "text"]. The response carries image attachments on choices[0].message.images as data URLs. Streaming variants emit partial frames natively for OpenAI gpt-image models.

result = client.chat.completions.create(
    model="gpt-image-2.5-flare",
    messages=[{"role": "user", "content": "A red maple leaf on white"}],
    modalities=["image", "text"],
    image_config={"size": "1024x1024"},
)
for image in result.choices[0].message.images:
    print(image.image_url.url[:64], "...")

Tool calling

Pass OpenAI-shape tool definitions; the SDK forwards them unchanged so any LLM that supports function calling can invoke them.

result = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "What's the weather in Toronto?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
for tc in result.choices[0].message.tool_calls or []:
    print(tc.function.name, tc.function.arguments)

Bring your own provider key

When the calling user has configured their own provider API key (OpenAI, Anthropic, etc.) in Gumloop, billing follows that account’s pricing policy. Usage pricing can waive inference for BYOK; some legacy organizations use a partial discount. See Credits. No SDK change is required.

MCP tools

client.mcp.execute(...) returns an McpExecuteResponse with one result per tool call. MCP execution failures, such as target server authentication errors or upstream connection failures, are reported on each result instead of being raised as APIStatusError. Gumloop request errors, such as missing credentials, invalid request bodies, or endpoint permission failures, can still raise APIStatusError.

from gumloop import APIStatusError, Gumloop

client = Gumloop(access_token="your_access_token")

try:
    response = client.mcp.execute(
        server_id="gumloop_slack",
        tool_name="slack_send_message",
        arguments={"channel": "#general", "text": "Hello from Gumloop"},
    )
except APIStatusError as error:
    print(f"Gumloop API request failed: {error}")
    raise

result = response.results[0]
if result.status != "success":
    print(result.error)
else:
    print(result.decoded_content)

decoded_content is a Python SDK convenience property. Raw REST responses include the underlying content array.

Agent versions

Every agent keeps an immutable history of its configuration. client.agents.list_versions(...) pages through those snapshots newest-first, and client.agents.get_version(...) returns one version’s full configuration plus the structured diff against the version before it.

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

response = client.agents.list_versions("abc123DEFghiJKL", page_size=20)
for version in response.versions:
    print(version.id, version.major_version, version.is_deployed, version.created_at)

detail = client.agents.get_version("abc123DEFghiJKL", response.versions[0].id)
print(detail.version.composition.model_name)
print(detail.version.composition.system_prompt)
print(detail.changes)  # None for the agent's first version

Both calls require configuration access on the agent, and they are read-only — deploying or restoring a version has to happen in the app.

Evaluations

client.agents.list_evaluations(...) pages through an agent’s graded chats newest-first, client.agents.get_evaluation_metrics(...) returns grade and tag counts over a window, and client.agents.run_evaluations(...) queues evaluations for finished sessions. client.agents.get_evaluation_options() lists the criterion types, priorities, and limits the config accepts.

from datetime import datetime, timedelta, timezone

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

since = datetime.now(timezone.utc) - timedelta(days=7)
failed = client.agents.list_evaluations("abc123DEFghiJKL", grade="needs_attention", created_after=since)
for evaluation in failed.evaluations:
    print(evaluation.interaction_id, evaluation.summary)

metrics = client.agents.get_evaluation_metrics("abc123DEFghiJKL", days=30)
print(metrics.grades)

run = client.agents.run_evaluations("abc123DEFghiJKL", session_ids=[e.interaction_id for e in failed.evaluations])
for queued in run.results:
    print(queued.session_id, queued.id)
for skipped in run.skipped:
    print(skipped.session_id, skipped.reason)

Listing and metrics need read access on the agent and cover the chats you can see. Running evaluations needs edit access and consumes one credit per session; pass dry_run=True to see the cost and the sessions that would be skipped (unfinished, or already queued) without queuing anything. Results from an organization evaluation enforced on the agent are listed with list_evaluations(agent_id, organization_evaluation_id=...).

Organization evaluations

client.evaluations manages rubrics an organization admin defines once and applies to teams, people, or individual agents (Enterprise plan, Manage evaluations permission). A new evaluation starts disabled: set its targets, then enable it. Run it over past sessions with run(...); grading is asynchronous, so poll each returned result id.

import time

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

organization_id = client.organizations.list().organizations[0].id

created = client.evaluations.create(
    organization_id=organization_id,
    name="Support tone",
    config={
        "criteria": [
            {"name": "Greets the customer", "prompt": "Did the agent greet the customer by name?", "priority": "needs_review"}
        ]
    },
)
evaluation_id = created.evaluation.id

client.evaluations.set_targets(evaluation_id, [{"type": "team", "id": "team_abc"}])
client.evaluations.update(evaluation_id, enabled=True)

queued = client.evaluations.run(evaluation_id, ["session_1", "session_2"])
for result in queued.results:
    polled = client.evaluations.get_result(evaluation_id, result.id).result
    while polled.status in ("queued", "in_progress"):
        time.sleep(5)
        polled = client.evaluations.get_result(evaluation_id, result.id).result
    print(result.session_id, polled.status, polled.grade)

for result in client.evaluations.list_results(evaluation_id, grade="needs_attention").results:
    print(result.agent_id, result.session_id, result.summary)

client.evaluations.options() returns the allowed values for every enum field (grades, statuses, target types, session types, criterion priorities) and the size limits.

Company Brain

client.brain.search(...) runs a hybrid (semantic + keyword) search across the knowledge sources indexed in your Company Brain and returns ranked results scoped to what you can access. Brain is available on the Pro and Enterprise plans, and each search consumes credits.

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

response = client.brain.search(
    "what is our refund policy?",
    limit=8,                                 # optional, 1–50 (default 8)
    source_type=["notion", "google_drive"],  # optional filter
)
for result in response.results:
    print(result.score, result.source, result.title, result.url)

Each result carries document_id, source, title, content, url, score, updated_at, owner_name, owner_email, parent_title, and metadata. Omit source_type to search every source you can access; valid values are notion, google_drive, slack, github, confluence, direct_file_uploads, and gumloop_artifacts.

Flows (legacy client)

from gumloop import GumloopClient

# Initialize the client
client = GumloopClient(
    api_key="your_api_key",
    user_id="your_user_id"
)

# Run a flow and wait for outputs
output = client.run_flow(
    flow_id="your_flow_id",
    inputs={
        "recipient": "example@email.com",
        "subject": "Hello",
        "body": "World"
    }
)

print(output)

Optionally add a project_id when creating the client if running automations in a workspace:

from gumloop import GumloopClient

# Initialize the client
client = GumloopClient(
    api_key="your_api_key",
    user_id="your_user_id",
    project_id="your_project_id"
)

Core Concepts

SDKs

Agents

Sessions

Skills

Artifacts

MCP

Evaluations

Organization Evaluations

Brain

Teams

Chat completions

Models

File Operations

Enterprise Organization

Installation

Chat completions

Streaming

Structured output

Image generation

Tool calling

Bring your own provider key

MCP tools

Agent versions

Evaluations

Organization evaluations

Company Brain

Flows (legacy client)

​Installation

​Chat completions

​Streaming

​Structured output

​Image generation

​Tool calling

​Bring your own provider key

​MCP tools

​Agent versions

​Evaluations

​Organization evaluations

​Company Brain

​Flows (legacy client)

Installation

Chat completions

Streaming

Structured output

Image generation

Tool calling

Bring your own provider key

MCP tools

Agent versions

Evaluations

Organization evaluations

Company Brain

Flows (legacy client)