Python SDK

The Python SDK is frozen and not recommended for production use.profy-sdk on PyPI is still 0.1.0, which ships only OAuth and event reporting (ProfyApp) — it does not contain the unified Profy client documented on this page. Every example here targets the unreleased 1.0.0 source, so pip install profy-sdk followed by from profy import Profy raises ImportError.Until the Python SDK is published again, call the REST /v1 endpoints directly, or use the TypeScript SDK.

profy is the official Python SDK for the Profy platform, providing both async and sync clients with built-in authentication, streaming, and error handling.

Installation

pip install profy-sdk

The distribution is named profy-sdk; the import name is profy (from profy import Profy). Requires Python 3.9+. The SDK is built on httpx.

Quick Start

Async Client (Recommended)

import asyncio
from profy import Profy

async def main():
    async with Profy(api_key="sk-pro-your-key") as client:
        result = await client.agents.run("my-expert", "你好")
        print(result.text)

asyncio.run(main())

Sync Client

from profy import ProfySync

with ProfySync(api_key="sk-pro-your-key") as client:
    result = client.agents.run("my-expert", "你好")
    print(result.text)

Client Configuration

from profy import Profy
import httpx

client = Profy(
    api_key="sk-pro-your-key",
    base_url="https://api.profy.cn",  # default
    timeout=httpx.Timeout(300.0, connect=10.0),  # default
)

Parameter	Type	Default	Description
`api_key`	`str`	(required)	API Key or OAuth Access Token
`base_url`	`str`	`https://api.profy.cn`	API base URL
`timeout`	`Timeout \| float`	300 seconds	Request timeout

Resource Namespaces

The SDK organizes API methods through resource namespaces:

Namespace	Methods	Endpoint
`client.agents`	`run()`, `run_stream()`	`POST /v1/agents/run`
`client.chat.completions`	`create()`	`POST /v1/chat/completions`
`client.models`	`list()`	`GET /v1/models`
`client.events`	`report()`	`POST /v1/events`

Agents

`agents.run()` — Invoke an Expert

result = await client.agents.run(
    "my-expert",           # Expert identifier
    "帮我分析这段代码",      # Message content
    session_id="abc123",   # Optional: continue a session
    model="deepseek-v3",   # Optional: specify a model
)

Returns an AgentRunResponse object:

Property	Type	Description
`text`	`str`	The Agent’s complete text reply
`model`	`str \| None`	Model name used
`session_id`	`str \| None`	Session ID (for multi-turn conversations)
`tool_calls`	`list[ToolCall]`	List of tool calls
`usage`	`TokenUsage`	Token usage
`error`	`str \| None`	Error message (if any)
`partial`	`bool`	Whether the response was truncated due to timeout
`elapsed_sec`	`float`	Elapsed time (seconds)

`agents.run_stream()` — Stream an Expert Invocation

async for chunk in client.agents.run_stream("my-expert", "你好"):
    if chunk.type == "output.text.delta":
        print(chunk.content, end="", flush=True)
    elif chunk.type == "tool_call.created":
        print(f"\n🔧 {chunk.tool_name}")
    elif chunk.type == "run.completed":
        print("\nDone")

Each AgentRunChunk contains:

Property	Type	Description
`type`	`str`	Event type (e.g., `output.text.delta`)
`content`	`str \| None`	Text increment (only for `output.text.delta`)
`tool_name`	`str \| None`	Tool name (only for `tool_call.*`)
`usage`	`TokenUsage \| None`	Token usage (only for the `usage` event)
`raw`	`dict`	Raw event data

Chat Completions

`chat.completions.create()` — Chat Completion

Non-streaming:

resp = await client.chat.completions.create(
    model="deepseek-v3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "你好"},
    ],
    temperature=0.7,
    max_tokens=1000,
)
print(resp.text)
print(f"Tokens: {resp.usage.total_tokens}")

Streaming:

stream = await client.chat.completions.create(
    model="deepseek-v3",
    messages=[{"role": "user", "content": "讲一个故事"}],
    stream=True,
)
async for chunk in stream:
    if chunk.delta.content:
        print(chunk.delta.content, end="", flush=True)

ChatResponse object:

Property	Type	Description
`text`	`str`	Reply text (shortcut for `choices[0].message.content`)
`model`	`str`	Model name
`usage`	`TokenUsage`	Token usage
`id`	`str`	Response ID
`created`	`int`	Creation timestamp
`choices`	`list[ChatChoice]`	Raw choices list

Models

`models.list()` — Get Model List

models = await client.models.list()

for m in models:
    print(f"{m['id']}: {m['name']}")
    caps = m.get("capabilities", {})
    print(f"  Tools: {'✅' if caps.get('supportsTools') else '❌'}")
    print(f"  Vision: {'✅' if caps.get('supportsVision') else '❌'}")

