# 配置智能体 (/docs/developers/agent/configure)



修改服务智能体的指令、模型和工具，再选择向终端用户提供哪一个版本。配置保存与嵌入版本选择是两个动作；固定版本后，保存新配置不会自动升级嵌入。



## 准备智能体 [#prepare]

准备一个已有的服务智能体，以及有权管理它的组织账户。打开控制台「服务智能体 → 选择智能体 → 接入与配置 → 配置」。下面的控件名称对应当前中文控制台。

使用 API 时，从创建或查询响应取得公开 ID `agent_…`。在服务器设置 `PRAXIS_API_BASE` 为所用环境的 API 源站地址，`PRAXIS_API_KEY` 为该组织的 API Key；不要把 Key 放入网页。下例还需 Node.js（支持原生 `fetch`），并将 `PRAXIS_AGENT` 设置为真实公开 ID。

## 修改并保存配置 [#save]

<Tabs items="['控制台', 'API']">
  <Tab value="控制台">
    1. 在「指令」写明角色、回答范围和无法回答时的处理方式。
    2. 在「模型」选择可用模型，例如目录中可用的 `deepseek-flash`。
    3. 在「工具与授权」启用所需工具，选择「自动执行」或「每次询问」。MCP 服务器在「MCP 与凭据」中配置；工具仍须在服务端核验用户权限。
    4. 检查底部保存栏中的改动分组，点击「保存」。

    **预期结果：** 当前配置的版本号增加；重新打开「指令」能看到保存内容。未保存的修改离开页面时会提示处理。
  </Tab>

  <Tab value="API">
    将下面内容保存为 `configure-agent.mjs`，在服务器执行 `node configure-agent.mjs`。它先读取当前版本，再通过 `POST /agent/v1/agents/{agent_id}` 更新指令和模型，最后读取新版本验证。

    ```js
    import assert from 'node:assert/strict';

    const { PRAXIS_API_BASE, PRAXIS_API_KEY, PRAXIS_AGENT } = process.env;
    assert(PRAXIS_API_BASE && PRAXIS_API_KEY && PRAXIS_AGENT, 'Set the three environment variables');
    assert(PRAXIS_AGENT.startsWith('agent_'), 'Use the public agent ID');
    const url = `${PRAXIS_API_BASE.replace(/\/$/, '')}/agent/v1/agents/${encodeURIComponent(PRAXIS_AGENT)}`;
    async function request(method, body) {
      const response = await fetch(url, {
        method,
        headers: { Authorization: `Bearer ${PRAXIS_API_KEY}`, 'Content-Type': 'application/json' },
        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
      });
      if (!response.ok) throw new Error(`Agent request failed: HTTP ${response.status}`);
      return response.json();
    }
    const before = await request('GET');
    const system = 'You help customers understand our courses. Ask for missing details; do not invent course policies.';
    const saved = await request('POST', { version: before.version, system, model: 'deepseek-flash' });
    const after = await request('GET');
    assert(saved.version > before.version);
    assert.equal(after.version, saved.version);
    assert.equal(after.system, system);
    assert.equal(after.model.id, 'deepseek-flash');
    console.log({ id: after.id, version: after.version, verified: true });
    ```

    **预期结果：** 输出 `verified: true` 和新版本号。模型必须在你的组织中可用。若有其他人同时修改，版本校验会拒绝覆盖；重新读取并核对改动后再执行。完整字段见[智能体 API](/docs/api/native/agent)。
  </Tab>
</Tabs>

## 单独保存嵌入设置 [#embed-settings]

嵌入安全策略、凭据库选择与嵌入版本固定**目前只能在控制台配置**。

在「配置 → 安全」选择可用运行环境，填写你的网站来源，并设置令牌有效期与预算，然后点击「保存安全设置」。有效期界面单位为分钟，预算单位为美元；不要直接把接口的秒数或美分数填入界面。来源规则见[保护嵌入接入](/docs/developers/agent/embed/security)。

需要凭据库时，在「MCP 与凭据」勾选后点击「保存凭据库」。&#x2A;*预期结果：** 两种保存均显示「已保存，不产生新版本」。它们不属于底部保存栏的配置草稿。

## 选择嵌入版本 [#versions]

进入「接入与配置 → 版本」。点击版本号查看与上一版本的差异，再选择「设为嵌入版本」或旧版本的「回滚到此版本」，确认后检查「嵌入中」标记。需要恢复跟随最新时点击「取消固定」。没有安全策略时，先完成上一步。

签发时显式指定的 `version` 优先于控制台固定版本；省略时使用固定版本，未固定才取最新版本。**已经签发的令牌保持原版本**，回滚不会改变它们。验证升级或回滚时，应重新签发令牌并开始新会话。

## 验证与下一步 [#verify]

进入「试用调试」，选择刚保存的版本，发送一个能区分新旧指令的问题，检查真实回复。随后在宿主网页重新取得令牌，开始新会话，并在「运营与管理 → 会话」核对版本。只看到界面加载不能证明新配置已被使用。

服务智能体目前不支持按消息切换模型、工具模式、语音输入和按终端用户的记忆；「配置 → 开场与外观」仍是占位，外观操作见[自定义外观](/docs/developers/agent/embed/appearance)。

下一步：[测试嵌入接入](/docs/developers/agent/embed/testing) · [智能体 API](/docs/api/native/agent) · [Cookbook](/docs/cookbook)