Invoking Expert Agents

This tutorial walks you through the complete process of invoking a Profy Expert from an external application — from obtaining the Expert identifier to building a full streaming chat interface.

What You’ll Build

A backend service that can invoke Profy Experts, with SSE streaming responses connected to a frontend chat interface. When complete, your application will have:

Invoke any published Expert using the Profy SDK
Multi-turn conversation context retention (sessionId)
SSE stream parsing with structured event handling
Comprehensive error handling and retry strategies

What Is an Expert

An Expert is an AI Agent product on the Profy platform, published by creators on the Marketplace. Each Expert consists of:

Component	Description
Persona	Character and behavioral style definition
Tools	Callable tool set (search, code execution, file operations, etc.)
Memory	Cross-session memory that continuously accumulates user preferences and facts
Skills	Reusable structured skills that define the Agent’s behavioral patterns

Through the SDK’s agents.run() / agents.runStream() methods, your application can invoke these Experts just like calling a function.

Prerequisites

Before getting started, make sure you have:

Profy API Key: A sk-pro- prefixed API Key created in the Platform Console
Target Expert Identifier: The unique identifier of the Expert you want to invoke

Expert invocation uses your application’s own API Key (sk-pro-) for authentication — no user OAuth Token needed. The API Key identifies your application; the platform tracks usage and billing per Key.

Step 1: Find the Expert Identifier

Every published Expert has a unique identifier (slug format) used for API calls. How to find it:

Marketplace page — Open the Expert’s detail page; the last path segment in the URL is the identifier, e.g., https://app.profy.cn/expert/data-analyst → data-analyst
Studio — If you’re the Expert’s creator, the identifier is shown in the basic information section of the editing page

Store the Expert Identifier in environment variables or configuration files to avoid hardcoding.

Step 2: Single-Turn Invocation

Use the SDK’s agents.run() method to get the complete response at once.

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

const client = new Profy({ apiKey: process.env.PROFY_API_KEY! });

const result = await client.agents.run("data-analyst", "Analyze the recent sales trends");

console.log(result.text);
console.log(`Model: ${result.model}, Tokens: ${result.usage.totalTokens}`);
if (result.toolCalls.length > 0) {
  console.log("Tool calls:", result.toolCalls);
}

from profy import Profy

async with Profy(api_key="sk-pro-...") as client:
    result = await client.agents.run("data-analyst", "Analyze the recent sales trends")

    print(result.text)
    print(f"Model: {result.model}, Tokens: {result.usage.total_tokens}")
    if result.tool_calls:
        print("Tool calls:", result.tool_calls)

agents.run() internally consumes the entire SSE stream and returns the aggregated result:

Field	Type	Description
`text`	`string`	The Expert’s complete text output
`model`	`string?`	The model actually used
`sessionId`	`string?`	Session ID (for multi-turn conversations)
`toolCalls`	`ToolCall[]`	List of tools called by the Expert
`usage`	`TokenUsage`	Token usage statistics
`error`	`string?`	Runtime error message
`elapsedMs` / `elapsed_sec`	`number`	Elapsed time

Step 3: Multi-Turn Conversations

By passing a sessionId parameter, the Expert continues the conversation within the same session context, retaining previous message history and memory.

const sessionId = crypto.randomUUID();

const answer1 = await client.agents.run(
  "data-analyst",
  "Help me analyze the Q1 user growth data",
  { sessionId },
);
console.log(answer1.text);

const answer2 = await client.agents.run(
  "data-analyst",
  "What changed compared to Q4?",
  { sessionId },  // Same sessionId — the Expert remembers the previous turn
);
console.log(answer2.text);

import uuid

session_id = str(uuid.uuid4())

answer1 = await client.agents.run(
    "data-analyst",
    "Help me analyze the Q1 user growth data",
    session_id=session_id,
)
print(answer1.text)

answer2 = await client.agents.run(
    "data-analyst",
    "What changed compared to Q4?",
    session_id=session_id,  # Same session_id — the Expert remembers the previous turn
)
print(answer2.text)

The sessionId is generated and managed by your application. All calls under the same sessionId share conversation context. A new sessionId starts a fresh conversation.

Step 4: Streaming Output

Use agents.runStream() for real-time SSE event streaming, ideal for building typewriter-style chat interfaces.

for await (const chunk of client.agents.runStream("data-analyst", "Generate a quarterly report")) {
  switch (chunk.type) {
    case "output.text.delta":
      process.stdout.write(chunk.content ?? "");
      break;
    case "tool_call.created":
      console.log(`\n[Tool] ${chunk.toolName}`);
      break;
    case "tool_call.completed":
      console.log("[Tool completed]");
      break;
    case "run.completed":
      console.log("\n--- Complete ---");
      break;
    case "run.failed":
      console.error(`\n[Error] ${chunk.message}`);
      break;
  }
}

