CellCog Python SDK

CellCog: Any-to-Any AI for Agents — Your sub-agent for quality work.

When you need depth, accuracy, or complex deliverables — research reports, interactive apps, videos, images, podcasts, documents, spreadsheets, and more — use CellCog.

Installation

pip install cellcog

Quick Start

export CELLCOG_API_KEY="sk_..."  # Get from https://cellcog.ai/profile?tab=api-keys

Any agent (blocks until done):

from cellcog import CellCogClient

client = CellCogClient(agent_provider="openclaw")

result = client.create_chat(
    prompt="Research quantum computing advances in 2026",
    task_label="quantum-research",
    chat_mode="agent",
)
# Blocks until done — result contains everything
print(result["message"])

OpenClaw agents (fire-and-forget):

result = client.create_chat(
    prompt="Research quantum computing advances in 2026",
    notify_session_key="agent:main:main",  # OpenClaw session key
    task_label="quantum-research",
    chat_mode="agent",
)
# Returns immediately — daemon delivers results to your session

How It Works

Two delivery modes:

• Wait for Completion (default) — Blocks until CellCog finishes and returns the full result. Works with any agent — OpenClaw, Claude Code, Cursor, or any Python environment.

• Fire-and-Forget (OpenClaw) — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires sessions_send on OpenClaw Gateway.

All methods return the same unified shape:

{
    "chat_id": str,
    "is_operating": bool,
    "status": str,         # "completed" | "tracking" | "timeout" | "operating"
    "message": str,        # Always print this in full
}

Configuration

export CELLCOG_API_KEY="sk_..."

Get your API key:

1. Create account: https://cellcog.ai/signup
2. Add payment: https://cellcog.ai/profile?tab=billing
3. Get API key: https://cellcog.ai/profile?tab=api-keys

API Reference

Core Methods

# Create chat — wait mode (default, universal)
result = client.create_chat(
    prompt="Your task...",
    task_label="my-task",
    chat_mode="agent",              # "agent" | "creative" | "team" (legacy names still work)
    chat_tier="core",               # "flash" | "core" | "max" (omit for the mode's default)
    timeout=1800,                   # 30 min default; use 3600 for complex jobs
)

# Create chat — notify mode (OpenClaw only)
result = client.create_chat(
    prompt="Your task...",
    notify_session_key="agent:main:main",
    task_label="my-task",
    chat_mode="agent",
)

# Send follow-up message
result = client.send_message(chat_id="abc123", message="Now create a PDF summary")

# Get full history
result = client.get_history(chat_id="abc123")

# Quick status check
status = client.get_status(chat_id="abc123")

# Resume waiting after timeout
result = client.wait_for_completion(chat_id="abc123", timeout=1800)

Optional Parameters

result = client.create_chat(
    prompt="...",
    task_label="...",
    chat_mode="agent",
    project_id="...",                       # CellCog project for document context
    agent_role_id="...",                    # Specialized agent role
    enable_cowork=True,                     # Direct machine access via CellCog Desktop
    cowork_working_directory="/Users/...",  # Working directory for co-work
)

File Handling

# Send files to CellCog
result = client.create_chat(
    prompt='Analyze this data: <SHOW_FILE>/path/to/sales.csv</SHOW_FILE>',
    task_label="data-analysis",
)

# Request output at specific path
result = client.create_chat(
    prompt='Create a report: <GENERATE_FILE>/output/report.pdf</GENERATE_FILE>',
    task_label="report",
)

Generated files auto-download to ~/.cellcog/chats/{chat_id}/ or to GENERATE_FILE paths if specified.

Chat Modes & Tiers

Every chat runs at a (mode, tier) operating point. Pick a mode for the KIND of work, a tier for the DEPTH (omit chat_tier for the mode's default).

Legacy mode names ("agent core", "agent team", "agent team max") keep working forever — the server normalizes them to their historical operating points.

35 Skills — The Cog Family

Browse all skills: https://cellcog.ai/skills

Error Handling

from cellcog import (
    CellCogClient,
    PaymentRequiredError,
    MaxConcurrencyError,
    GatewayConfigError,
    SDKUpgradeRequiredError,
)

client = CellCogClient(agent_provider="openclaw")

try:
    result = client.create_chat(...)
except PaymentRequiredError as e:
    print(f"Add credits: {e.billing_url}")
except MaxConcurrencyError as e:
    print(f"Too many parallel chats: {e.operating_count}/{e.max_parallel}")
except GatewayConfigError as e:
    print(f"Fix: {e.fix_command}")  # OpenClaw notify mode only
except SDKUpgradeRequiredError as e:
    print(f"Upgrade: pip install cellcog>={e.minimum_version}")

Links

• CellCog Platform: https://cellcog.ai
• Skills Catalog: https://cellcog.ai/skills
• GitHub: https://github.com/CellCog/cellcog_python
• ClawHub Skills: https://clawhub.ai
• API Docs: https://cellcog.ai/developer/docs
• Get API Key: https://cellcog.ai/profile?tab=api-keys

License

MIT License — see LICENSE for details.