> ## 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.

# Create Agent Version

> Create a new version of an agent with updated configuration

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

Creates a new version of the specified agent. The new version uses merge semantics: only the fields you supply override the previous version's values. Omitted fields carry forward from the current version unchanged.

This is how you update an agent's model, capabilities, policies, subagents, skills, system prompt, and other configuration. The agent's `version` field automatically advances to the newly created version.

<Note>
  **Permission required:** `agent:version_create`
</Note>

### Path Parameters

<ParamField path="id" type="string" required>
  Agent identifier
</ParamField>

### Request Body

All fields are optional. Only supplied fields override the previous version.

<ParamField body="model" type="string">
  Model to use for this version
</ParamField>

<ParamField body="capabilities" type="array">
  Updated list of capability identifiers
</ParamField>

<ParamField body="policies" type="object">
  Updated execution policies

  <Expandable title="Policies object">
    <ParamField body="policies.max_turns" type="integer">Maximum number of conversation turns per run</ParamField>
    <ParamField body="policies.max_tool_calls" type="integer">Maximum number of tool calls per turn</ParamField>
    <ParamField body="policies.allow_tools" type="array">Allowlist of tool names the agent may invoke</ParamField>
    <ParamField body="policies.deny_tools" type="array">Denylist of tool names the agent must not invoke</ParamField>
    <ParamField body="policies.subagent_timeout" type="integer">Maximum seconds a subagent may run before being cancelled</ParamField>
    <ParamField body="policies.subagent_max_concurrency" type="integer">Maximum number of subagents that may run concurrently</ParamField>
  </Expandable>
</ParamField>

<ParamField body="output" type="object">
  Updated output configuration

  <Expandable title="Output object">
    <ParamField body="output.mode" type="string">Output mode (`text` or `json`)</ParamField>
    <ParamField body="output.json_schema" type="object">JSON Schema that the agent's output must conform to when mode is `json`</ParamField>
  </Expandable>
</ParamField>

<ParamField body="subagents" type="array">
  Updated subagent definitions

  <Expandable title="Subagent object">
    <ParamField body="subagents[].name" type="string">Subagent name</ParamField>
    <ParamField body="subagents[].mode" type="string">Execution mode for the subagent</ParamField>
    <ParamField body="subagents[].context" type="string">Context instructions passed to the subagent</ParamField>
    <ParamField body="subagents[].inherit_tools" type="boolean">Whether the subagent inherits the parent agent's tools</ParamField>
  </Expandable>
</ParamField>

<ParamField body="skills" type="array">
  Updated skill references

  <Expandable title="Skill reference">
    <ParamField body="skills[].skill_id" type="string">Skill identifier</ParamField>
    <ParamField body="skills[].skill_version" type="integer">Skill version number</ParamField>
  </Expandable>
</ParamField>

<ParamField body="system_prompt" type="string">
  Updated system prompt
</ParamField>

<ParamField body="model_settings" type="object">
  Updated model-specific settings
</ParamField>

<ParamField body="runtime_bindings" type="object">
  Updated runtime binding configuration
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/agents/agt_r8k2m1n3/versions' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gpt-4o",
      "capabilities": ["tool_use", "memory_read", "memory_write"],
      "policies": {
        "max_turns": 25,
        "max_tool_calls": 15
      },
      "skills": [
        {
          "skill_id": "skl_kb_search",
          "skill_version": 3
        }
      ],
      "model_settings": {
        "temperature": 0.5,
        "max_tokens": 8192
      }
    }'
  ```
</RequestExample>

### Response

<ResponseField name="data" type="object">
  <Expandable title="Agent version object">
    <ResponseField name="version" type="integer">Version number of the newly created version</ResponseField>
    <ResponseField name="model" type="string">Model used in this version</ResponseField>
    <ResponseField name="capabilities" type="array">List of capability identifiers</ResponseField>

    <ResponseField name="policies" type="object">
      Execution policies for this version

      <Expandable title="Policies object">
        <ResponseField name="max_turns" type="integer">Maximum number of conversation turns per run</ResponseField>
        <ResponseField name="max_tool_calls" type="integer">Maximum number of tool calls per turn</ResponseField>
        <ResponseField name="allow_tools" type="array">Allowlist of tool names the agent may invoke</ResponseField>
        <ResponseField name="deny_tools" type="array">Denylist of tool names the agent must not invoke</ResponseField>
        <ResponseField name="subagent_timeout" type="integer">Maximum seconds a subagent may run before being cancelled</ResponseField>
        <ResponseField name="subagent_max_concurrency" type="integer">Maximum number of subagents that may run concurrently</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="output" type="object">
      Output configuration for this version

      <Expandable title="Output object">
        <ResponseField name="mode" type="string">Output mode</ResponseField>
        <ResponseField name="json_schema" type="object">JSON Schema for structured output</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="subagents" type="array">
      Subagent definitions in this version

      <Expandable title="Subagent object">
        <ResponseField name="name" type="string">Subagent name</ResponseField>
        <ResponseField name="mode" type="string">Execution mode for the subagent</ResponseField>
        <ResponseField name="context" type="string">Context instructions passed to the subagent</ResponseField>
        <ResponseField name="inherit_tools" type="boolean">Whether the subagent inherits the parent agent's tools</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="skills" type="array">
      Skills in this version

      <Expandable title="Skill reference">
        <ResponseField name="skill_id" type="string">Skill identifier</ResponseField>
        <ResponseField name="skill_version" type="integer">Skill version number</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="agent_id" type="string">Parent agent identifier</ResponseField>
    <ResponseField name="system_prompt" type="string">System prompt used in this version</ResponseField>
    <ResponseField name="model_settings" type="object">Model-specific settings for this version</ResponseField>
    <ResponseField name="runtime_bindings" type="object">Runtime binding configuration for this version</ResponseField>
    <ResponseField name="created_at" type="string">Version creation timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "version": 4,
      "model": "gpt-4o",
      "capabilities": ["tool_use", "memory_read", "memory_write"],
      "policies": {
        "max_turns": 25,
        "max_tool_calls": 15,
        "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": "delegate",
          "context": "Create support tickets from conversation context",
          "inherit_tools": false
        }
      ],
      "skills": [
        {
          "skill_id": "skl_kb_search",
          "skill_version": 3
        }
      ],
      "agent_id": "agt_r8k2m1n3",
      "system_prompt": "You are a helpful support assistant. Use the knowledge base to answer questions accurately.",
      "model_settings": {
        "temperature": 0.5,
        "max_tokens": 8192
      },
      "runtime_bindings": {
        "knowledge_base": "kb_prod_docs"
      },
      "created_at": "2025-05-15T10:00:00Z"
    }
  }
  ```
</ResponseExample>