创建部署

POST

deployments

创建部署

curl --request POST \
  --url http://localhost:38080/v1/deployments \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'anthropic-beta: <anthropic-beta>' \
  --header 'anthropic-version: <anthropic-version>' \
  --data '
{
  "name": "<string>",
  "agent": "<string>",
  "environment_id": "<string>",
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "我的订单 #1234 到哪里了？"
        }
      ]
    }
  ],
  "description": "<string>"
}
'

import requests

url = "http://localhost:38080/v1/deployments"

payload = {
    "name": "<string>",
    "agent": "<string>",
    "environment_id": "<string>",
    "initial_events": [
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "我的订单 #1234 到哪里了？"
                }
            ]
        }
    ],
    "description": "<string>"
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "anthropic-beta": "<anthropic-beta>",
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'anthropic-beta': '<anthropic-beta>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    agent: '<string>',
    environment_id: '<string>',
    initial_events: [{type: 'user.message', content: [{type: 'text', text: '我的订单 #1234 到哪里了？'}]}],
    description: '<string>'
  })
};

fetch('http://localhost:38080/v1/deployments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/deployments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"agent\": \"<string>\",\n  \"environment_id\": \"<string>\",\n  \"initial_events\": [\n    {\n      \"type\": \"user.message\",\n      \"content\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"我的订单 #1234 到哪里了？\"\n        }\n      ]\n    }\n  ],\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("anthropic-beta", "<anthropic-beta>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "type": "deployment",
  "id": "depl_011CZkZcDH3vPqd7xnEfwTai",
  "name": "每日订单报告",
  "description": "每个工作日早晨将前一天的订单汇总为报告。",
  "agent": {
    "type": "agent",
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "version": 1
  },
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "将昨天的订单汇总到 report.md。"
        }
      ]
    }
  ],
  "resources": [],
  "metadata": {},
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "America/Los_Angeles",
    "last_run_at": "2026-03-16T16:00:09Z",
    "upcoming_runs_at": [
      "2026-03-17T16:00:00Z",
      "2026-03-18T16:00:00Z"
    ]
  },
  "status": "active",
  "paused_reason": null,
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

每个请求都必须发送 ?beta=true、anthropic-version: 2023-06-01 与 anthropic-beta: managed-agents-2026-04-01。

授权

X-Api-Key

string

header

默认值:sk-ant-local-default

必填

OMA 工作区 API 密钥。

请求头

anthropic-version

string

必填

anthropic-beta

string

必填

查询参数

beta

enum<boolean>

必填

为此接口启用 Beta API 合同，必须为 true。

可用选项:

true

请求体

application/json

创建 deployment 的请求参数。

name

string

必填

部署的人类可读名称。

Required string length: 1 - 256

agent

必填

要部署的智能体。可传入 agent ID 字符串（将固定最新版本），或同时指定 ID 和 version 的 agent 对象。该智能体必须存在且未被归档。

environment_id

string

必填

定义此部署所创建会话的容器配置的 environment 的 ID。

Required string length: 1 - 128

initial_events

object[]

必填

创建后立即发送给每个会话的事件。至少 1 个，最多 50 个。

向会话发送用户消息的参数。

Option 1
Option 2
Option 3

Show child attributes

示例:

{
  "type": "user.message",
  "content": [
    {
      "type": "text",
      "text": "我的订单 #1234 到哪里了？"
    }
  ]
}

description

string | null

对部署功能的描述。

Maximum string length: 2048

vault_ids

string[]

存储凭据的密钥库 ID，智能体可在此部署创建的会话中使用这些凭据。最多 50 个。

resources

object[]

要挂载到每个会话容器中的资源（如代码仓库、文件）。最多 500 个。

将 GitHub 仓库挂载到会话的容器中。

Option 1
Option 2
Option 3

Show child attributes

示例:

{
  "type": "file",
  "url": "https://github.com/example-org/example-repo",
  "authorization_token": "ghp_exampletoken",
  "mount_path": "/uploads/receipt.pdf"
}

metadata

object

任意键值元数据。最多 16 对，键最多 64 个字符，值最多 512 个字符。

Show child attributes

schedule

object | null

可选的周期性 cron 调度。存在时，部署会自动触发。设置 schedule 时，expression 和 timezone 均为必填。

Show child attributes

示例:

{
  "type": "cron",
  "expression": "0 9 * * 1-5",
  "timezone": "America/Los_Angeles"
}

budget

object | null

加盖到从该部署创建的每个会话上的强制消费上限，在会话创建时复制。省略则会话不设上限。部署智能体的模型必须有公开的列表价格，否则请求将被拒绝；多智能体名册在每次触发复制该上限时会被完整重新校验，并以同样的方式失败即拒绝。

Show child attributes

响应

请求成功。

部署是智能体的一个已配置实例——它将智能体绑定到自主运行所需的一切：环境、凭据、初始事件，以及可选的调度计划。

type

enum<string>

必填

可用选项:

deployment

示例:

"deployment"

string

必填

此部署的唯一标识符。

示例:

"depl_011CZkZcDH3vPqd7xnEfwTai"

name

string

必填

人类可读的名称。

示例:

"每日订单报告"

description

string | null

必填

对部署功能的描述。

示例:

"每个工作日早晨将昨天的订单汇总为报告。"

agent

object

必填

该部署所运行的智能体的引用，已解析为具体版本。

Show child attributes

示例:

{
  "type": "agent",
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "version": 1
}

environment_id

string

必填

会话运行所在 environment 的 ID。

示例:

"env_011CZkZ9X2dpNyB7HsEFoRfW"

vault_ids

string[]

必填

为从此部署创建的会话提供已存储凭据的密钥库 ID 列表。

示例:

["vlt_011CZkZDLs7fYzm1hXNPeRjv"]

initial_events

object[]

必填

每个会话创建后立即发送的事件。

发送到会话的用户消息。

Option 1
Option 2
Option 3

Show child attributes

示例:

[
  {
    "type": "user.message",
    "content": [
      {
        "type": "text",
        "text": "将昨天的订单汇总到 report.md。"
      }
    ]
  }
]

resources

object[]

必填

附加到此部署所创建会话的资源。回显输入内容，但不包括只写凭据。

挂载到每个会话容器中的 GitHub 仓库。授权令牌为只写，不会被返回。

Option 1
Option 2
Option 3

Show child attributes

示例:

[]

metadata

object

必填

任意键值元数据。最多 16 对。

Show child attributes

示例:

{}

schedule

object | null

必填

周期性 cron 调度。存在时启用计划执行；为 null 表示仅手动执行。cron 变体包含计算得出的时间戳（下次触发时间、上次运行时间）。

Show child attributes

示例:

{
  "type": "cron",
  "expression": "0 9 * * 1-5",
  "timezone": "America/Los_Angeles",
  "last_run_at": "2026-03-16T16:00:09Z",
  "upcoming_runs_at": [
    "2026-03-17T16:00:00Z",
    "2026-03-18T16:00:00Z"
  ]
}

status

enum<string>

必填

部署的计算状态：active 或 paused。已归档的部署会报告为 active，同时已设置 archived_at。

可用选项:

active,

paused

示例:

"active"

paused_reason

object

必填

部署被暂停的原因。仅当 status 为 paused 时非空；否则为 null。

Option 1
Option 2

Show child attributes

示例:

null

created_at

string<date-time>

必填

部署的创建时间。

示例:

"2026-03-15T10:00:00Z"

updated_at

string<date-time>

必填

部署的最后更新时间。

示例:

"2026-03-15T10:00:00Z"

archived_at

string<date-time> | null

必填

部署的归档时间。未归档时为 null。

示例:

null

budget

object | null

为该部署创建的每个会话设定的消费上限。未设置预算时不存在。

Show child attributes

创建部署

curl --request POST \
  --url http://localhost:38080/v1/deployments \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'anthropic-beta: <anthropic-beta>' \
  --header 'anthropic-version: <anthropic-version>' \
  --data '
{
  "name": "<string>",
  "agent": "<string>",
  "environment_id": "<string>",
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "我的订单 #1234 到哪里了？"
        }
      ]
    }
  ],
  "description": "<string>"
}
'

import requests

url = "http://localhost:38080/v1/deployments"

payload = {
    "name": "<string>",
    "agent": "<string>",
    "environment_id": "<string>",
    "initial_events": [
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "我的订单 #1234 到哪里了？"
                }
            ]
        }
    ],
    "description": "<string>"
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "anthropic-beta": "<anthropic-beta>",
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'anthropic-beta': '<anthropic-beta>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    agent: '<string>',
    environment_id: '<string>',
    initial_events: [{type: 'user.message', content: [{type: 'text', text: '我的订单 #1234 到哪里了？'}]}],
    description: '<string>'
  })
};

fetch('http://localhost:38080/v1/deployments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/deployments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"agent\": \"<string>\",\n  \"environment_id\": \"<string>\",\n  \"initial_events\": [\n    {\n      \"type\": \"user.message\",\n      \"content\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"我的订单 #1234 到哪里了？\"\n        }\n      ]\n    }\n  ],\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("anthropic-beta", "<anthropic-beta>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "type": "deployment",
  "id": "depl_011CZkZcDH3vPqd7xnEfwTai",
  "name": "每日订单报告",
  "description": "每个工作日早晨将前一天的订单汇总为报告。",
  "agent": {
    "type": "agent",
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "version": 1
  },
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "将昨天的订单汇总到 report.md。"
        }
      ]
    }
  ],
  "resources": [],
  "metadata": {},
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "America/Los_Angeles",
    "last_run_at": "2026-03-16T16:00:09Z",
    "upcoming_runs_at": [
      "2026-03-17T16:00:00Z",
      "2026-03-18T16:00:00Z"
    ]
  },
  "status": "active",
  "paused_reason": null,
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

开始使用

核心 API

托管智能体

Webhook

授权

请求头

查询参数

请求体

响应