initial_events 将这两个步骤合并为一次调用。
托管智能体 API 请求需要
managed-agents-2026-04-01 Beta 请求头，但记忆存储端点除外，它们使用 agent-memory-2026-07-22。SDK 会自动设置正确的 Beta 请求头。请参阅Beta 请求头。创建会话
会话需要一个agent ID 和一个 environment ID。智能体是带版本的资源；以字符串形式传入 agent ID 会使用最新的智能体版本启动会话。
session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")
ant beta:sessions create \
--agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID"
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
)
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id
});
var session = await client.Beta.Sessions.Create(new()
{
Agent = agent.ID,
EnvironmentID = environment.ID,
});
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(agent.ID),
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(agent.id())
.environmentId(environment.id())
.build());
$session = $client->beta->sessions->create(
agent: $agent->id,
environmentID: $environment->id,
);
session = client.beta.sessions.create(
agent: agent.id,
environment_id: environment.id
)
pinned_session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
ant beta:sessions create <<YAML
agent:
type: agent
id: $AGENT_ID
version: 1
environment_id: $ENVIRONMENT_ID
YAML
pinned_session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": 1},
environment_id=environment.id,
)
const pinnedSession = await client.beta.sessions.create({
agent: { type: "agent", id: agent.id, version: 1 },
environment_id: environment.id
});
var pinnedSession = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentParams
{
Type = BetaManagedAgentsAgentParamsType.Agent,
ID = agent.ID,
Version = 1,
},
EnvironmentID = environment.ID,
});
pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: agent.ID,
Version: anthropic.Int(1),
},
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
.agent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(agent.id())
.version(1)
.build())
.environmentId(environment.id())
.build());
$pinnedSession = $client->beta->sessions->create(
agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
environmentID: $environment->id,
);
pinned_session = client.beta.sessions.create(
agent: {type: :agent, id: agent.id, version: 1},
environment_id: environment.id
)
使用初始事件为会话提供种子
您可以在一次调用中创建会话并启动其工作。initial_events 是一个可选数组，包含在创建时发送给会话的初始事件，按顺序处理。它支持 user.message 和 user.define_outcome 事件，最多接受 50 个事件。非空列表会在同一次调用中启动智能体循环：会话直接以 running 状态创建，无需进一步请求。
以下示例创建了一个在 initial_events 中包含单个 user.message 的会话：
seeded_session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"initial_events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "List the files in the working directory."}]
}
]
}
EOF
)
SEEDED_SESSION_ID=$(jq -r '.id' <<< "$seeded_session")
# initial_events 不会在创建响应中回显；列出会话的
# 事件即可看到植入的消息。
seeded_events=$(curl -fsSL \
"http://localhost:38080/v1/sessions/$SEEDED_SESSION_ID/events" \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01")
echo "Seeded event: $(jq -r \
'.data[] | select(.type == "user.message") | .content[0].text' <<< "$seeded_events")"
SEEDED_SESSION_ID=$(ant beta:sessions create \
--transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
- type: user.message
content:
- type: text
text: List the files in the working directory.
YAML
)
# initial_events 不会在创建响应中回显；列出会话的
# 事件即可看到植入的消息。
echo "Seeded event: $(ant beta:sessions:events list \
--session-id "$SEEDED_SESSION_ID" \
--format raw \
--transform 'data.#(type=="user.message").content.0.text' --raw-output)"
seeded_session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
initial_events=[
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
],
},
],
)
# initial_events 不会在创建响应中回显；需从
# 会话的事件列表中读回它们。
for event in client.beta.sessions.events.list(seeded_session.id):
if event.type == "user.message":
for block in event.content:
if block.type == "text":
print(f"Seeded event: {block.text}")
const seededSession = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id,
initial_events: [
{
type: "user.message",
content: [{ type: "text", text: "List the files in the working directory." }]
}
]
});
// initial_events 不会在创建响应中回显；需列出会话的
// 事件才能读回预置的消息。
for await (const event of client.beta.sessions.events.list(seededSession.id)) {
if (event.type === "user.message") {
for (const block of event.content) {
if (block.type === "text") {
console.log(`Seeded event: ${block.text}`);
}
}
}
}
var seededSession = await client.Beta.Sessions.Create(new()
{
Agent = agent.ID,
EnvironmentID = environment.ID,
InitialEvents =
[
new BetaManagedAgentsUserMessageEventParams
{
Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
Content =
[
new BetaManagedAgentsTextBlock
{
Type = BetaManagedAgentsTextBlockType.Text,
Text = "List the files in the working directory.",
},
],
},
],
});
// initial_events 不会在创建响应中回显；请从
// 会话的事件列表中读取它们。
var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
await foreach (var sessionEvent in seededEvents.Paginate())
{
if (sessionEvent.TryPickUserMessage(out var userMessage))
{
foreach (var contentBlock in userMessage.Content)
{
if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
{
Console.WriteLine($"Seeded event: {textBlock.Text}");
}
}
}
}
seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(agent.ID),
},
EnvironmentID: environment.ID,
InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: "List the files in the working directory.",
},
}},
},
}},
})
if err != nil {
panic(err)
}
// initial_events 不会在创建响应中回显，因此需列出
// 会话的事件以读回预置的 user.message。
seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
if err != nil {
panic(err)
}
for _, event := range seededEvents.Data {
if event.Type != "user.message" {
continue
}
for _, contentBlock := range event.AsUserMessage().Content {
if contentBlock.Type == "text" {
fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
}
}
}
var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
.agent(agent.id())
.environmentId(environment.id())
.addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
.addTextContent("List the files in the working directory.")
.build())
.build());
// initial_events 不会在创建响应中回显；列出
// 会话的事件以读回预置的 user.message。
for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
if (event.isUserMessage()) {
for (var contentBlock : event.asUserMessage().content()) {
if (contentBlock.isText()) {
IO.println("Seeded event: " + contentBlock.asText().text());
}
}
}
}
$seededSession = $client->beta->sessions->create(
agent: $agent->id,
environmentID: $environment->id,
initialEvents: [
[
'type' => 'user.message',
'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
],
],
);
// initial_events 不会在创建响应中回显；需从会话的
// 事件列表中读取它们。
$seededEvents = $client->beta->sessions->events->list($seededSession->id);
foreach ($seededEvents->getItems() as $event) {
if ($event->type === 'user.message') {
echo "Seeded event: {$event->content[0]->text}\n";
}
}
seeded_session = client.beta.sessions.create(
agent: agent.id,
environment_id: environment.id,
initial_events: [
{
type: :"user.message",
content: [{type: :text, text: "List the files in the working directory."}]
}
]
)
# initial_events 不会在创建响应中回显；需要从
# 会话的事件列表中读回它们。
client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
next unless event.type == :"user.message"
event.content.each do |block|
puts "Seeded event: #{block.text}" if block.type == :text
end
end
user.tool_confirmation、user.tool_result 和 user.custom_tool_result）不被接受，因为此时还不存在智能体回合；user.interrupt 也不被接受，因为没有可停止的回合。与计划部署上的 initial_events 不同，会话的 initial_events 不接受 system.message。
initial_events 中的每个事件都会在创建响应返回之前按列表顺序进行验证和持久化，并分配服务器生成的 ID，就像您在创建后立即将其发布到发送事件端点一样。每个事件的内容规则也与该端点相同。空列表等同于省略该字段。验证是全有或全无的：如果任何事件验证失败，整个请求将被拒绝，且不会创建会话。
在以下情况下，创建请求会被拒绝：
| 条件 | 状态码 |
|---|---|
超过一个 user.define_outcome 事件 | 400 |
user.define_outcome 事件没有 rubric | 400 |
整个列表中来自文件的 document 内容块超过 100 个 | 400 |
| 请求体超过 32 MB | 413 |
initial_events 中的 user.define_outcome 事件在与向现有会话发送该事件相同的条件下被接受；请参阅定义结果。
为会话覆盖智能体配置
您可以通过三种形式传递agent：智能体 ID 字符串、固定版本对象（type: "agent"）或覆盖对象。覆盖形式可为单个会话更改智能体配置的部分内容。使用它可以在一个会话中尝试不同的模型或授予额外的工具，而无需对智能体进行版本管理。对于覆盖形式，将 type 设置为 agent_with_overrides，并传入智能体的 id 和可选的 version（省略 version 则使用智能体的最新版本）。然后包含 model、system、tools、mcp_servers 或 skills 中的任意字段，并提供会话应使用的值。
每个可覆盖的字段都遵循相同的三条规则：
- 省略该字段： 会话从其引用的智能体版本继承该值。
-
将字段设置为
null，或对于列表字段设置为空数组： 会话运行时该字段被清除。此规则完全适用于system和skills。有三个例外：model永远不可清除。会话始终需要一个模型，因此model: null会返回 400agent_model_required错误。- 当会话的有效
skills非空时，清除tools会返回 400 错误，因为技能需要read工具。否则，tools: null和tools: []会清除该字段。 - 当会话的有效
tools仍包含引用智能体某个服务器的mcp_toolset时，清除mcp_servers会返回 400 错误。请在同一请求中覆盖tools以移除这些mcp_toolset条目，然后再清除mcp_servers。
-
将字段设置为某个值： 该值会完全替换智能体的值。覆盖永远不会与智能体的配置合并，因此
tools覆盖必须列出会话应拥有的每个工具。有一个例外：- 会话级
model覆盖中的effort不会生效。由于覆盖会完全替换智能体的model对象，智能体自身的effort也不会被保留：使用model覆盖创建的会话将以模型的默认推理强度运行。要使用特定的推理强度，请在智能体上设置effort，并且不要为该会话覆盖model。
- 会话级
agent 对象反映的是应用覆盖后会话运行所使用的配置。其 id 和 version 仍标识覆盖所应用到的智能体和版本。这使您可以将会话追溯到其基础智能体。
以下示例启动一个覆盖模型并清除系统提示的会话：
override_session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": {
"type": "agent_with_overrides",
"id": "$AGENT_ID",
"model": {"id": "claude-sonnet-5"},
"system": null
},
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
jq '.agent | {id, version, model, system}' <<< "$override_session"
OVERRIDE_SESSION_ID=$(jq -r '.id' <<< "$override_session")
# 响应中的 `agent` 是解析后的快照：每个覆盖项仅针对此会话替换
# 对应字段，智能体资源保留其 id 和版本。
ant beta:sessions create \
--transform 'agent.{id,version,model,system}' \
--format json <<YAML
agent:
type: agent_with_overrides
id: $AGENT_ID
model:
id: claude-sonnet-5
system: null
environment_id: $ENVIRONMENT_ID
YAML
override_session = client.beta.sessions.create(
agent={
"type": "agent_with_overrides",
"id": agent.id,
"model": {"id": "claude-sonnet-5"},
"system": None, # clear the agent's system prompt for this session
},
environment_id=environment.id,
)
# 响应中的 agent 是应用了覆盖后的已解析快照。
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")
const overrideSession = await client.beta.sessions.create({
agent: {
type: "agent_with_overrides",
id: agent.id,
model: { id: "claude-sonnet-5" },
system: null // clear the agent's system prompt for this session
},
environment_id: environment.id
});
// 响应中的 agent 是应用了覆盖项后解析出的快照。
console.log(`Model: ${overrideSession.agent.model.id}`);
console.log(`System: ${overrideSession.agent.system}`);
var overrideSession = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentWithOverridesParams
{
Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
ID = agent.ID,
Model = new BetaManagedAgentsModelConfigParams
{
ID = BetaManagedAgentsModel.ClaudeSonnet5,
},
System = null, // clear the agent's system prompt for this session
},
EnvironmentID = environment.ID,
});
// 响应中的 agent 是应用了覆盖项后解析出的快照。
Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
ID: agent.ID,
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeSonnet5,
},
// 清除此会话的智能体系统提示。
System: param.Null[string](),
},
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
// 响应中的 agent 是应用了覆盖项后解析出的快照。
fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
fmt.Printf("System: %q\n", overrideSession.Agent.System)
var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
.agent(BetaManagedAgentsAgentWithOverridesParams.builder()
.type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
.id(agent.id())
.model(BetaManagedAgentsModelConfigParams.builder()
.id(BetaManagedAgentsModel.CLAUDE_SONNET_5)
.build())
.system((String) null) // clear the agent's system prompt for this session
.build())
.environmentId(environment.id())
.build());
// 响应中的 agent 是应用了覆盖项后解析出的快照。
IO.println("Model: " + overrideSession.agent().model().id());
IO.println("System: " + overrideSession.agent().system().orElse("null"));
$overrides = BetaManagedAgentsAgentWithOverridesParams::with(
id: $agent->id,
type: 'agent_with_overrides',
model: ['id' => 'claude-sonnet-5'],
);
// 清除此会话的系统提示。这里数组访问方式至关重要：
// create() 会从原始数组中剥离 null，而 ::with() 将 null 参数视为省略。
$overrides['system'] = null;
$overrideSession = $client->beta->sessions->create(
agent: $overrides,
environmentID: $environment->id,
);
// 响应中的 agent 是应用了覆盖后的已解析快照。
echo "Model: {$overrideSession->agent->model->id}\n";
echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
# 系统提示覆盖项是 `system_`（带尾部下划线），因为普通的
# `system` 是 Ruby 的 Kernel#system。将其设为 nil 会清除该提示。
override_session = client.beta.sessions.create(
agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
type: :agent_with_overrides,
id: agent.id,
model: {id: "claude-sonnet-5"},
system_: nil
),
environment_id: environment.id
)
# 响应中的智能体是应用了覆盖项后解析出的快照。
puts "Model: #{override_session.agent.model.id}"
puts "System: #{override_session.agent.system_.inspect}"
为会话固定推理地理位置
由于model 覆盖会完全替换智能体的 model 对象，它也会为会话设置或清除模型的 inference_geo 固定设置：包含 inference_geo 的覆盖会固定为会话的模型请求提供服务的地理位置，而省略它的覆盖会清除智能体的固定设置，使会话遵循工作区的 default_inference_geo。覆盖的值会在创建会话时根据工作区的 allowed_inference_geos 进行验证。
以下示例从一个模型没有地理位置固定的智能体启动会话，通过在 model 覆盖中包含 inference_geo 将会话的模型请求固定到美国推理，并打印响应的 agent.model 中回显的值：
# 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": {
"type": "agent_with_overrides",
"id": "$AGENT_ID",
"model": {"id": "claude-opus-5", "inference_geo": "us"}
},
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"
# 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
session=$(ant beta:sessions create <<YAML
agent:
type: agent_with_overrides
id: $AGENT_ID
model:
id: claude-opus-5
inference_geo: us
environment_id: $ENVIRONMENT_ID
YAML
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"
session = client.beta.sessions.create(
agent={
"type": "agent_with_overrides",
"id": agent.id,
# 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
"model": {"id": "claude-opus-5", "inference_geo": "us"},
},
environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")
const session = await client.beta.sessions.create({
agent: {
type: "agent_with_overrides",
id: agent.id,
// 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
model: { id: "claude-opus-5", inference_geo: "us" }
},
environment_id: environment.id
});
console.log(`Inference geo: ${session.agent.model.inference_geo}`);
var session = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentWithOverridesParams
{
Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
ID = agent.ID,
// 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
Model = new BetaManagedAgentsModelConfigParams
{
ID = BetaManagedAgentsModel.ClaudeOpus5,
InferenceGeo = "us",
},
},
EnvironmentID = environment.ID,
});
Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
ID: agent.ID,
// 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5,
InferenceGeo: anthropic.String("us"),
},
},
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(BetaManagedAgentsAgentWithOverridesParams.builder()
.type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
.id(agent.id())
// 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
.model(BetaManagedAgentsModelConfigParams.builder()
.id(BetaManagedAgentsModel.CLAUDE_OPUS_5)
.inferenceGeo("us")
.build())
.build())
.environmentId(environment.id())
.build());
IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
$session = $client->beta->sessions->create(
agent: BetaManagedAgentsAgentWithOverridesParams::with(
id: $agent->id,
type: 'agent_with_overrides',
// 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
model: BetaManagedAgentsModelConfigParams::with(
id: 'claude-opus-5',
inferenceGeo: 'us',
),
),
environmentID: $environment->id,
);
echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
session = client.beta.sessions.create(
agent: {
type: :agent_with_overrides,
id: agent.id,
# 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
model: {id: "claude-opus-5", inference_geo: "us"}
},
environment_id: environment.id
)
puts "Inference geo: #{session.agent.model.inference_geo}"
智能体定义了模型在会话中的行为方式，包括模型、系统提示、工具和 MCP 服务器。详情请参阅定义您的智能体。
设置会话预算
要限制会话的支出上限，请在创建会话时传入可选的budget 对象。预算是会话标价成本的硬性上限：平台按公开标价对会话消耗的所有内容进行计价，一旦累计总额达到 max_list_cost，会话就会停止发出新的模型请求。将 type 设置为 limit，并为 max_list_cost 提供 amount 和 currency。amount 是以字符串形式表示的美分整数，例如 "2500" 表示 $25.00；API 采用字符串而非数字，以确保不会应用任何浮点舍入。USD 是目前唯一支持的货币。当会话达到上限时，它会暂停并进入空闲状态，停止原因为 budget_reached。该上限在模型请求之间强制执行，因此超过上限的那个请求会先完成，会话的最终标价成本可能会略微超过上限。预算只能在创建时附加：您可以稍后更改或移除它，但无法为创建时没有预算的会话添加预算。
以下示例创建一个预算为 $25.00 的会话；响应会在会话资源上回显 budget：
cURL
curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"budget": {
"type": "limit",
"max_list_cost": {"amount": "2500", "currency": "USD"}
}
}
EOF
通过密钥库进行 MCP 身份验证
如果您的智能体使用需要身份验证的 MCP 工具，请在创建会话时传入vault_ids，以引用包含已存储 OAuth 凭据的密钥库。OMA 会代表您管理令牌刷新。请参阅使用密钥库进行身份验证，了解如何创建密钥库和注册凭据。
vault_session=$(curl -fsSL http://localhost:38080/v1/sessions \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"vault_ids": ["$VAULT_ID"]
}
EOF
)
VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")
ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
- $VAULT_ID
YAML
vault_session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
)
const vaultSession = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id,
vault_ids: [vault.id]
});
var vaultSession = await client.Beta.Sessions.Create(new()
{
Agent = agent.ID,
EnvironmentID = environment.ID,
VaultIds = [vault.ID],
});
vaultSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(agent.ID),
},
EnvironmentID: environment.ID,
VaultIDs: []string{vault.ID},
})
if err != nil {
panic(err)
}
var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
.agent(agent.id())
.environmentId(environment.id())
.addVaultId(vault.id())
.build());
$vaultSession = $client->beta->sessions->create(
agent: $agent->id,
environmentID: $environment->id,
vaultIDs: [$vault->id],
);
vault_session = client.beta.sessions.create(
agent: agent.id,
environment_id: environment.id,
vault_ids: [vault.id]
)
启动会话
在不使用initial_events 的情况下创建会话只会注册该会话，但不会启动任何工作；环境的沙箱会在会话创建后立即开始配置，因此第一次工具调用无需等待它。要委派任务，请使用用户事件向会话发送事件。如需在创建请求中提供第一个事件，请参阅使用初始事件为会话提供种子。会话充当跟踪进度的状态机，而事件驱动实际的执行。
curl -fsSL "http://localhost:38080/v1/sessions/$SESSION_ID/events" \
-H "x-api-key: $OMA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<'EOF'
{
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "List the files in the working directory."}]
}
]
}
EOF
ant beta:sessions:events send \
--session-id "$SESSION_ID" <<'YAML'
events:
- type: user.message
content:
- type: text
text: List the files in the working directory.
YAML
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
],
},
],
)
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.message",
content: [{ type: "text", text: "List the files in the working directory." }]
}
]
});
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserMessageEventParams
{
Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
Content =
[
new BetaManagedAgentsTextBlock
{
Type = BetaManagedAgentsTextBlockType.Text,
Text = "List the files in the working directory.",
},
],
},
],
});
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: "List the files in the working directory.",
},
}},
},
}},
}); err != nil {
panic(err)
}
client.beta().sessions().events().send(
session.id(),
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserMessageEventParams.builder()
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
.addTextContent("List the files in the working directory.")
.build())
.build());
$client->beta->sessions->events->send(
$session->id,
events: [
[
'type' => 'user.message',
'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
],
],
);
client.beta.sessions.events.send_(
session.id,
events: [
{
type: :"user.message",
content: [{type: :text, text: "List the files in the working directory."}]
}
]
)
后续步骤
会话操作
检索、列出、更新、归档和删除 Open Managed Agents会话。
会话事件流
发送事件、流式传输响应，以及在执行过程中中断或重定向您的会话。
计划部署
使用 OMA API 创建和管理部署：按定期 cron 计划运行智能体并检查其运行历史记录。