互動式 Shell （終端機）

InvokeAgentRuntimeCommandShell 操作會在透過 WebSocket 執行中的 AgentCore 執行期工作階段內開啟持久的互動式終端機工作階段。與單鏡頭命令執行不同， shell 工作階段會維持狀態 — 環境變數、工作目錄和命令歷史記錄會跨輸入傳遞。這可讓您在應用程式中進行偵錯、環境檢查和建置終端體驗。

若要呼叫 InvokeAgentRuntimeCommandShell，您需要 bedrock-agentcore:InvokeAgentRuntimeCommandShell 許可。

運作方式

InvokeAgentRuntimeCommandShell 會建立 WebSocket 連線至在代理程式工作階段中執行的互動式 shell 程序。連線使用二進位影格以雙向串流終端機輸入和輸出。

相同的代理程式、相同的工作階段

InvokeAgentRuntimeCommandShell 在與 InvokeAgentRuntime和 相同的代理程式執行時間上運作InvokeAgentRuntimeCommand。您不會建立個別的資源。您使用 部署的代理CreateAgentRuntime程式接受任何作用中工作階段的 shell 連線。

注意

您可以傳遞 session_id以鎖定特定執行階段工作階段。如果省略，則會為每個連線建立新的工作階段。若要使用重新連線，您必須同時存放和重複使用 session_id和 shellId。

連線支援：

功能	說明
持續狀態	環境變數、工作目錄和命令歷史記錄會跨相同工作階段中的輸入傳遞。
重新連線	提供相同的 session_id和 shellId 在中斷連線後重新連線至相同的 shell。服務會重播最多 256 KB 的緩衝輸出。
多個並行 shell	每個執行時間最多 10 個作用中 Shell 工作階段 （終端機）。處於容量時，新連線會遭到拒絕。

先決條件

• bedrock-agentcore:InvokeAgentRuntimeCommandShell IAM 許可

• 有效的 AgentCore 執行期端點 ARN，執行期處於 READY 狀態

注意

2026 年 6 月 5 日之後建立的代理程式會自動支援互動式 shell （終端）。如果您在此日期之前部署代理程式，則必須重新部署它以更新代理程式執行時間。

使用 AgentCore CLI

如需安裝和設定說明，請參閱使用 CLI 開始使用 AgentCore 執行期。

CLI 透過 提供內建的終端機體驗agentcore exec。

agentcore exec --it

若要連接至特定執行時間：

agentcore exec --it --runtime <runtime-arn> --region us-west-2

按下 Ctrl+] 以從殼層分離，而不關閉殼層。CLI 會列印重新連線命令：

agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

對於單鏡頭命令，省略 --it：

agentcore exec "ls -la /tmp"

對於機器可讀取的輸出，請使用 JSON 模式：

agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

如需其他 CLI 範例，請參閱 GitHub 上的 AgentCore 範例。

使用 AgentCore SDK

安裝 Python SDK：

pip install bedrock-agentcore

範例

SigV4 (default)

1. 下列範例示範如何使用預設 AWS 登入資料開啟 shell 工作階段。

   import asyncio
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ShellChannel
   
   async def main():
       runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
       client = AgentCoreRuntimeClient(region="us-west-2")
   
       async with client.open_shell(runtime_arn) as shell:
           print(f"Connected. Shell ID: {shell.shell_id}")
   
           # Send a command
           await shell.send("echo Hello from AgentCore Shell\n")
   
           # Read output frames
           async for frame in shell:
               if frame.channel == ShellChannel.STDOUT:
                   print(frame.text, end="")
                   if "Hello from AgentCore Shell" in frame.text:
                       break
   
   asyncio.run(main())

Pre-signed URL

1. 下列範例示範如何使用預先簽章的 URL 開啟 shell 工作階段。

   import asyncio
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient, PresignedAuth, ShellChannel
   
   async def main():
       runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
       client = AgentCoreRuntimeClient(region="us-west-2")
   
       async with client.open_shell(runtime_arn, auth=PresignedAuth(expires=120)) as shell:
           await shell.send("whoami\n")
   
           async for frame in shell:
               if frame.channel == ShellChannel.STDOUT:
                   print(frame.text, end="")
                   break
   
   asyncio.run(main())

OAuth

1. 下列範例示範如何使用 OAuth 承載符記開啟 shell 工作階段。

   import asyncio
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient, OAuthAuth, ShellChannel
   
   async def main():
       runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
       bearer_token = "your_oauth_token_here"
       client = AgentCoreRuntimeClient(region="us-west-2")
   
       async with client.open_shell(runtime_arn, auth=OAuthAuth(bearer_token=bearer_token)) as shell:
           await shell.send("echo oauth-connected\n")
   
           async for frame in shell:
               if frame.channel == ShellChannel.STDOUT:
                   print(frame.text, end="")
                   if "oauth-connected" in frame.text:
                       break
   
   asyncio.run(main())

重新連線

常見的模式是在中斷連線後shellId使用 重新連線至 Shell，保留所有工作階段狀態。

import asyncio

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

async def main():
    client = AgentCoreRuntimeClient(region="us-west-2")
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    session_id = "my-session-0000000000000000000000"
    shell_id = "my-shell"

    shell = await client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ).__aenter__()
    print(f"connected (reconnected={shell.reconnected})")
    await shell.send("export GREETING='hello'\n")
    await asyncio.sleep(1)

    async with client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ) as shell2:
        print(f"reconnected (reconnected={shell2.reconnected})")
        assert shell2.reconnected


if __name__ == "__main__":
    asyncio.run(main())

自動重新連線

開發套件也可以在 WebSocket 連線中斷時自動重新連線。使用 ReconnectConfig 啟用此功能：

import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {reconnected}")

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    shell_id = "my-persistent-shell"
    config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect)

    client = AgentCoreRuntimeClient(region="us-west-2")
    async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell:
        # If the connection drops, the SDK retries automatically
        await shell.send("long-running-command\n")
        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")

asyncio.run(main())

如需其他 SDK 範例，請參閱 GitHub 上的 AgentCore 範例。

常用案例

互動式偵錯

開啟 shell 以檢查代理程式的執行期環境：檢查已安裝的套件、讀取日誌檔案、檢查檔案系統或測試命令，然後再將其新增至您的代理程式程式碼。

python --version && pip list | head -20

環境檢查

驗證環境變數、網路連線、可用工具和檔案系統狀態。診斷代理程式失敗或驗證部署組態時很有用。

env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/

編碼代理程式終端機存取

AI 編碼代理器使用互動式 shell （終端） 作為其執行環境。當編碼代理程式需要執行程式碼、安裝套件或執行測試時，它會開啟 AgentCore 執行期的 shell 工作階段，並直接執行命令，就像開發人員使用終端機一樣。例如，Claude Code、Amazon Kiro 和 OpenAI Codex 每個都連接到 shell 工作階段，他們可以反覆編寫程式碼、執行程式碼、觀察輸出，以及修正迴圈中的錯誤。持久性狀態表示代理程式可以執行一系列命令，而不會遺失步驟之間的內容。

# A coding agent opens a shell and iterates on code
async with client.open_shell(runtime_arn, shell_id="agent-workspace") as shell:
    await shell.send("cd /workspace && git clone https://github.com/user/repo.git\n")
    await shell.send("cd repo && pip install -r requirements.txt\n")
    await shell.send("python -m pytest tests/ -v\n")
    # Agent reads test output, fixes failures, re-runs — all in the same shell

長時間執行的程序

啟動讓單一 HTTP 請求過期的程序。使用重新連線來檢查進度，或隨著時間提供額外的輸入。

nohup python train.py > /tmp/train.log 2>&1 &

關鍵設計選擇

持久性互動式工作階段

每個連線都會對應至長期 Shell 程序。您可以傳送多個命令而不重新建立連線，而先前命令 （匯出的變數、cd變更） 累積的狀態可供稍後的命令使用。

透過 WebSocket 的二進位框架

終端機 I/O 會串流為二進位 WebSocket 影格。這支援原始終端機控制序列、顏色、游標移動和全螢幕應用程式，而不會編碼額外負荷。

重新連線輸出重播

當您使用相同的 重新連線時shellId，服務會重播最多 256 KB 的最新輸出。這可讓您從網路中斷中復原，而不會遺失內容。shell 程序會在中斷連線期間繼續執行。

工作階段限制

當執行時間上已開啟 10 個 shell 工作階段 （終端機） 時，新的連線會遭到拒絕並顯示錯誤。您必須先關閉現有的工作階段，才能開啟新的工作階段。

安全考量

提示

如需所有執行期安全建議的合併檢視，請參閱 AgentCore 執行期的安全最佳實務。

重要

在 AWS 共同責任模型下，您要對您在 AgentCore 執行期工作階段中執行的命令負責。 在 microVM 層級 AWS 提供安全的基礎設施和隔離。您必須負責執行的命令、處理的資料，以及您設定的存取控制。

shell 工作階段 （終端） 的安全界限是 microVM。每個 AgentCore 執行期工作階段都會在具有自己的核心、記憶體和檔案系統的隔離 microVM 中執行。Shell 工作階段無法存取其他客戶的工作負載或逸出 VM 界限。不過，在您的 VM 中， shell 命令可以完整存取容器檔案系統，以及您設定的任何登入資料或秘密。

使用 CloudWatch Logs 稽核

AgentCore 執行期會將請求 ID 和連線中繼資料傳送至代理程式的 Amazon CloudWatch Logs 日誌群組。您可以使用這些日誌來監控 shell 連線活動，並維護稽核線索。終端機 I/O 內容 (stdin/stdout) 會串流到您的用戶端，且服務不會記錄。

使用 CloudTrail 稽核

