> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 复制 Agent

> 把一个 Agent 复制成一个新的、相互独立的 Agent

```
POST /openapi/memorylake/api/v3/agents/{id}/fork
```

把一个 Agent 复制（fork）成一个新 Agent，新 Agent 有自己的 `id` 和自己的 [Actor](/features/memorylake/api-reference/actors/overview)。已经调好一个 Agent、想以它为模板再做一个时，用这个接口，不必从零重新配置。

副本会带上源 Agent 的描述和它的最新版本（模型、系统提示词、能力、策略、输出、子 Agent、技能、模型设置和运行时绑定），并从版本 1 开始。此后两个 Agent 相互独立，修改其中任何一个都不会影响另一个。

副本不会带上：

* **版本历史。** 只复制最新版本，作为副本的版本 1。
* **`metadata`。** 用下面的 `metadata` 字段给副本设置。
* **工作空间绑定。** 通过 A2A 调用副本之前，先把它[绑定到工作空间](/features/memorylake/api-reference/agents/bind-agent)。
* **记忆。** 副本有新的 Actor，因此一开始没有任何属于自己的事实。

只有 `INTERNAL` 类型的 Agent 可以复制。复制 `EXTERNAL` 类型的 Agent 会返回 `AGENT_OPERATION_NOT_SUPPORTED`。

<Note>
  **所需权限：** `agent:create`，以及源 Agent 的 `agent:read`
</Note>

### 路径参数

<ParamField path="id" type="string" required>
  要复制的 Agent 的 ID。这个接口不支持 `by_custom_id`，请传 Agent 的 `id`。
</ParamField>

### 请求体

<ParamField body="custom_id" type="string" required>
  您为副本指定的自定义标识符。在您的租户内必须唯一，且不能以 `_sys_` 开头。参见[您自己的标识符](/features/memorylake/api-reference/overview#您自己的标识符)。
</ParamField>

<ParamField body="name" type="string">
  副本名称，1–255 个字符。省略时，副本名称为源 Agent 名称加上后缀 ` (copy)`，例如 `Support Assistant (copy)`。
</ParamField>

<ParamField body="metadata" type="object">
  副本的键值对，值必须是字符串。源 Agent 的 metadata 不会被复制。
</ParamField>

<Tip>
  每次调用都会新建一个 Agent，所以重试一个超时的请求，可能会得到两个副本。重试时沿用同一个 `custom_id`：如果第一次调用其实已经成功，重试会返回 `409` 和 `CUSTOM_ID_CONFLICT`，而不会再建一个副本。
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.memorylake.cn/openapi/memorylake/api/v3/agents/agent-f8bf71ab17ed8eccad8c0e8ae708273f/fork' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "custom_id": "support-assistant-eu",
      "name": "Support Assistant (EU)",
      "metadata": {
        "region": "eu"
      }
    }'
  ```
</RequestExample>

### 响应

返回新建的 Agent，字段与[获取 Agent](/features/memorylake/api-reference/agents/get-agent) 相同。

<ResponseField name="data" type="object">
  <Expandable title="Agent 对象">
    <ResponseField name="id" type="string">新 Agent 的 ID</ResponseField>
    <ResponseField name="name" type="string">新 Agent 的名称</ResponseField>
    <ResponseField name="custom_id" type="string">您传入的 `custom_id`</ResponseField>
    <ResponseField name="metadata" type="object">您传入的 `metadata`。没有传时不返回</ResponseField>
    <ResponseField name="actor_id" type="string">新 Agent 自己的 Actor，与源 Agent 的不同</ResponseField>
    <ResponseField name="agent_type" type="string">恒为 `INTERNAL`</ResponseField>
    <ResponseField name="version" type="integer">当前版本号。新副本恒为 `1`</ResponseField>
    <ResponseField name="latest_version" type="integer">最新版本号。新副本恒为 `1`</ResponseField>
    <ResponseField name="description" type="string">从源 Agent 复制</ResponseField>
    <ResponseField name="model" type="string">从源 Agent 的最新版本复制，`system_prompt`、`capabilities`、`policies`、`output`、`subagents`、`skills`、`model_settings` 和 `runtime_bindings` 同样如此</ResponseField>
  </Expandable>
</ResponseField>

### 错误

| 状态码 | 错误码 | 何时出现 |
| - | - | - |
| `400` | `INVALID_ARGUMENT` | 缺少 `custom_id` 或它以 `_sys_` 开头；`name` 为空白或超过 255 个字符；或省略了 `name`，而源 Agent 没有名称，或其名称过长、加上 ` (copy)` 后缀会超长 |
| `400` | `AGENT_OPERATION_NOT_SUPPORTED` | 源 Agent 是 `EXTERNAL` 类型 |
| `404` | `NOT_FOUND` | 您的租户内没有这个 `id` 的 Agent |
| `409` | `CUSTOM_ID_CONFLICT` | 您的租户内已有其他 Agent 使用这个 `custom_id` |

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "id": "agent-3c1e9a7d52b84f06a9d1e7c4b8f20a65",
      "name": "Support Assistant (EU)",
      "description": "Handles customer support inquiries using knowledge base",
      "metadata": {
        "region": "eu"
      },
      "version": 1,
      "model": "gpt-4o",
      "capabilities": ["tool_use", "memory_read", "memory_write"],
      "policies": {
        "max_turns": 20,
        "max_tool_calls": 10,
        "allow_tools": ["search_kb", "create_ticket"],
        "deny_tools": [],
        "subagent_timeout": 300,
        "subagent_max_concurrency": 3
      },
      "output": {
        "mode": "text",
        "json_schema": null
      },
      "subagents": [
        {
          "name": "ticket-creator",
          "mode": "fork",
          "context": "Create support tickets from conversation context",
          "inherit_tools": false
        }
      ],
      "skills": [],
      "custom_id": "support-assistant-eu",
      "actor_id": "actor-5b7d2e90c41f4a3e8d6b1c0f9a2e7d34",
      "agent_type": "INTERNAL",
      "latest_version": 1,
      "system_prompt": "You are a helpful support assistant. Use the knowledge base to answer questions accurately.",
      "model_settings": {
        "temperature": 0.7,
        "max_tokens": 4096
      },
      "runtime_bindings": {
        "knowledge_base": "kb_prod_docs"
      }
    }
  }
  ```

  ```json custom_id taken (409) theme={null}
  {
    "success": false,
    "message": "custom_id 'support-assistant-eu' already exists",
    "error_code": "CUSTOM_ID_CONFLICT"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.