Events

`events.report()` — Report a Custom Event

result = await client.events.report(
    "image_generation",
    idempotency_key="order_123_gen_1",
    metadata={"style": "watercolor"},
)
print(f"Charged: {result['charged']}")
print(f"Remaining: {result['balance_remaining']}")

Parameter	Type	Required	Description
`event_name`	`str`	✅	Event name
`idempotency_key`	`str`	No	Idempotency key (auto-generated if omitted)
`metadata`	`dict`	No	Additional metadata

/v1/events requires an OAuth Access Token (pass it as api_key when constructing the client). Calling with an sk-pro- API Key returns 401 (Custom events require OAuth token, not API key).

Error Handling

The SDK raises ProfyApiError when the API returns a 4xx/5xx status code:

from profy import Profy, ProfyApiError

async with Profy(api_key="sk-pro-your-key") as client:
    try:
        result = await client.agents.run("non-existent", "你好")
    except ProfyApiError as e:
        print(f"HTTP Status: {e.status_code}")
        print(f"Error: {e.body}")
        if e.status_code == 404:
            print("Expert not found")
        elif e.status_code == 403:
            print("Access denied")
        elif e.status_code == 429:
            print("Rate limited, please retry later")

Timeout Handling

import httpx
from profy import Profy

async with Profy(
    api_key="sk-pro-your-key",
    timeout=httpx.Timeout(60.0, connect=5.0),
) as client:
    try:
        result = await client.agents.run("my-expert", "复杂任务")
    except httpx.TimeoutException:
        print("Request timed out")

agents.run() will attempt to return partial results already received on timeout (result.partial = True) rather than raising an exception directly.

Sync Client

ProfySync provides the exact same API but with synchronous methods:

from profy import ProfySync

with ProfySync(api_key="sk-pro-your-key") as client:
    # Agents
    result = client.agents.run("my-expert", "你好")
    for chunk in client.agents.run_stream("my-expert", "你好"):
        print(chunk.content, end="")

    # Chat
    resp = client.chat.completions.create(
        model="deepseek-v3",
        messages=[{"role": "user", "content": "你好"}],
    )

    # Models
    models = client.models.list()

ProfySync exposes the exact same resource namespaces as Profy (including events). Note: events.report() requires constructing the client with an OAuth Access Token (ProfySync(api_key=oauth_token)); calling /v1/events with an sk-pro- API Key returns 401.

Full Example: Multi-Turn Chat Bot

import asyncio
from profy import Profy, ProfyApiError

async def chat_bot():
    async with Profy(api_key="sk-pro-your-key") as client:
        session_id = None
        print("Start chatting (type 'quit' to exit)\n")

        while True:
            user_input = input("You: ")
            if user_input.lower() == "quit":
                break

            try:
                print("AI: ", end="", flush=True)
                async for chunk in client.agents.run_stream(
                    "my-expert",
                    user_input,
                    session_id=session_id,
                ):
                    if chunk.type == "run.in_progress":
                        session_id = chunk.session_id
                    elif chunk.type == "output.text.delta":
                        print(chunk.content, end="", flush=True)
                print()
            except ProfyApiError as e:
                print(f"\nError: {e.body}")

asyncio.run(chat_bot())

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Installation

Quick Start

Async Client (Recommended)

Sync Client

Client Configuration

Resource Namespaces

Agents

`agents.run()` — Invoke an Expert

`agents.run_stream()` — Stream an Expert Invocation

Chat Completions

`chat.completions.create()` — Chat Completion

Models

`models.list()` — Get Model List

Events

`events.report()` — Report a Custom Event

Error Handling

Timeout Handling

Sync Client

Full Example: Multi-Turn Chat Bot

Next Steps

TypeScript SDK

API Reference

​Installation

​Quick Start

​Async Client (Recommended)

​Sync Client

​Client Configuration

​Resource Namespaces

​Agents

​agents.run() — Invoke an Expert

​agents.run_stream() — Stream an Expert Invocation

​Chat Completions

​chat.completions.create() — Chat Completion

​Models

​models.list() — Get Model List

​Events

​events.report() — Report a Custom Event

​Error Handling

​Timeout Handling

​Sync Client

​Full Example: Multi-Turn Chat Bot

​Next Steps

TypeScript SDK

API Reference

Installation

Quick Start

Async Client (Recommended)

Sync Client

Client Configuration

Resource Namespaces

Agents

`agents.run()` — Invoke an Expert

`agents.run_stream()` — Stream an Expert Invocation

Chat Completions

`chat.completions.create()` — Chat Completion

Models

`models.list()` — Get Model List

Events

`events.report()` — Report a Custom Event

Error Handling

Timeout Handling

Sync Client

Full Example: Multi-Turn Chat Bot

Next Steps