Run Expert

Invoke a Profy Expert (AI Agent) and receive a complete response via SSE streaming, including text output, tool calls, and token usage.

POST https://api.profy.cn/v1/agents/run

Authentication

string

required

Bearer sk-pro-xxxx (API Key) or Bearer <access_token> (OAuth)

Request Body

string

required

The Expert’s unique identifier. You can find it on the Expert’s marketplace page or in Studio.

string

required

The message content to send to the Expert.

string

Session ID for multi-turn conversations. Not required for the first call — a new session_id is returned in the X-Session-Id response header.

string

Specify the model to use. Defaults to the platform’s default model if not provided. Use GET /v1/models to query available models.

string[]

File ids to attach, up to 20. Ids come from Upload File. The platform materializes each file in the Expert’s sandbox (/home/user/uploads/), where the Expert can read / grep it.Ids only, never URLs: the platform will not fetch a link you hand it, so you never have to publish a readable link to a private document.

Request Examples

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    result = await client.agents.run(
        "my-expert",
        "Help me analyze the performance issues in this code",
        session_id="existing-session-id",  # optional
        model="deepseek-v3",               # optional
    )
    print(result.text)
    print(f"Tool calls: {[t.name for t in result.tool_calls]}")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

const result = await client.agents.run(
  "my-expert",
  "Help me analyze the performance issues in this code",
  {
    sessionId: "existing-session-id",
    model: "deepseek-v3",
  }
);

console.log(result.text);
console.log("Tool calls:", result.toolCalls.map(t => t.name));

curl -X POST https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expert_identifier": "my-expert",
    "message": "Help me analyze the performance issues in this code"
  }'

Response Format

The response is an SSE (Server-Sent Events) stream with hierarchical dot-notation event names (aligned with the OpenAI Responses API). The response headers include X-Session-Id for subsequent multi-turn conversations.

event: run.in_progress
data: {"type":"run.in_progress","model_name":"deepseek-v3","session_id":"ses_abc123","event_id":2}

SSE Event Types

Lifecycle Events

Event	Description	Key Fields
`run.created`	Agent run created	`event_id`
`run.in_progress`	Agent started running	`model_name`, `session_id`
`run.completed`	Agent run completed	`event_id`
`run.failed`	Agent run failed	`message`

Output Events

Event	Description	Key Fields
`output.text.delta`	Incremental text output	`delta`
`output.thinking.delta`	Chain-of-thought increment (reasoning models)	`delta`

Tool Call Events

Event	Description	Key Fields
`tool_call.created`	Tool call started	`tool_name`, `tool_call_id`
`tool_call.arguments.delta`	Tool argument increment	`delta`
`tool_call.completed`	Tool call completed	`tool_name`, `result`
`tool_call.failed`	Tool call failed	`tool_name`, `error`

Usage Events

Event	Description	Key Fields
`usage.token`	Token usage statistics	`input_tokens`, `output_tokens`
`usage.trial_exhausted`	Trial uses exhausted	`message`

Streaming Examples

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    async for chunk in client.agents.run_stream("my-expert", "Hello"):
        match chunk.type:
            case "run.in_progress":
                print(f"Session: {chunk.raw.get('session_id')}")
            case "output.text.delta":
                print(chunk.delta, end="", flush=True)
            case "tool_call.created":
                print(f"\nTool call: {chunk.raw.get('tool_name')}")
            case "run.completed":
                print("\n--- Done ---")
            case "run.failed":
                print(f"\nError: {chunk.raw.get('message')}")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

for await (const chunk of client.agents.runStream("my-expert", "Hello")) {
  switch (chunk.type) {
    case "run.in_progress":
      console.log(`Session: ${chunk.raw.session_id}`);
      break;
    case "output.text.delta":
      process.stdout.write(chunk.delta ?? "");
      break;
    case "tool_call.created":
      console.log(`\nTool call: ${chunk.raw.tool_name}`);
      break;
    case "run.completed":
      console.log("\n--- Done ---");
      break;
  }
}

curl -N -X POST https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"expert_identifier":"my-expert","message":"Hello"}'

Billing

Billed by token usage (billing unit token_split). Credits are deducted from the account that owns the API Key, not from the end user named in X-End-User-Id — that header only scopes sessions and attributes usage; it is not a billing subject. Formula: ceil(input_tokens × input_rate ÷ 1e6) + ceil(output_tokens × output_rate ÷ 1e6) (input and output are rounded up separately, then summed). Per-model rates are operational data, so read the current values from the model selector or the model list endpoint; the algorithm is fixed and documented in Billing Formulas. Read actual consumption for a call from the usage.token event — that is the authoritative value. Do not estimate with your own tokenizer and treat the result as a bill.

Error Codes

HTTP Status Code	Description
`400`	Missing or invalid request parameters
`401`	Authentication failed (invalid API Key or expired token)
`403`	Expert access denied (not purchased or trial uses exhausted)
`404`	Expert does not exist or is not published; or an id in `attachment_file_ids` is unknown or not yours
`502`	Agent Runtime upstream error
`504`	Agent Runtime timeout

Next Steps

Upload File

Give the Expert a document to read

Chat Completions

OpenAI-compatible chat completions endpoint

Python SDK

Complete Python SDK guide

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Authentication

Request Body

Request Examples

Response Format

SSE Event Types

Lifecycle Events

Output Events

Tool Call Events

Usage Events

Streaming Examples

Billing

Error Codes

Next Steps

Upload File

Chat Completions

Python SDK

​Authentication

​Request Body

​Request Examples

​Response Format

​SSE Event Types

​Lifecycle Events

​Output Events

​Tool Call Events

​Usage Events

​Streaming Examples

​Billing

​Error Codes

​Next Steps

Upload File

Chat Completions

Python SDK

Authentication

Request Body

Request Examples

Response Format

SSE Event Types

Lifecycle Events

Output Events

Tool Call Events

Usage Events

Streaming Examples

Billing

Error Codes

Next Steps