Python SDK - Gumloop

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 configuration

Everything the agent panel can set is available through client.agents. create takes the whole configuration in one call. After that, settings change through update, and each collection has its own attach/detach pair so one item changes without re-sending the rest.

from gumloop import Gumloop

client = Gumloop(access_token="your_access_token")

agent = client.agents.create(
    name="Support triage",
    model_name="anthropic/claude-sonnet-4",
    system_prompt="Triage incoming tickets and draft replies.",
    skill_ids=["skill_2b9c"],
    knowledge_sources=[{"connector_id": "PFqdAMir8PA2Xc6qcszSN9"}],  # omit config for the whole source
    metadata={"fallback": {"enabled": True}, "max_steps": 30},
).agent

client.agents.attach_mcp_server(agent.id, "gmail", approval_mode="write", restricted_tools=["send_email"])
client.agents.update_abilities(agent.id, web_search={"enabled": True, "provider": "exa"}, ask_question={"enabled": False})
client.agents.attach_subagent(agent.id, "xyz789MNOpqrSTU")
client.agents.create_trigger(agent.id, type="schedule", prompt="Morning digest", cron_expression="0 9 * * 1-5")

One retrieve returns the whole agent: tools, metadata, abilities, skill_ids, knowledge_sources, triggers and version. Pass that version back on update and the call fails with agent_version_conflict if someone else saved the agent in between; leave it out and the last write wins.

agent = client.agents.retrieve(agent.id).agent
client.agents.update(agent.id, version=agent.version, metadata={"voice": {"enabled": True}})

A webhook trigger’s URL embeds its secret. It comes back once on create_trigger and from get_trigger_webhook_url, never in list_triggers or retrieve. delete removes a custom agent; gumball and analytics can be read and chatted with but not configured.

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.

Sources and files

Create file-upload sources and put files into them. Only direct_file_uploads sources can be created through the SDK; connected sources are set up in the app.

source = client.brain.create_source("Engineering docs").source            # personal, active
# client.brain.create_source("Runbooks", scope="team", team_id="...")
# client.brain.create_source("Policies", scope="organization", require_approval=True)

upload = client.brain.upload_files(source.id, {"handbook.pdf": open("handbook.pdf", "rb").read()})
print([f.status for f in upload.files], upload.rejected)                    # indexing starts on its own

for f in client.brain.list_files(source.id).files:
    print(f.file_name, f.status, f.sha256)                                  # uploaded → indexing → indexed

client.brain.delete_file(source.id, upload.files[0].id)
client.brain.delete_source(source.id)

list_sources(scope=..., source_type=..., team_id=..., page_size=..., cursor=...) and get_source(id) read sources of every type. A source created with require_approval=True is a draft: get_estimate(id).estimate.estimated_credits shows the cost once estimate.status is paused_for_approval, and approve_source(id) starts indexing. Every file’s sha256 lets you diff a local folder against a source; the CLI’s gumloop brain sync does exactly that.

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"
)

​Installation

​Chat completions

​Streaming

​Structured output

​Image generation

​Tool calling

​Bring your own provider key

​MCP tools

​Agent configuration

​Agent versions

​Evaluations

​Organization evaluations

​Company Brain

​Sources and files

​Flows (legacy client)

Installation

Chat completions

Streaming

Structured output

Image generation

Tool calling

Bring your own provider key

MCP tools

Agent configuration

Agent versions

Evaluations

Organization evaluations

Company Brain

Sources and files

Flows (legacy client)