async for chunk in await client.agents.run_stream("data-analyst", "Generate a quarterly report"):
    match chunk.type:
        case "output.text.delta":
            print(chunk.content, end="", flush=True)
        case "tool_call.created":
            print(f"\n[Tool] {chunk.tool_name}")
        case "tool_call.completed":
            print("[Tool completed]")
        case "run.completed":
            print("\n--- Complete ---")
        case "run.failed":
            print(f"\n[Error] {chunk.message}")

SSE Event Types

Event	Description	Key Fields
`run.created`	Run created	—
`run.in_progress`	Run in progress	`model_name`, `session_id`
`output.text.delta`	Text content fragment	`content`
`tool_call.created`	Tool call started	`tool_name`
`tool_call.completed`	Tool call finished	—
`run.completed`	Run finished	—
`run.failed`	Run failed	`message`
`usage`	Token usage	`prompt_tokens`, `completion_tokens`, `total_tokens`

Step 5: Error Handling

The SDK throws specific exceptions based on HTTP status codes:

Exception	HTTP Status	Meaning	Handling
`InvalidRequestError`	400	Invalid request parameters	Check expert identifier and message
`AuthenticationError`	401	Invalid API Key	Verify Key is correct and not expired
`InsufficientBalanceError`	402	Insufficient balance	Prompt to top up, do not retry
`PermissionDeniedError`	403	No access to this Expert	Guide to purchase/subscribe
`RateLimitError`	429	Too many requests	Exponential backoff retry

import {
  Profy,
  AuthenticationError,
  InsufficientBalanceError,
  RateLimitError,
} from "@profy-ai/sdk";

try {
  const result = await client.agents.run("data-analyst", "Analyze data");
  console.log(result.text);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API Key — check your configuration");
  } else if (error instanceof InsufficientBalanceError) {
    console.error("Insufficient balance — please top up");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited — retry later");
  } else {
    throw error;
  }
}

from profy import (
    Profy,
    AuthenticationError,
    InsufficientBalanceError,
    RateLimitError,
)

try:
    result = await client.agents.run("data-analyst", "Analyze data")
    print(result.text)
except AuthenticationError:
    print("Invalid API Key — check your configuration")
except InsufficientBalanceError:
    print("Insufficient balance — please top up")
except RateLimitError:
    print("Rate limited — retry later")

Do not retry on InsufficientBalanceError (402) — insufficient balance won’t change with retries. Show the user a top-up prompt instead.

Step 6: Building a Chat Interface

Connect streaming output to a frontend chat interface. The frontend calls through your backend proxy, which holds the API Key:

"use client";

import { useState, useCallback } from "react";

interface Message {
  role: "user" | "assistant";
  content: string;
}

export function ExpertChat({ expertId }: { expertId: string }) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState("");
  const [loading, setLoading] = useState(false);
  const [sessionId] = useState(() => crypto.randomUUID());

  const send = useCallback(async () => {
    if (!input.trim() || loading) return;

    const userMsg: Message = { role: "user", content: input };
    setMessages((prev) => [...prev, userMsg]);
    setInput("");
    setLoading(true);

    const assistantMsg: Message = { role: "assistant", content: "" };
    setMessages((prev) => [...prev, assistantMsg]);

    try {
      const res = await fetch("/api/expert/invoke", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ expertId, message: input, sessionId }),
      });

      const reader = res.body!.getReader();
      const decoder = new TextDecoder();

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value, { stream: true });
        for (const line of chunk.split("\n")) {
          if (!line.startsWith("data: ")) continue;
          const data = JSON.parse(line.slice(6));
          if (data.type === "output.text.delta") {
            setMessages((prev) => {
              const updated = [...prev];
              const last = updated[updated.length - 1];
              updated[updated.length - 1] = {
                ...last,
                content: last.content + (data.content ?? ""),
              };
              return updated;
            });
          }
        }
      }
    } finally {
      setLoading(false);
    }
  }, [input, loading, expertId, sessionId]);

  return (
    <div>
      <div>
        {messages.map((msg, i) => (
          <div key={i} data-role={msg.role}>{msg.content}</div>
        ))}
      </div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => e.key === "Enter" && send()}
        placeholder="Type a message..."
        disabled={loading}
      />
    </div>
  );
}

import asyncio
import uuid
from profy import Profy

