跳至主要內容

Bedrock AgentCore

以 OpenAI 的請求/回應格式呼叫 Bedrock AgentCore。

屬性詳細資訊
描述Amazon Bedrock AgentCore 提供對受託管 agent runtime 的直接存取，可使用 foundation models 執行 agentic workflows。
LiteLLM 上的提供者路由bedrock/agentcore/{AGENT_RUNTIME_ARN}
提供者文件AWS Bedrock AgentCore ↗
資訊

此文件適用於 AgentCore Agents（agent runtimes）。如果您想將 AgentCore MCP servers 與 LiteLLM 一起使用，請參閱 MCP AWS SigV4 Auth 指南以取得設定說明。

快速開始​

模型格式到 LiteLLM​

若要透過 LiteLLM 呼叫 bedrock agent runtime，請使用以下模型格式。

此處的 model=bedrock/agentcore/ 會告訴 LiteLLM 呼叫 bedrock InvokeAgentRuntime API。

Model Format to LiteLLM
bedrock/agentcore/{AGENT_RUNTIME_ARN}

範例：

  • bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime

您可以在 AWS Bedrock 主控台的 AgentCore 下找到 Agent Runtime ARN。

LiteLLM Python SDK​

Basic AgentCore Completion
import litellm

# Make a completion request to your AgentCore runtime
response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user", 
            "content": "Explain machine learning in simple terms"
        }
    ],
)

print(response.choices[0].message.content)
print(f"Usage: {response.usage}")
Streaming AgentCore Responses
import litellm

# Stream responses from your AgentCore runtime
response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user",
            "content": "What are the key principles of software architecture?"
        }
    ],
    stream=True,
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

LiteLLM Proxy​

1. 在 config.yaml 中設定您的模型​

LiteLLM Proxy Configuration
model_list:
  - model_name: agentcore-runtime-1
    litellm_params:
      model: bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-west-2

  - model_name: agentcore-runtime-2
    litellm_params:
      model: bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:987654321098:runtime/production-runtime
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1

2. 啟動 LiteLLM Proxy​

Start LiteLLM Proxy
litellm --config config.yaml

3. 向您的 AgentCore runtimes 發出請求​

Basic AgentCore Request
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "model": "agentcore-runtime-1",
    "messages": [
      {
        "role": "user", 
        "content": "Summarize the main benefits of cloud computing"
      }
    ]
  }'
Streaming AgentCore Request
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "model": "agentcore-runtime-2",
    "messages": [
      {
        "role": "user",
        "content": "Explain the differences between SQL and NoSQL databases"
      }
    ],
    "stream": true
  }'

提供者專屬參數​

AgentCore 支援可傳入的額外參數，用於自訂 runtime 呼叫。

Using AgentCore-specific parameters
from litellm import completion

response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user",
            "content": "Analyze this data and provide insights",
        }
    ],
    qualifier="production",  # PROVIDER-SPECIFIC: Runtime qualifier/version
    runtimeSessionId="session-abc-123",  # PROVIDER-SPECIFIC: Custom session ID
)

可用參數​

參數型別說明
qualifierstring選用的 runtime qualifier/version，用於呼叫 agent runtime 的特定版本
runtimeSessionIdstring選用的自訂 session ID（必須為 33 個字元以上）。如果未提供，LiteLLM 會自動產生一個

LiteLLM A2A Gateway​

將 Bedrock AgentCore runtime 註冊為 LiteLLM Agent Gateway 上的一級 A2A 代理程式。這可讓您享有每個代理程式的 RBAC、存取群組、trace-ID 強制，以及 x-a2a-{agent_name_or_id}-{header} 每位使用者轉傳慣例，與任何其他 A2A 提供者相同的介面。

此路徑與上方的 chat-completions 呼叫不同。請依據您的用戶端選擇其一：

您要透過... 呼叫 AgentCore使用此路徑
/v1/chat/completions 搭配 model: bedrock/agentcore/<ARN>Chat completions（上方已涵蓋）
POST /a2a/{agent_id} 搭配 A2A JSON-RPC 2.0（message/send 或 message/stream）A2A Gateway（本節）

