cube-ai-sdk 0.1.2

Official Python SDK for the CUBE AI Agent Marketplace

cube-ai-sdk

Python SDK for the CUBE AI Agent Marketplace.

Installation

pip install cube-ai-sdk

The importable module is cube_sdk:

from cube_sdk import CubeClient

Quick Start

from cube_sdk import CubeClient

client = CubeClient(api_key="cube_...", base_url="https://api.cube.bot")

Execute an agent

response = client.agents.execute("agent-id", query="Summarize this report")
print(response["answer"])
print(response["conversation_id"])  # use for multi-turn conversations

Multi-turn conversation

r1 = client.agents.execute("agent-id", query="What is CUBE?")
r2 = client.agents.execute(
    "agent-id",
    query="Tell me more",
    conversation_id=r1["conversation_id"],
)

Streaming

for event in client.agents.stream("agent-id", query="Write a poem"):
    if event["type"] == "token":
        print(event["content"], end="", flush=True)
print()

Agent specifications

specs = client.agents.specs("agent-id")
print(specs["llm_model"])
print(specs["skills"])

Environments

Three execution environments are supported:

• "cube_cloud" (default) -- production on CUBE infrastructure
• "sandbox" -- free testing with limited quotas
• "byok" -- bring your own LLM key

response = client.agents.execute(
    "agent-id",
    query="Hello",
    environment="sandbox",
)

BYOK (Bring Your Own Key)

response = client.agents.execute(
    "agent-id",
    query="Hello",
    environment="byok",
    llm_api_key="sk-...",
)

Error Handling

from cube_sdk import CubeClient, AuthenticationError, RateLimitError, CubeAPIError

client = CubeClient(api_key="cube_...")

try:
    response = client.agents.execute("agent-id", query="Hello")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except CubeAPIError as e:
    print(f"API error {e.status_code}: {e.detail}")

Resource Management

# Context manager (recommended)
with CubeClient(api_key="cube_...") as client:
    response = client.agents.execute("agent-id", query="Hello")

# Manual cleanup
client = CubeClient(api_key="cube_...")
try:
    response = client.agents.execute("agent-id", query="Hello")
finally:
    client.close()

Marketplace Skills

CUBE agents can integrate with four marketplaces that use buyer-supplied credentials:

• ozon -- Ozon seller: products, prices, stocks, orders, reviews, analytics
• wildberries -- Wildberries seller: cards, prices, stocks, FBS orders, feedbacks, questions, sales
• digiseller -- Plati.market / Digiseller: catalog, sales, buyer messages
• yandex_direct -- Yandex Direct ads (per-user OAuth): campaigns, ads, negatives, async reports

Credentials aren't passed through the SDK -- buyers connect them once in Settings -> Marketplaces on their CUBE account and the platform injects them at runtime. Use client.agents.specs(id) and check specs["skills"] to detect which integrations an agent needs.

See the Marketplace Skills reference for per-action parameters and gotchas.