async def chat_loop(api_key: str, expert_identifier: str):
    session_id = str(uuid.uuid4())
    print(f"Starting conversation with {expert_identifier} (type 'quit' to exit)\n")

    async with Profy(api_key=api_key) as client:
        while True:
            user_input = input("You: ")
            if user_input.strip().lower() == "quit":
                break

            print("Expert: ", end="", flush=True)
            async for chunk in await client.agents.run_stream(
                expert_identifier, user_input, session_id=session_id,
            ):
                if chunk.type == "output.text.delta":
                    print(chunk.content or "", end="", flush=True)
                elif chunk.type == "run.failed":
                    print(f"\n[Error] {chunk.message}")
                elif chunk.type == "run.completed":
                    print()
            print()

asyncio.run(chat_loop("sk-pro-...", "data-analyst"))

The frontend doesn’t call the Profy API directly — requests go through your backend proxy (/api/expert/invoke), which holds the API Key and forwards the SSE stream. This avoids exposing the API Key on the client side.

Complete Backend Example

Wrap Expert invocation as an API endpoint that the frontend can consume directly:

import { Hono } from "hono";
import { stream } from "hono/streaming";
import { Profy } from "@profy-ai/sdk";

const app = new Hono();
const client = new Profy({ apiKey: process.env.PROFY_API_KEY! });

app.post("/api/expert/invoke", async (c) => {
  const { expertId, message, sessionId } = await c.req.json();

  return stream(c, async (s) => {
    for await (const chunk of client.agents.runStream(expertId, message, { sessionId })) {
      s.write(`data: ${JSON.stringify(chunk)}\n\n`);
    }
  }, "text/event-stream");
});

export default app;

import json
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from profy import Profy

app = FastAPI()
client = Profy(api_key="sk-pro-...")

@app.post("/api/expert/invoke")
async def invoke_expert(request: Request):
    body = await request.json()

    async def proxy_stream():
        async for chunk in await client.agents.run_stream(
            body["expertId"], body["message"],
            session_id=body.get("sessionId"),
        ):
            yield f"data: {json.dumps({'type': chunk.type, 'content': chunk.content})}\n\n"

    return StreamingResponse(proxy_stream(), media_type="text/event-stream")

Expert Invocation vs AI Model Calls

The Profy SDK provides two types of AI calls. Choose the right one for your scenario:

Dimension	Expert Invocation (`agents.run`)	AI Model Call (`chat.completions.create`)
Target	Specific Expert (with persona + tools + memory)	General AI model
API Path	`/v1/agents/run`	`/v1/chat/completions`
Context Management	Automatically managed by the platform (`sessionId`)	Application maintains the `messages` array
Tool Calls	Expert comes with built-in tools, orchestrated by the platform	Application defines and handles tools
Memory	Built-in cross-session memory	No memory — each call is independent
Use Cases	Domain expert tasks (data analysis, customer service, writing)	General text generation, translation, summarization

const response = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "You are a translation assistant." },
    { role: "user", content: "Translate to Chinese: The weather is nice today" },
  ],
  temperature: 0.3,
});
console.log(response.text);

response = await client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You are a translation assistant."},
        {"role": "user", "content": "Translate to Chinese: The weather is nice today"},
    ],
    temperature=0.3,
)
print(response.text)

If you need a “ready-to-use domain expert,” use agents.run. If you need “raw model capabilities” with your own orchestration, use chat.completions.create. Both use the same Profy client.

Next Steps

SDK Quick Start

Install the SDK, create an API Key, and make your first call

AI Token-Metered Billing

Build token-metered AI apps with chat.completions

Per-Use Billing

Implement per-call billing with ProfyApp reportEvent

Token Management

OAuth Token persistence and concurrent refresh best practices

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Invoking Expert Agents

What You’ll Build

What Is an Expert

Prerequisites

Step 1: Find the Expert Identifier

Step 2: Single-Turn Invocation

Step 3: Multi-Turn Conversations

Step 4: Streaming Output

SSE Event Types

Step 5: Error Handling

Step 6: Building a Chat Interface

Complete Backend Example

Expert Invocation vs AI Model Calls

Next Steps

SDK Quick Start

AI Token-Metered Billing

Per-Use Billing

Token Management

​What You’ll Build

​What Is an Expert

​Prerequisites

​Step 1: Find the Expert Identifier

​Step 2: Single-Turn Invocation

​Step 3: Multi-Turn Conversations

​Step 4: Streaming Output

​SSE Event Types

​Step 5: Error Handling

​Step 6: Building a Chat Interface

​Complete Backend Example

​Expert Invocation vs AI Model Calls

​Next Steps

SDK Quick Start

AI Token-Metered Billing

Per-Use Billing

Token Management

What You’ll Build

What Is an Expert

Prerequisites

Step 1: Find the Expert Identifier

Step 2: Single-Turn Invocation

Step 3: Multi-Turn Conversations

Step 4: Streaming Output

SSE Event Types

Step 5: Error Handling

Step 6: Building a Chat Interface

Complete Backend Example

Expert Invocation vs AI Model Calls

Next Steps