1. 註冊 agent​

  1. 前往 Agents → Add Agent。
  2. 將 Bedrock AgentCore 選為提供者。
  3. 將 AgentCore Runtime ARN 貼為代理程式 URL。
  4. 設定 AWS 憑證（或留白以使用 proxy 的環境憑證鏈；請參閱下方的 Authentication）。

更新或輪替憑證​

litellm_params 中任何含有憑證的欄位（aws_access_key_id、aws_secret_access_key、aws_session_token、api_key 等）皆為唯寫。GET/POST/PUT/PATCH /v1/agents 回應，以及 Admin UI 的代理程式編輯表單，永遠會將這些欄位顯示為已遮蔽的預留位置，而非已儲存的值。

  • 編輯無關欄位（名稱、描述、速率限制）並儲存時，已儲存的憑證不會變更，即使表單對每個未觸及的憑證欄位都會來回傳遞該預留位置。
  • 若要輪替憑證，請提交該欄位的新值；更新會立即套用，且同樣不會回傳回來。
  • 將欄位提交為空字串會清除已儲存的憑證（例如，改回使用 proxy 的環境 AWS 憑證鏈）。

2. 透過 A2A 呼叫​

curl -X POST http://localhost:4000/a2a/my-agentcore-runtime/message/send \
  -H "x-litellm-api-key: Bearer sk-client-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Summarize the latest clinical trial results"}],
        "messageId": "msg-1"
      }
    }
  }'

工作階段隔離​

每個 AgentCore runtime 工作階段都是自己的 microVM：重複使用相同的 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 會保留對話內容，而將兩個呼叫者混入同一個工作階段會導致彼此之間的內容外洩。LiteLLM 依下列順序選取該工作階段 id：

  1. params.message.contextId，位於 A2A 請求中，並以呼叫的 API 金鑰為範圍，因此兩個金鑰永遠不會在同一個 contextId 上衝突。這是每個對話隔離工作階段的建議方式。
  2. 代理程式的 litellm_params 中的 runtimeSessionId（請參閱 Available Parameters），僅在請求未帶有 contextId 時使用。省略 contextId 的每個呼叫者都會共用這一個工作階段。
  3. 當以上皆未設定時，會產生一個新的 id。每個請求都會取得自己的工作階段，因此不會保留多輪對話內容。

若要在多輪之間維持對話，請在該對話的每次 message/send 或 message/stream 呼叫中傳送相同的 contextId，並為每個新對話或最終使用者使用不同的 contextId：

curl -X POST http://localhost:4000/a2a/my-agentcore-runtime/message/send \
  -H "x-litellm-api-key: Bearer sk-client-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Summarize the latest clinical trial results"}],
        "messageId": "msg-1",
        "contextId": "conversation-<a stable id you generate per conversation, e.g. a UUID>"
      }
    }
  }'

AWS 要求 runtime 工作階段 id 為 33-256 個字元。LiteLLM 會在檢查前，先在 contextId 前加上呼叫金鑰的 16 字元雜湊，因此 contextId 本身至少需要 16 個字元；UUID（36 個字元）則很充裕。超出該範圍的 contextId（或已設定的 runtimeSessionId）會在任何請求送達 AWS 之前，以 HTTP 400 和 JSON-RPC -32602 錯誤遭到拒絕，而不是無聲地退回共用工作階段。

驗證​

AgentCore A2A 路徑支援兩種不同的對外驗證模式，會根據 litellm_params 中的內容自動選擇：

模式觸發時機傳送給 AgentCore 的內容
Bearer / JWT已設定 litellm_params.api_key（任何值）Authorization: Bearer <api_key>——完全略過 SigV4
SigV4未設定 litellm_params.api_key使用完整 AWS credential chain（如下）進行每次請求的 SigV4 簽章

SigV4 憑證解析​

