Python SDK - SketricGen Docs

Overview

The sketricgen Python package provides one typed SketricGenClient for the Runtime API and the supported Admin API operations. Use it to run agents, stream responses, attach files, handle human-in-the-loop (HITL) pauses, browse Teamspace resources, and manage Brand Agents and connectors. SDK version 0.3.0 removed the separate AdminClient. The same client now routes runtime and management calls to the correct API.

Requirements

Python 3.9 or later
sketricgen>=0.3.0
A Teamspace API key beginning with sk_api_

Create the key from Teamspace settings → API keys → Create key. Enable Run agents for workflow calls, Manage resources for control-plane calls, or both for the complete SDK surface. Project scope, agent restrictions, and management role still apply.

Installation

pip install --upgrade "sketricgen>=0.3.0"

Or with another package manager:

uv add "sketricgen>=0.3.0"

poetry add "sketricgen>=0.3.0"

Configure the client

Set the single supported API-key environment variable:

export SKETRICGEN_API_KEY="sk_api_YOUR_KEY"

Then create one client for runtime and management operations:

from sketricgen import SketricGenClient

client = SketricGenClient.from_env()

You can also pass the key directly:

client = SketricGenClient(
    api_key="sk_api_YOUR_KEY",
    timeout=30,
    upload_timeout=300,
    max_retries=3,
)

Environment variable	Default	Description
`SKETRICGEN_API_KEY`	Required	Teamspace API key used for every SDK operation
`SKETRICGEN_TIMEOUT`	`300`	Runtime request timeout in seconds
`SKETRICGEN_UPLOAD_TIMEOUT`	`300`	File-upload timeout in seconds
`SKETRICGEN_MAX_RETRIES`	`3`	Maximum retry attempts

SKETRICGEN_RUNTIME_API_KEY, SKETRICGEN_ADMIN_API_KEY, and AdminClient are not supported in version 0.3.0. Replace them with SKETRICGEN_API_KEY and SketricGenClient.

Run an agent

Async

response = await client.run_workflow(
    agent_id="agent-123",
    user_input="Summarize the latest project updates.",
)

print(response.response)
print(response.conversation_id)

Sync

response = client.run_workflow_sync(
    agent_id="agent-123",
    user_input="Summarize the latest project updates.",
)

print(response.response)

Both methods accept the same arguments:

response = await client.run_workflow(
    agent_id,
    user_input="",
    conversation_id=None,
    contact_id=None,
    file_paths=None,
    stream=False,
    enable_hitl=False,
    hitl_resume=None,
)

user_input is required unless the request resumes a HITL pause or includes at least one file. Its maximum length is 10,000 characters.

Stream a response

run_workflow(..., stream=True) returns an async iterator. The synchronous method returns a regular iterator.

import json

async for event in await client.run_workflow(
    agent_id="agent-123",
    user_input="Draft a launch plan.",
    stream=True,
):
    data = json.loads(event.data)

    if data["type"] == "TEXT_MESSAGE_CONTENT":
        print(data["delta"], end="", flush=True)

    if event.is_terminal:
        break

The SDK marks RUN_FINISHED, RUN_ERROR, and RUN_PAUSED_HITL as terminal through event.is_terminal.

Event type	Meaning
`RUN_STARTED`	The workflow started
`TEXT_MESSAGE_START`	An assistant message started
`TEXT_MESSAGE_CONTENT`	A text chunk arrived
`TEXT_MESSAGE_END`	The assistant message ended
`TOOL_CALL_START`	A tool call started
`TOOL_CALL_END`	A tool call ended
`CUSTOM_EVENT`	A custom event; `deep_agents_hitl` carries pending HITL details
`RUN_PAUSED_HITL`	The run paused for a human decision
`RUN_FINISHED`	The run completed
`RUN_ERROR`	The run failed

Handle human-in-the-loop requests

HITL is opt-in. Set enable_hitl=True on the initial request and every resume request where the agent may pause for an answer, approval, or rejection.

