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)

string

Required on API-key calls. A stable terminal-user id that isolates sessions, files, and memory. Omitting it returns 400, starting with Missing required header: X-Profy-End-User-Id. OAuth calls do not send it. Billing still charges the key owner.

Request Body

Persona, subagents, and delegation partners default to the Expert configured in Studio. profy-skills is not loaded on its own. This endpoint does not accept instructions.

string | object

required

Expert id. The shortest form is a string. The object form uses id for the same expert and may include model and tools. model is the model id only. tools is only this run’s extension set, not the whole toolbox. Omit it and those extensions stay off, while web_search and web_fetch stay on. Pass an array and only the listed types are on; an empty array also turns web_search and web_fetch off. Every entry is {"type": ...}. A bare string is rejected. Allowed type values: imagegen, video, music, audio, generate_3d, postprocess_3d, generate_world, schedule, knowledge, obsidian_knowledge, memory, delegation, distill, evolution, web_search, web_fetch, mcp. mcp requires server_label and transport with type: "http" plus server_url. That entry adds one HTTP server for this run and does not remove MCP already stored on the expert. read, bash, and skill stay either way. Plugins are environment.plugins, not this list. Top-level expert_identifier is an alias of agent.id and wins when both are set. Top-level model is an alias of agent.model; the value inside agent wins. When rules is present it replaces this run’s identity, soul, agent, and guard. Omit it to keep the Studio text. An empty array clears those rules for this run. type is one of those four, and each type appears at most once. When subagents is present it replaces this run’s roster and turns spawning on. Omit it to keep the Expert roster, which still follows the key owner’s multi-task switch. Each agents entry needs name, description, system_prompt, and tools. model is optional. When expert_partner is present it replaces this run’s delegation roster. Omit it to keep the platform roster built from the whitelist and @-mentions. An empty array means this run delegates to nobody. Each entry requires identifier. Optional: name, brief (or description), needs_sandbox, mentioned. Listing an expert does not grant access; the delegate call still checks that you can use it.

object

Optional. type is profy_hosted (platform sandbox), self_hosted (the caller’s desktop), or none (no shell). Omitted means profy_hosted. Any other value, including openai_hosted, returns 400. Each skills entry is {"type":"built_in","name":"docx"} or {"type":"customize","name":"..."}. profy-skills loads only when this array names it. A built_in entry loads that one skill from the pack. name: "*" loads the whole pack. Omit skills and this run has no product skill pack. customize reads a same-named skill from the key owner’s or the expert’s library on profy_hosted, and ~/.agents/skills/<name>/SKILL.md on self_hosted. Without this field, user, expert, and workspace skills still appear in discovery. An expert skill marked builtin pack or auto-evolution includes its full text. Other library skills include full text only when named here as customize, or through skill_names. Each plugins entry is {"type":"built_in","id":"profy-sites"} and selects an installed plugin. capability_directories is only for self_hosted. Entries are local directories and must not contain ...

string | array

required

What to send the Expert. A string, or an array of { role, content } messages. Missing input returns Missing required field: input. message remains an alias.

boolean

Must be true or omitted. false returns 400. This endpoint is SSE only.

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[]

File ids to attach, up to 20. Ids come from Upload File. The platform materializes each file in this session’s directory (/home/user/workspace/<expert_identifier>/<session_id>/), 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.

object[]

HITL resume. When non-empty, input may be omitted. session_id must be the turn that emitted approval.required. Each entry requires tool_call_id, tool_name, and decision. Put an Ask answer in modified_parameters.result. Optional: result, original_parameters, rejection_reason, is_error. camelCase (toolCallId and the rest) is accepted.

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 -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-expert",
    "input": "Help me analyze the performance issues in this code",
    "stream": true
  }'

To change the model or the extensions for this run only, put them on the same request:

curl -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "my-expert",
      "model": "gpt-6-astra",
      "tools": [
        { "type": "knowledge" },
        { "type": "web_search" },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" }
        }
      ]
    },
    "environment": { "type": "profy_hosted" },
    "input": "Create tree.py and run it.",
    "stream": true
  }'

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

Every data payload carries a monotonic event_id and a type that matches the event: line. Text and thinking rename the internal content field to delta. The full vocabulary is on SSE Events. Unmapped internal events keep their original type.

Lifecycle Events

Event	Description	Key Fields
`run.created`	Request accepted; the run is preparing	`stage`, `message`
`run.in_progress`	One reasoning turn started. A run can emit this more than once	`session_id`, `model_name`, `turn_id`, `capabilities`
`run.completed`	Run finished	`content`, `summary`, `finish_reason`
`run.failed`	Run failed	`error`, `error_code`, `failure_class`

Output Events

Event	Description	Key Fields
`output.text.delta`	Text increment	`delta`
`output.thinking.delta`	Thinking increment	`delta`
`output.thinking.status`	Thinking phase	`status`: `thinking` or `done`

Tool Call Events

Event	Description	Key Fields
`tool_call.created`	The model chose a tool (`status=pending`)	`tool_call_id`, `tool_name`, `parameters`
`tool_call.in_progress`	The tool started	`tool_call_id`, `tool_name`
`tool_call.completed`	The tool finished. The return value is on `tool_call.result`, not on this event	`tool_call_id`, `tool_name`, `parameters`
`tool_call.failed`	The tool failed	`tool_call_id`, `tool_name`, `parameters`
`tool_call.arguments.delta`	Streaming argument text	`tool_call_id`, `tool_name`, `args_chunk`, `index`
`tool_call.result`	Tool return value	`tool_call_id`, `tool_name`, `result`, `is_error`
`tool_call.denied`	A permission gate refused the tool before it ran	`tool_call_id`, `tool_name`, `layer`, `reason`
`approval.required`	The run is waiting for a human answer. Resume with `tool_confirmations`	`tool_call_id`, `questions`, `title`

Usage Events

Event	Description	Key Fields
`usage.token`	Token totals for this turn. Billing reads this event	`prompt_tokens`, `completion_tokens`, `total_tokens`
`usage.budget_exhausted`	Budget spent; the run stops	`total_tokens_used`, `token_budget`
`usage.trial_exhausted`	Trial uses exhausted	Internal fields passed through

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('error')}")

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 "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"agent":"my-expert","input":"Hello","stream":true}'

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-Profy-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`	An id in `attachment_file_ids` is unknown or not yours
`500`	Internal error. The body is `{ code, message, data: null }`
`502`	Agent Runtime upstream error
`503`	Cannot connect to Agent Runtime
`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