# Configure your agent (/en/docs/developers/agent/configure)



Update a service agent's instructions, model and tools, then choose the version offered to end users. Saving configuration and selecting an embed version are separate actions. A pinned embed does not automatically adopt new configuration.



## Prepare your agent [#prepare]

You need an existing service agent and an organization account authorized to manage it. Open **Service agents → Select agent → Integration and configuration → Configuration** in the Dashboard. UI labels below describe the current Chinese Dashboard.

For API access, obtain the public `agent_…` ID from a create or retrieve response. Set `PRAXIS_API_BASE` to your environment's API origin and `PRAXIS_API_KEY` to its organization API Key on your server. Keep the Key out of browser code. The example requires Node.js with native `fetch` and `PRAXIS_AGENT` set to the real public ID.

## Update and save configuration [#save]

<Tabs items="['Dashboard', 'API']">
  <Tab value="Dashboard">
    1. In &#x2A;*Instructions (指令)**, define the agent's role, answer scope and response when information is missing.
    2. In &#x2A;*Model (模型)**, select an available model, such as `deepseek-flash` when listed for your organization.
    3. In &#x2A;*Tools and authorization (工具与授权)**, enable tools and choose automatic execution or confirmation on every call. Configure MCP servers in &#x2A;*MCP and credentials (MCP 与凭据)**. Tools must still authorize users on the server.
    4. Review changed groups in the bottom save bar and click &#x2A;*Save (保存)**.

    **Expected:** The configuration version increases. Reopening Instructions shows the saved text. Leaving with unsaved changes prompts you to handle them.
  </Tab>

  <Tab value="API">
    Save this as `configure-agent.mjs` and run `node configure-agent.mjs` on your server. It reads the current version, updates instructions and model with `POST /agent/v1/agents/{agent_id}`, then reads back the result.

    ```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 });
    ```

    **Expected:** The script prints `verified: true` and the new version. The model must be available to your organization. Concurrent edits cause version validation to reject the update. Read the latest configuration and reconcile changes before trying again. See the [Agent API](/en/docs/api/native/agent) for all fields.
  </Tab>
</Tabs>

## Save embed settings separately [#embed-settings]

Embed security policies, vault selection and embed version pinning **can currently only be configured in the Dashboard**.

In &#x2A;*Configuration → Security (安全)**, select an available environment, add your website origin, and set token lifetime and budgets. Click &#x2A;*Save security settings (保存安全设置)**. Lifetime inputs use minutes and budget inputs use US dollars. Do not paste API seconds or cents into these fields. See [Secure your embed](/en/docs/developers/agent/embed/security) for origin rules.

For vaults, select them in MCP and credentials and click &#x2A;*Save vaults (保存凭据库)**. &#x2A;*Expected:** Both saves display “已保存，不产生新版本” (saved without creating a version). These settings are separate from the configuration draft in the bottom save bar.

## Select the embed version [#versions]

Open &#x2A;*Integration and configuration → Versions (版本)**. Click a version to compare it with its predecessor. Choose &#x2A;*Set as embed version (设为嵌入版本)** or &#x2A;*Roll back to this version (回滚到此版本)** and confirm. Check the &#x2A;*Embedded (嵌入中)** badge. Choose &#x2A;*Unpin (取消固定)** to follow the latest version again. Save a security policy first if none exists.

An explicit `version` in token issuance takes precedence over the pinned version. When omitted, issuance uses the pinned version, or the latest when unpinned. **Existing tokens retain their version**, including after rollback. Issue a new token and start a new session to verify a change.

## Verify and continue [#verify]

In &#x2A;*Playground (试用调试)**, select the saved version and ask a question that distinguishes the new instructions from the old ones. Check the actual reply. Then obtain a new token in your host application, start a session, and confirm its version under **Operations → Sessions**. A loaded interface alone does not prove the new configuration is in use.

Service agents do not currently support per-message model switching, tool modes, voice input or per-end-user memory. Configuration's appearance section is a placeholder; use [Customize appearance](/en/docs/developers/agent/embed/appearance).

Next: [Test your embed](/en/docs/developers/agent/embed/testing) · [Agent API](/en/docs/api/native/agent) · [Cookbook](/en/docs/cookbook)