from sketricgen import HitlDecision, HitlResume, SketricGenClient

client = SketricGenClient.from_env()

paused = await client.run_workflow(
    agent_id="agent-123",
    user_input="Prepare the campaign and ask for approval before scheduling it.",
    enable_hitl=True,
)

if paused.run_paused_hitl and paused.hitl_request:
    request = paused.hitl_request

    # Render request.action_requests and honor each corresponding
    # request.review_configs entry before collecting decisions.
    resumed = await client.run_workflow(
        agent_id="agent-123",
        conversation_id=paused.conversation_id,
        enable_hitl=True,
        hitl_resume=HitlResume(
            request_id=request.request_id,
            decisions=[HitlDecision(type="approve")],
        ),
    )

Each decision must use a type allowed by the corresponding review_configs entry:

Decision	Payload	Use it for
Respond	`HitlDecision(type="respond", message="October 15")`	Answering a requested question
Approve	`HitlDecision(type="approve")`	Allowing a proposed action
Reject	`HitlDecision(type="reject")`	Declining a proposed action

For multiple pending actions, provide one decision per action in the same order as hitl_request.action_requests. Resume on the same conversation_id, include the returned request_id, and do not send a new user_input. A resumed run can pause again. For streaming runs, capture the deep_agents_hitl custom event and stop when RUN_PAUSED_HITL arrives. Resume with a new run_workflow() call using the same typed HitlResume payload.

Attach files

Pass one or more local paths through file_paths. The SDK uploads them in parallel, registers the resulting assets, and includes them in the workflow request.

response = await client.run_workflow(
    agent_id="agent-123",
    user_input="Compare the report with the source data.",
    file_paths=[
        "/path/to/report.pdf",
        "/path/to/source.csv",
        "/path/to/notes.md",
    ],
)

Each file can be up to 20 MB.

Supported file types

Category	Extensions
Images	`.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`
Documents and data	`.pdf`, `.csv`, `.xls`, `.xlsx`, `.json`, `.xml`, `.yaml`, `.yml`, `.txt`, `.md`, `.markdown`, `.html`, `.htm`
Web source	`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.css`, `.scss`, `.sass`, `.less`, `.vue`, `.svelte`
Application source	`.py`, `.pyw`, `.pyi`, `.rb`, `.php`, `.java`, `.kt`, `.kts`, `.go`, `.rs`, `.swift`, `.scala`, `.sc`, `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hpp`, `.cs`, `.fs`, `.fsx`, `.sql`
Shell and scripting	`.sh`, `.bash`, `.zsh`, `.ps1`, `.bat`, `.cmd`, `.r`, `.dart`, `.ex`, `.exs`, `.erl`, `.hrl`, `.clj`, `.cljs`, `.lua`, `.pl`, `.pm`, `.rkt`, `.zig`, `.nim`, `.odin`
Configuration and build text	`.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.env`, `.gitignore`, `.dockerignore`, `.gradle`, `.cmake`, `.mk`, `.makefile`, `.vim`

An unsupported type raises SketricGenContentTypeError; an oversized file raises SketricGenFileSizeError.

Use the control plane

Management operations use namespaces on the same SketricGenClient. The API key must have Manage resources access.

Identify the Teamspace

teamspace = await client.whoami()
print(teamspace.teamspace_id, teamspace.display_name)

teamspace = client.whoami_sync()

List scoped resources

Project, agent, and knowledge-base lists transparently follow pagination. They fetch pages lazily as you consume the iterator.

async for project in client.projects.list():
    print(project.project_id, project.display_name)

async for agent in client.agents.list():
    print(agent.agent_id, agent.name)

async for knowledge_base in client.knowledge_bases.list():
    print(knowledge_base.knowledge_base_id, knowledge_base.name)

Use list_sync() on each namespace for synchronous iteration.

Manage Brand Agents

# Start provisioning and wait for a terminal result.
job = await client.brand_agents.create_and_wait(
    name="Acme Support",
    seed_url="https://example.com",
    poll_interval=10,
    timeout=600,
)

# Inspect and update an existing Brand Agent.
agent = await client.brand_agents.get("skbrand_123")
await client.brand_agents.update(
    "skbrand_123",
    display_name="Acme Assistant",
    instructions="Answer concisely.",
)

# Read and update its widget configuration.
widget = await client.brand_agents.get_widget_config("skbrand_123")
await client.brand_agents.update_widget_config(
    "skbrand_123",
    primary_color="#0055FF",
)

The namespace also provides list_templates(), create(), and get_status(). Every async method has a synchronous _sync variant.

Manage connectors

connectors = await client.connectors.list()
tools = await client.connectors.list_tools("gmail")

link = await client.connectors.create_link("gmail", project_id="project-123")
print(link.connect_url)

status = await client.connectors.check_connection(
    "gmail",
    project_id="project-123",
)

await client.connectors.attach(
    "agent-123",
    "gmail",
    allowed_tools=["send_email"],
)
await client.connectors.detach("agent-123", "gmail")

Connector methods also have synchronous _sync variants. Opening the hosted connection link and completing external authorization remains a human step.

Response models

`ChatResponse`

Field	Type	Description
`agent_id`	`str`	Agent ID
`user_id`	`str`	User identifier
`conversation_id`	`str`	Conversation ID for follow-up or resume requests
`response`	`str`	Assistant response text
`owner`	`str`	Agent owner
`error`	`bool`	Whether the response represents an error
`assets`	`list[Asset]`	Assets returned by the run
`run_paused_hitl`	`bool`	Whether the run paused for a human decision
`hitl_request`	`HitlRequest	None`	Typed pause metadata used to render and resume HITL
`run_halted_out_of_credits`	`bool`	Whether the run stopped because credits were unavailable

`StreamEvent`

Field	Type	Description
`event_type`	`str`	Server-Sent Events envelope type
`data`	`str`	JSON event payload
`id`	`str	None`	Optional event ID
`is_terminal`	`bool`	Whether the run finished, failed, or paused for HITL

Error handling

from sketricgen import (
    SketricGenAdminError,
    SketricGenAuthenticationError,
    SketricGenContentTypeError,
    SketricGenError,
    SketricGenFileSizeError,
    SketricGenJobError,
)

try:
    response = await client.run_workflow(
        agent_id="agent-123",
        user_input="Analyze this file.",
        file_paths=["/path/to/file.pdf"],
    )
except SketricGenAuthenticationError:
    print("The API key was rejected.")
except SketricGenContentTypeError as error:
    print(f"Unsupported file type: {error}")
except SketricGenFileSizeError as error:
    print(f"File is larger than {error.max_size} bytes.")
except SketricGenJobError as error:
    print(f"Brand Agent job {error.job_id} failed: {error.error_summary}")
except SketricGenAdminError as error:
    print(f"Admin API error {error.code}: {error}")
except SketricGenError as error:
    print(f"SDK error: {error}")

Control-plane errors expose a machine-readable code. All SDK-specific errors inherit from SketricGenError.

​Overview

​Requirements

​Installation

​Configure the client

​Run an agent

​Async

​Sync

​Stream a response

​Handle human-in-the-loop requests

​Attach files

​Supported file types

​Use the control plane

​Identify the Teamspace

​List scoped resources

​Manage Brand Agents

​Manage connectors

​Response models

​ChatResponse

​StreamEvent

​Error handling

​Related guides

Overview

Requirements

Installation

Configure the client

Run an agent

Async

Sync

Stream a response

Handle human-in-the-loop requests

Attach files

Supported file types

Use the control plane

Identify the Teamspace

List scoped resources

Manage Brand Agents

Manage connectors

Response models

`ChatResponse`

`StreamEvent`

Error handling

Related guides