将工作委托给智能体

会话事件流

发送事件、流式传输响应，以及在会话执行过程中中断或重定向会话。

与 Claude Managed Agents 的通信是基于事件的。您向代理发送用户事件，并接收代理和会话事件以跟踪状态。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。

事件类型

事件在两个方向上流动。

用户事件是您发送给代理以启动会话并在其进行过程中引导它的事件。
会话事件、跨度事件和代理事件被发送给您，以便观察您的会话状态和代理进度。

事件类型字符串遵循 {domain}.{action} 命名约定。

每个事件都包括一个 processed_at 时间戳，指示事件在服务器端何时被记录。如果 processed_at 为 null，则意味着事件已由工具排队，将在前面的事件完成处理后处理。

有关每个事件类型的完整架构，请参阅会话事件 API 参考。

集成事件

其他场景

处理自定义工具调用

当代理调用自定义工具时：

会话发出包含工具名称和输入的 agent.custom_tool_use 事件。
会话暂停，发出包含 stop_reason: requires_action 的 session.status_idle 事件。阻塞事件 ID 在 stop_reason.requires_action.event_ids 数组中。
在您的系统中执行工具，并为每个工具发送 user.custom_tool_result 事件，在 custom_tool_use_id 参数中传递事件 ID 以及结果内容。
一旦所有阻塞事件都被解决，会话就会转回 running。

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Look up the custom tool use event and execute it
        result=$(call_tool "$event_id")
        # Send the result back
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

工具确认

当权限策略要求在工具执行前进行确认时：

会话发出 agent.tool_use 或 agent.mcp_tool_use 事件。
会话暂停，并发出包含 stop_reason: requires_action 的 session.status_idle 事件。阻止事件 ID 位于 stop_reason.requires_action.event_ids 数组中。
为每个事件发送 user.tool_confirmation 事件，在 tool_use_id 参数中传递事件 ID。将 result 设置为 "allow" 或 "deny"。使用 deny_message 来解释拒绝原因。
一旦所有阻止事件都被解决，会话将转换回 running。

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Approve the pending tool call
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

跟踪使用情况

会话对象包含一个 usage 字段，其中包含累积的令牌统计信息。在会话进入空闲状态后获取会话以读取最新的总数，并使用它们来跟踪成本、强制执行预算或监控消耗。

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens 报告未缓存的输入令牌，output_tokens 报告会话中所有模型调用的总输出令牌。cache_creation_input_tokens 和 cache_read_input_tokens 字段反映提示缓存活动。缓存条目使用 5 分钟的 TTL，因此在该时间窗口内的连续轮次受益于缓存读取，这降低了每个令牌的成本。

Was this page helpful?

将工作委托给智能体

会话事件流

发送事件、流式传输响应，以及在会话执行过程中中断或重定向会话。

与 Claude Managed Agents 的通信是基于事件的。您向代理发送用户事件，并接收代理和会话事件以跟踪状态。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。

事件类型

事件在两个方向上流动。

用户事件是您发送给代理以启动会话并在其进行过程中引导它的事件。
会话事件、跨度事件和代理事件被发送给您，以便观察您的会话状态和代理进度。

事件类型字符串遵循 {domain}.{action} 命名约定。

有关每个事件类型的完整架构，请参阅会话事件 API 参考。

集成事件

其他场景

处理自定义工具调用

当代理调用自定义工具时：

会话发出包含工具名称和输入的 agent.custom_tool_use 事件。
会话暂停，发出包含 stop_reason: requires_action 的 session.status_idle 事件。阻塞事件 ID 在 stop_reason.requires_action.event_ids 数组中。
在您的系统中执行工具，并为每个工具发送 user.custom_tool_result 事件，在 custom_tool_use_id 参数中传递事件 ID 以及结果内容。
一旦所有阻塞事件都被解决，会话就会转回 running。

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Look up the custom tool use event and execute it
        result=$(call_tool "$event_id")
        # Send the result back
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

工具确认

当权限策略要求在工具执行前进行确认时：

会话发出 agent.tool_use 或 agent.mcp_tool_use 事件。
会话暂停，并发出包含 stop_reason: requires_action 的 session.status_idle 事件。阻止事件 ID 位于 stop_reason.requires_action.event_ids 数组中。
为每个事件发送 user.tool_confirmation 事件，在 tool_use_id 参数中传递事件 ID。将 result 设置为 "allow" 或 "deny"。使用 deny_message 来解释拒绝原因。
一旦所有阻止事件都被解决，会话将转换回 running。

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Approve the pending tool call
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

跟踪使用情况

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

Was this page helpful?