當 SigV4 模式啟用時，憑證會依下列優先順序解析：

  1. aws_web_identity_token + aws_role_name + aws_session_name → sts:AssumeRoleWithWebIdentity。跨帳戶 IRSA 路徑。
  2. 僅 aws_role_name → sts:AssumeRole。proxy 的 ambient credentials（instance profile、IRSA、環境變數）為來源身分。若省略，session name 會自動產生。
  3. aws_profile_name → 透過 boto3 profile loader（~/.aws/credentials）解析。
  4. aws_access_key_id + aws_secret_access_key + aws_session_token → 明確的暫時性憑證。
  5. aws_access_key_id + aws_secret_access_key + aws_region_name → 明確的長期憑證。三者都必須設定；若沒有 aws_region_name，此分支會被略過。
  6. 未設定任何憑證 → boto3 預設鏈（環境變數、透過 AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN 的 IRSA、instance metadata）。

litellm_params 上可辨識的 SigV4 欄位：

欄位說明
aws_role_name要透過 STS assume 的 IAM role ARN
aws_session_nameAssumeRole 呼叫的 session name（若省略則自動產生）
aws_external_id傳遞給 sts:AssumeRole 的 ExternalId，用於跨帳戶信任政策
aws_web_identity_token供 AssumeRoleWithWebIdentity 使用的 OIDC token（可明確設定或透過 AWS_WEB_IDENTITY_TOKEN_FILE env 設定）
aws_profile_nameAWS CLI profile name
aws_sts_endpoint自訂 STS endpoint（VPC endpoints、FIPS endpoints）
aws_access_key_id / aws_secret_access_key / aws_session_token明確的憑證
aws_region_nameAWS region。若省略，會從 agent_card_params.url 中的 runtime ARN 偵測。

EKS 上的 IRSA​

對於使用 IAM Roles for Service Accounts 的 Kubernetes 部署，不需要明確設定憑證。boto3 的預設鏈會自動從 pod 環境中取得 AWS_WEB_IDENTITY_TOKEN_FILE 和 AWS_ROLE_ARN。

如果您希望呼叫時再 assume 第二個 role（例如：將 pod 的身分與 agent 呼叫身分分開，以利 CloudTrail 歸因），請將 IRSA 與 aws_role_name 結合使用：

curl -X POST http://localhost:4000/v1/agents \
  -H "Authorization: Bearer sk-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "production-runtime",
    "agent_card_params": {
      "name": "production-runtime",
      "url": "bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/prod"
    },
    "litellm_params": {
      "custom_llm_provider": "bedrock",
      "aws_role_name": "arn:aws:iam::123456789012:role/AgentCoreInvocationRole",
      "aws_session_name": "litellm-prod"
    }
  }'

proxy pod 的 IRSA role 會作為 AssumeRole 呼叫的來源身分；assumed role 的 CloudTrail 項目會反映 agent 呼叫。

每位使用者的標頭透傳​

適用標準 A2A 標頭轉送機制；完整參考請參閱 A2A Agent Authentication Headers。這三種方法都可與 AgentCore 搭配使用：

  • static_headers — 一律傳送至 AgentCore（例如自訂 X-Tenant-Id）
  • extra_headers — 由管理員設定的允許轉送 client headers 清單
  • x-a2a-{agent_name_or_id}-{header} 慣例 — 不需管理設定、由呼叫端驅動的轉送

請注意，litellm_params 所處理的 SigV4 / Bearer auth 與上方的 agent-level 標頭轉送是分開的。auth headers 會由 AWS signer 逐次請求計算；使用者透傳標頭則會在簽章後併入請求。

RBAC 與 trace IDs​

適用所有標準 A2A 控制：

  • 每個代理程式的 RBAC — Agent Permission Management。當呼叫的金鑰/團隊未獲授權使用 AgentCore 代理程式時，會回傳 HTTP 403。
  • 存取群組 — 在 LiteLLM 儀表板中為代理程式加上一或多個存取群組標籤，然後透過 object_permission.agent_access_groups 將該群組授予團隊或金鑰。請參閱 Agent Access Groups。
  • Trace ID 強制。 在 litellm_params 上設定 require_trace_id_on_calls_to_agent: true，以要求每次傳入呼叫都必須有 x-litellm-trace-id。請參閱 A2A Overview: Trace ID enforcement。

延伸閱讀​

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →