创建会话
创建运行选定智能体版本的会话,初始状态为 idle。
- 未提供
agent_version时,将冻结最新可用的智能体版本,并固定环境最新构建就绪的版本。此后对二者的更新都不会改变此会话。 - 凭据库(Vault)与记忆库的绑定仅在创建时生效(最多 16 个凭据库和 8 个记忆库)。文件可以稍后添加。
- 使用
POST /v1/sessions/{id}/events发送第一条消息以开始任务。
curl --request POST \
--url https://api.moonshot.cn/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q"
}
'import requests
url = "https://api.moonshot.cn/v1/sessions"
payload = {
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 'agent_01h455vb4pex5vsknk084sn02q',
environment_id: 'env_01h455vb4pex5vsknk084sn02q'
})
};
fetch('https://api.moonshot.cn/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 'agent_01h455vb4pex5vsknk084sn02q',
'environment_id' => 'env_01h455vb4pex5vsknk084sn02q'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/sessions"
payload := strings.NewReader("{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/v1/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}"
response = http.request(request)
puts response.read_body{
"id": "sesn_01h455vb4pex5vsknk084sn02q",
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q",
"status": "idle",
"title": "示例会话",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}请求头
本次请求使用的 API 版本,格式为 YYYY-MM-DD。发送 2026-09-01-beta 即使用本文档所述版本。/v1/files* 之外必传:未携带请求头将被拒绝并返回 400 invalid_request_error;在 /v1/files* 上缺省时选择兼容行为。所有端点对未知取值均返回 400 invalid_request_error。
平台当前支持的 API 版本。新的日期版本发布时加入;版本在公告的 Sunset 日期后移除。
2026-09-01-beta 可选的幂等键。相同的键与请求体会在 24 小时内重放首个响应;以不同的请求体复用,或在首个请求仍在处理时复用,返回 409。
请求体
创建会话的请求体。仅 agent_id 与 environment_id 必填。
要运行的智能体。
会话使用的环境。其最新构建就绪的版本会在会话的整个生命周期内固定。环境必须可见、活跃且具有构建就绪的版本。
128可选的精确智能体版本("1"、"2"……)。默认为创建时的最新版本。
128可选的人类可读标题。
256用户自定义元数据(最多 16 条)。
Show child attributes
Show child attributes
创建时要绑定的资源:文件、凭据库(Vault)和记忆库。每个会话最多包含 16 个凭据库和 8 个记忆库,它们的绑定在创建后不能再添加或替换。
作为资源绑定到会话的文件。
- 文件
- 凭据库
- 记忆库
Show child attributes
Show child attributes
自创建起生效的会话级智能体配置覆盖。
Show child attributes
Show child attributes
响应
已创建的会话(idle),携带其资源绑定与智能体快照。
带版本智能体配置的一个运行实例。
会话 ID。
此会话运行的智能体。
托管此会话的环境。
当前生命周期状态。
idle, running, stopping, terminated 创建时间戳。
最后更新时间戳。
已提交的停止是否暂停执行。新消息或显式继续可以恢复执行。
会话当前的控制版本。
19^(0|[1-9][0-9]{0,18})$已接受继续请求,但尚未开始执行。
人类可读的标题。
用户自定义元数据(最多 16 条)。
Show child attributes
Show child attributes
会话级智能体配置覆盖。未存储任何覆盖时不存在。
Show child attributes
Show child attributes
归档时间戳。活跃期间不存在。
绑定到此会话的资源。在 GET /v1/sessions 的列表项中省略。
作为资源绑定到会话的文件。
- 文件
- 凭据库
- 记忆库
Show child attributes
Show child attributes
协调者线程使用的智能体版本快照。
Show child attributes
Show child attributes
此页面对您有帮助吗?
curl --request POST \
--url https://api.moonshot.cn/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q"
}
'import requests
url = "https://api.moonshot.cn/v1/sessions"
payload = {
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 'agent_01h455vb4pex5vsknk084sn02q',
environment_id: 'env_01h455vb4pex5vsknk084sn02q'
})
};
fetch('https://api.moonshot.cn/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 'agent_01h455vb4pex5vsknk084sn02q',
'environment_id' => 'env_01h455vb4pex5vsknk084sn02q'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/sessions"
payload := strings.NewReader("{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/v1/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"agent_01h455vb4pex5vsknk084sn02q\",\n \"environment_id\": \"env_01h455vb4pex5vsknk084sn02q\"\n}"
response = http.request(request)
puts response.read_body{
"id": "sesn_01h455vb4pex5vsknk084sn02q",
"agent_id": "agent_01h455vb4pex5vsknk084sn02q",
"environment_id": "env_01h455vb4pex5vsknk084sn02q",
"status": "idle",
"title": "示例会话",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}