AWS CloudTrail 會在您的帳戶中記錄 InvokeAgentRuntimeCommandShell API 呼叫。每個記錄都包含中繼資料，例如發起人身分、時間戳記、來源 IP 地址和回應狀態。CloudTrail 不會記錄請求或回應承載。使用 CloudTrail 稽核誰開啟 shell 工作階段，以及何時開啟，然後使用連線詳細資訊的請求 ID 與 CloudWatch Logs 建立關聯。

對於敏感工作負載，請考慮實作其他控制項，例如：

• 使用 IAM 政策來限制哪些主體可以呼叫 InvokeAgentRuntimeCommandShell

• 設定 VPC 端點以將流量保留在您的網路中

• 設定 CloudWatch Logs 指標篩選條件和警示，以偵測非預期的連線模式

• 定期檢閱 CloudTrail 日誌是否有未經授權的存取嘗試

錯誤處理

建立 shell 工作階段連線時，您可能會在 WebSocket 升級期間遇到下列錯誤：

ValidationException

當請求參數無效時發生。如果工作階段 ID 少於 33 個字元、未在目標區域中啟用此功能，或代理程式未處於就緒狀態，就會發生這種情況。

AccessDeniedException

當您沒有必要的許可時發生。確保您的 IAM 政策包含 bedrock-agentcore:InvokeAgentRuntimeCommandShell許可。

ResourceNotFoundException

當找不到指定的代理程式執行時間時發生。驗證執行時間 ARN 是否正確。

RuntimeClientError (424)

在數種案例中發生：(1) 已達到並行 shell 工作階段 （終端） 上限 (10 開啟） — 關閉現有工作階段並重試。(2) Shell ID 格式無效 — 必須是 1-128 個英數字元、底線或連字號。(3) 無法連線執行時間 — 退避後重試。剖析回應內文 JSON error 欄位以區分原因。

ThrottlingException

當您超過 API 速率限制時發生。實作指數退避和重試邏輯。

ConflictException

另一個連線shellId同時宣告相同的 。1 秒後重試。這是狹窄的競爭條件 （非持久性狀態），並在重試時立即解析。

連線後，以下關閉代碼會指出連線終止的原因：

Code	意義	用戶端動作
1000	正常關閉 — 殼層以乾淨或正常的方式離開	顯示「已中斷連線」。正常終止。
1001	離開 — 伺服器部署或關閉	使用存放的 自動重新連線shellId。
1003	不支援的資料 — 在連續 5 個文字影格後傳送 （僅限二進位通訊協定）	請勿自動重新連線。切換到二進位影格。
1006	異常關閉 — 未收到關閉影格時在本機合成 （網路死亡、TCP RST)	使用存放的 自動重新連線shellId。
1008	政策違規 – 連線 TTL 已過期 (1 小時）、超過影格速率限制 (250 個影格/秒） 或寫入緩衝區溢位	自動重新連線 TTL 過期 （重新連線時重新整理 TTL)。對於速率限制：關閉，然後重新連線。
1009	訊息太大 — 影格承載超過 64 KB	減少影格大小 （區塊至 <64 KB)，然後重新連線。工作階段仍然有效。
1011	伺服器錯誤 — 非預期的內部故障	使用退避重試。
4000	已取代 — 使用相同 連線的另一個用戶端 shellId	請勿自動重新連線。顯示「從另一個用戶端連接工作階段」。

最佳實務

使用 時，請遵循下列最佳實務InvokeAgentRuntimeCommandShell：

• 為每個邏輯工作階段使用唯一的 shellId（例如 UUID) 來啟用重新連線。將 存放在shellId用戶端。

• 在 SDK ReconnectConfig中使用 可自動處理暫時性網路中斷，無需手動重新連線邏輯。

• 立即讀取輸出影格。如果用戶端落後，伺服器的寫入緩衝區會填滿，且連線會以代碼 關閉1008。

• 對於大型輸入 （例如貼上檔案），請將內容分割為每個影格 64 KB 以下的區塊，以避免關閉程式碼 1009。

• 設定適當的連線逾時。最長連線持續時間為 1 小時 — 以相同的 重新連線shellId以繼續超過此時間。

• 完成後明確關閉工作階段。分離的工作階段會計入 10 個工作階段的限制。

配額和限制

限制	Value	說明
影格承載大小上限	64 KB	超過此限制的影格會導致關閉程式碼 1009。
影格播放速率	每秒 250 個影格	超過此值會觸發關閉程式碼 1008。
連線持續時間上限	1 小時	連線會以代碼 關閉1008。使用相同的 重新連線shellId以繼續。
每個執行時間的並行 shell 工作階段 （終端機）	10	如果已開啟 10 個工作階段，則會拒絕新的連線。關閉現有的工作階段並重試。
重新連線緩衝區	256 KB	重新連線至 shell 時重播的最大輸出。

如需完整的服務限制，請參閱 Amazon Bedrock AgentCore 的配額。