Panofy SDK 用户使用指南
本页目录
引言
你已经在 Panofy 上训练好了一个智能体，平时可以在网页里和它对话。但在网页上手动交互没办法批量完成任务——没法让它自动运行、反复调用，更没法接进你自己的程序里。
SDK 就是来解决这个的。它（Software Development Kit，软件开发工具包）是一个小工具包，能让你在自己的代码里直接调用训练好的智能体。不用再打开浏览器手动交互，几行 Python 或 Node.js 代码就可以自动实现数据传输并获得任务结果——可以把它接进脚本、后端或者自动化流程。
这份指南会用一个简单的「斐波那契智能体」的例子带你走完从训练到获得结果的全过程：它接收一个数字 n，返回第 n 个斐波那契数。第一部分展示这个智能体被创建和训练的全过程，第二部分展示如何用 SDK 在代码里调用它。这个最小的例子跑通之后，你可以参照以下操作调用你自己的智能体。
第一部分 · 创建并训练智能体
步骤 1：准备训练说明
可以先准备一个 Markdown 文件，比如 fibonacci-agent.md，内容类似：
# Fibonacci Workflow Agent
You are a Workflow Agent callable via the SDK. Your task is to read the field n passed by the caller, compute the n-th Fibonacci number, and return the result directly.
## Call definition
fib(n) -> number
## Input field
- n: a non-negative integer.
Example request:
{ "n": 10 }
## Return value
When n = 10, return: 55
## Rules
- fib(0) = 0
- fib(1) = 1
- fib(n) = fib(n - 1) + fib(n - 2), where n >= 2
## Examples
| n | result |
|----|--------|
| 0 | 0 |
| 1 | 1 |
| 7 | 13 |
| 10 | 55 |
## Constraints
- Do not ask the user any questions.
- Do not return explanatory text.
- Do not return Markdown.
- Return the final result only.
提示： 上述内容也可以在网页端的「使用描述」部分直接填写。为了保证训练效果，建议将该文档作为训练材料上传。
步骤 2：创建智能体
进入 Panofy 控制台后，打开工作流列表页，点击右上角「新智能体」创建。
在「创建智能体」页面填写基本信息：
- 智能体名称：Fibonacci Workflow Agent
- 模型：免费版默认使用 Panofy Air 模型；订阅后可以使用 Panofy Pro 模型
填写完成后点击「下一步」。
接着在「使用描述」里说清楚这个智能体是做什么的，比如：
This is a Fibonacci Workflow Agent for structured SDK calls. The input field is n, which represents the index of the Fibonacci number to compute. When the caller passes in n, compute fib(n) and return the final result directly. Do not ask the user any questions, and do not return any explanatory text.
最后在训练文档区域把刚才准备的文件传上去，然后点击「开始训练」。
训练一开始，卡片上会显示「训练中」状态，按钮进度条展示训练进度（比如「0%」）。等状态变成「可集成」、「去集成」按钮变成绿色，就说明这个智能体可以调用了。训练未完成就调 SDK 会触发智能体暂时无法调用的报错。
第二部分 · 通过 SDK 调用智能体
步骤 1：安装 SDK
Panofy SDK 同时支持 Python 和 TypeScript / Node.js，可以根据自己的需求选择安装。
Python
pip install panofy
装好之后，导入的模块名还是 panofy：
from panofy import Panofy
TypeScript / Node.js
npm install panofy
# 或使用 pnpm
pnpm add panofy
步骤 2：调用训练完成的智能体
训练完成后，回到工作流列表页：
在 Fibonacci 这个智能体卡片上，点击绿色的「去集成」按钮。
弹窗里会显示智能体 ID 和 base_url，二者都需要复制保存。
关于 API Key 的补充说明：如果示例代码里还是 your_api_key 占位符，进入开放平台，点击「新建密钥」。
记录完整密钥。可以点击列表里的「复制」按钮直接复制完整密钥。
Python 完整示例
from panofy import Panofy
def main() -> None:
n = 10
with Panofy(
base_url="https://your-base-url.up.railway.app",
agent_id="your-agent-id",
api_key="your-api-key",
) as client:
result = client.predict(n=n)
point_usage = client.last_point_usage()
print(f"fib({n}) = {result}")
if point_usage is not None:
print("points consumed:", point_usage.points_consumed)
if __name__ == "__main__":
main()
把代码存成 run_fib.py，然后运行：
python run_fib.py
这个 Fibonacci Agent 的返回类型固定是 number，所以输出应该是：
fib(10) = 55
如果不用 with，记得在程序结束时手动关掉 client：
client.close()
TypeScript / Node.js 完整示例
import { Panofy } from "panofy";
const main = async () => {
const n = 10;
const panofy = new Panofy({
baseUrl: "https://your-base-url.up.railway.app",
agentId: "your-agent-id",
apiKey: "your-api-key",
});
const result = await panofy.predict({ n });
const pointUsage = panofy.lastPointUsage();
console.log(`fib(${n}) =`, result);
if (pointUsage) {
console.log("points consumed:", pointUsage.points_consumed);
}
};
main().catch((error) => {
console.error(error);
process.exit(1);
});
输出应为：
fib(10) = 55
附录 · 参考说明
1. 字段名必须和智能体的输入定义一致
这个斐波那契智能体的输入字段是 n。实际使用时可以根据你自己智能体的输入字段来替换。
比如字段叫 input：
# Python
result = client.predict(input=10)
// TypeScript
const result = await panofy.predict({ input: 10 });
字段叫 number：
# Python
result = client.predict(number=10)
// TypeScript
const result = await panofy.predict({ number: 10 });
2. 查看最近一次积分消耗
每次 predict() 调用结束后，SDK 都会记录本次的积分消耗。读取最近一次消耗的代码为：
# Python
result = client.predict(n=10)
point_usage = client.last_point_usage()
if point_usage is not None:
print("points consumed:", point_usage.points_consumed)
// TypeScript
const result = await panofy.predict({ n: 10 });
const pointUsage = panofy.lastPointUsage();
if (pointUsage) {
console.log("points consumed:", pointUsage.points_consumed);
}
3. 调用时传入本地文件作为输入
想把本地文件（CSV、JSON、PDF、图片、Word、Excel 等）传给智能体，只需将本地文件路径当成普通字符串传给 predict()。这只对训练后可以接收文件的智能体有效，不适用于本例的斐波那契智能体。
以本地文件 ./data/report.csv 为例：
# Python
result = client.predict(input_csv="./data/report.csv")
// TypeScript
const result = await panofy.predict({
input_csv: "./data/report.csv",
});
4. 查看智能体和任务
除了 predict()，SDK 还有一些辅助操作，在排查问题时可以发挥作用。
4.1 列出可访问的 Agents
# Python
agents = client.agents.list()
for agent in agents:
print(agent.id, agent.name, agent.training_status)
// TypeScript
const agents = await panofy.agents.list();
for (const agent of agents) {
console.log(agent.id, agent.name, agent.training_status);
}
4.2 查询单个 Agent
# Python
agent = client.agents.get("your-agent-id")
print(agent.id, agent.name, agent.training_status)
// TypeScript
const agent = await panofy.agents.get('your-agent-id');
console.log(agent.id, agent.name, agent.training_status);
4.3 创建、更新、删除 Agent
# Python
agent = client.agents.create(
name="sales-report-agent",
description="Analyze sales CSV files",
model_id="PANOFY_AIR",
)
updated = client.agents.update(agent.id, name="sales-report-agent-v2")
client.agents.delete(agent.id)
// TypeScript
const agent = await panofy.agents.create({
name: 'sales-report-agent',
description: 'Analyze sales CSV files',
model_id: 'PANOFY_AIR',
});
const updated = await panofy.agents.update(agent.id, {
name: 'sales-report-agent-v2',
});
await panofy.agents.delete(agent.id);
4.4 查看任务列表
# Python
tasks = client.tasks.list(agent_id="your-agent-id", limit=10)
for task in tasks:
print(task.id, task.status)
// TypeScript
const tasks = await panofy.tasks.list({
agent_id: 'your-agent-id',
limit: 10,
});
for (const task of tasks) {
console.log(task.id, task.status);
}
4.5 查询单个任务
# Python
task = client.tasks.get("your-task-id")
print(task)
// TypeScript
const task = await panofy.tasks.get('your-task-id');
console.log(task);
4.6 删除任务
# Python
client.tasks.delete("your-task-id")
// TypeScript
await panofy.tasks.delete('your-task-id');