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

# Fork Agent

> Copy an agent into a new, independent agent

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

Copies an agent into a new agent with its own `id` and its own [actor](/features/memorylake/api-reference/actors/overview). Use it to start from an agent you have already tuned instead of configuring a new one from scratch.

The copy takes the source agent's description and its latest version — model, system prompt, capabilities, policies, output, subagents, skills, model settings and runtime bindings — and starts at version 1. From then on the two agents are independent: changing either one does not affect the other.

The copy does not take:

* **Version history.** Only the latest version is carried over, as version 1.
* **`metadata`.** Set it on the copy with the `metadata` field below.
* **Workspace bindings.** [Bind the copy](/features/memorylake/api-reference/agents/bind-agent) to a workspace before you call it over A2A.
* **Memory.** The copy has a new actor, so it starts without any facts of its own.

Only `INTERNAL` agents can be forked. Forking an `EXTERNAL` agent fails with `AGENT_OPERATION_NOT_SUPPORTED`.

<Note>
  **Permission required:** `agent:create`, plus `agent:read` on the source agent
</Note>

### Path Parameters

<ParamField path="id" type="string" required>
  ID of the agent to copy. This endpoint does not accept `by_custom_id`, so pass the agent's `id`.
</ParamField>

### Request Body

<ParamField body="custom_id" type="string" required>
  Your own identifier for the copy. Must be unique within your tenant and must not start with `_sys_`. See [Your own identifiers](/features/memorylake/api-reference/overview#your-own-identifiers).
</ParamField>

<ParamField body="name" type="string">
  Name of the copy, 1–255 characters. When omitted, the copy is named after the source agent with ` (copy)` appended, for example `Support Assistant (copy)`.
</ParamField>

<ParamField body="metadata" type="object">
  Key-value pairs for the copy. Values must be strings. The source agent's metadata is not copied.
</ParamField>

<Tip>
  Each call creates a new agent, so retrying a request that timed out can leave you with two copies. Reuse the same `custom_id` when you retry: if the first call went through, the retry fails with `409` and `CUSTOM_ID_CONFLICT` instead of creating a second copy.
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.memorylake.ai/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>

### Response

Returns the new agent, with the same fields as [Get Agent](/features/memorylake/api-reference/agents/get-agent).

<ResponseField name="data" type="object">
  <Expandable title="Agent object">
    <ResponseField name="id" type="string">ID of the new agent</ResponseField>
    <ResponseField name="name" type="string">Name of the new agent</ResponseField>
    <ResponseField name="custom_id" type="string">The `custom_id` you passed</ResponseField>
    <ResponseField name="metadata" type="object">The `metadata` you passed. Absent when you passed none</ResponseField>
    <ResponseField name="actor_id" type="string">The new agent's own actor, different from the source agent's</ResponseField>
    <ResponseField name="agent_type" type="string">Always `INTERNAL`</ResponseField>
    <ResponseField name="version" type="integer">Current version number. Always `1` for a new copy</ResponseField>
    <ResponseField name="latest_version" type="integer">Latest version number. Always `1` for a new copy</ResponseField>
    <ResponseField name="description" type="string">Copied from the source agent</ResponseField>
    <ResponseField name="model" type="string">Copied from the source agent's latest version, as are `system_prompt`, `capabilities`, `policies`, `output`, `subagents`, `skills`, `model_settings` and `runtime_bindings`</ResponseField>
  </Expandable>
</ResponseField>

### Errors

| Status | Error code | When |
| - | - | - |
| `400` | `INVALID_ARGUMENT` | `custom_id` is missing or starts with `_sys_`; `name` is blank or longer than 255 characters; or `name` is omitted and the source agent has no name, or its name is too long to take the ` (copy)` suffix |
| `400` | `AGENT_OPERATION_NOT_SUPPORTED` | The source agent is `EXTERNAL` |
| `404` | `NOT_FOUND` | No agent with this `id` exists in your tenant |
| `409` | `CUSTOM_ID_CONFLICT` | Another agent in your tenant already uses this `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": {"web_search": {"max_results": 5, "search_depth": "basic", "chunks_per_source": 2, "open_datasets": ["research/academic"]}},
      "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.