运行第一个智能体

用 API 建立一段服务智能体对话，并从事件中验证真实回复。本页只在服务端运行，不需要网页组件或嵌入策略。

准备 Bun 或支持原生 fetch 的 Node.js、Develop 组织的 API Key，以及该组织可用的 deepseek-flash 模型和余额。在服务端进程设置 PRAXIS_API_KEY；密钥创建见API Key。如果你的 Key 属于其他环境，先统一 API 地址、组织和模型，不能混用环境。

1. 创建智能体

新建 first-agent.mjs，从下面的代码开始。后续三段 JavaScript 按顺序追加到同一个文件，不要分别执行。助手只回答一个算术问题，便于判断首次调用是否完成；业务工具在接通后再添加。

POST /agent/v1/agents 使用名称、类型、模型和指令创建配置。tools: [] 不声明额外工具。请求辅助函数为每次调用检查状态并设置超时，失败时只输出状态和请求标识，不打印 Key。

import assert from "node:assert/strict";
import { setTimeout as delay } from "node:timers/promises";

const { PRAXIS_API_KEY } = process.env;
assert(PRAXIS_API_KEY, "Set PRAXIS_API_KEY in the server process");
const base = "https://api-develop.deepraxis.com/agent/v1";
async function request(path, body) {
  const response = await fetch(`${base}${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${PRAXIS_API_KEY}`,
      "Content-Type": "application/json",
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}; request=${response.headers.get("X-Request-Id") ?? response.headers.get("request-id")}`);
  }
  return response.json();
}
const agent = await request("/agents", {
  name: "First support agent", kind: "service", model: "deepseek-flash",
  system: "Answer the user's question briefly. Do not use tools for this exercise.",
  tools: [],
});
assert(agent.id.startsWith("agent_"));
console.log({ agent: agent.id, version: agent.version });

预期结果： 创建响应为 HTTP 200，包含公开 id 和 version。运行脚本时会打印这两个值，后续直接复用，不手写猜测 ID。

2. 建立会话

追加以下代码。POST /agent/v1/sessions 把刚创建的版本固定在会话中。省略 environment_id 使用轻型机器；这一步不需要先创建沙箱。示例显式设置 100 美分的会话预算，不把预算金额当作预计费用。

const session = await request("/sessions", {
  agent: { type: "agent", id: agent.id, version: agent.version },
  title: "First API conversation",
  budget: { type: "limit", max_list_cost: { amount: "100", currency: "USD" } },
});
assert(session.id);
console.log({ session: session.id });

预期结果： HTTP 201，响应包含会话 id。此时还没有发送用户问题；即使状态为 idle，也不代表已经得到回复。预算决定后续请求能否继续，不保证生成特定答案。

3. 发送第一条消息

追加以下代码，调用 POST /agent/v1/sessions/{session_id}/events。events 是输入数组；这里发送一条 user.message，其中只有一个非空文本块。

const accepted = await request(`/sessions/${session.id}/events`, {
  events: [{ type: "user.message", content: [{ type: "text", text: "What is 2 + 2?" }] }],
});
assert(accepted.data.some(event => event.type === "user.message"));

预期结果： HTTP 200，data 中出现已接收的用户事件。这是接收确认；不要把它当作智能体答案，也不要因为暂时没有答案就再次发送同一条消息。

4. 读取并验证回复

追加以下代码，然后执行 node first-agent.mjs 或 bun first-agent.mjs。它用 GET /agent/v1/sessions/{session_id}/events 分页读取事件，先找到 agent.message，再找到其后的 session.status_idle。初始空闲状态不会被误判为成功。

let completed = false;
const deadline = Date.now() + 120_000;
while (Date.now() < deadline) {
  const events = [];
  let page;
  do {
    const query = new URLSearchParams({ order: "asc", limit: "100" });
    if (page) query.set("page", page);
    const result = await request(`/sessions/${session.id}/events?${query}`);
    events.push(...result.data);
    page = result.next_page;
  } while (page && Date.now() < deadline);
  const reply = events.findIndex(event => event.type === "agent.message");
  const idle = events.findIndex((event, i) => i > reply && event.type === "session.status_idle");
  if (reply >= 0 && idle > reply) {
    const text = events.filter(event => event.type === "agent.message")
      .flatMap(event => event.content ?? []).filter(block => block.type === "text")
      .map(block => block.text).join("\n");
    assert(text.trim(), "Expected a nonempty reply");
    console.log({ reply: text, completed: true });
    completed = true;
    break;
  }
  await delay(1500);
}
assert(completed, `No completed reply before timeout; inspect session ${session.id}`);

完成判定： 进程正常退出，输出非空 reply 和 completed: true，答案应表达 4。脚本的 120 秒是本例等待期限，不是服务运行上限。只通过文本非空断言还不足以验证业务答案；上线前为实际问题准备预期结果。

失败时检查

症状	下一步
HTTP 401	检查服务端 Key 是否存在、有效，是否对应当前环境
HTTP 400	核对字段与模型；错误详情见限制与错误
HTTP 404	使用创建响应里的 ID，确认组织与所选版本一致
HTTP 429 或临时上游失败	按响应重试提示退避；先查询会话，避免重新创建资源或重复发消息
超时仍无完成回复	保留会话 ID，读取事件检查工具等待、预算或运行错误；不要仅依据创建响应的状态判断

重新运行整份脚本会新建智能体和会话。排错时优先查询已输出的 ID。测试记录可在确认不再需要后按 API 参考处理，不要把仍在运行的会话当作可直接删除的记录。

下一步

继续配置智能体、了解智能体与会话，或用 PraxisKit 接入网页。

交给你的代理：

按 /docs/developers/agent/quickstart 在服务端运行首次对话。
需要我提供 Develop 组织 API Key，并确认 deepseek-flash 可用。
完成标准：收到非空 agent.message，其后出现 session.status_idle。
不要把 Key 放进浏览器或日志；记录智能体 ID、版本和会话 ID。