工具

工具為宣告式。您可以列出客服人員可以呼叫的內容；AgentCore 會處理調用、登入資料和結果。該繫帶支援五種工具類型，以及內建檔案系統和 shell 工具。

MCP 伺服器：依 URL 連線至任何遠端模型內容通訊協定端點。簡單案例不需要閘道。
AgentCore Gateway：對 APIs 和 MCP 伺服器的受管連線，具有傳入/傳出身分驗證、存取控制和政策強制執行。參考閘道 ARN，在該閘道上設定的每個工具都可供使用。當您需要受管、政策後端的工具表面時，請使用 Gateway。
AgentCore 瀏覽器：受管 Web 瀏覽和自動化。
AgentCore Code Interpreter：用於資料分析和運算的沙盒化 Python/JavaScript/TypeScript 程式碼執行。
內嵌函數：在用戶端執行的工具結構描述，而不是在繫帶 VM 上執行。呼叫工具時，該工具會暫停，並將呼叫傳回給您的程式碼，這會決定要做什麼並傳回結果。這是human-in-the-loop核准和自訂整合的模式。

除非您使用限制它們，否則每個工作階段都file_operations提供預設工具 shell 和 allowedTools。會shell執行 bash 命令； file_operations 支援檢視、建立和編輯檔案。

allowedTools 參數控制代理程式可以使用哪些工具。如果省略，則允許所有工具。

支援的模式：

模式	範例	相符
`*`	`"*"`	所有工具
純名稱	`"shell"`	依名稱內建
內建 glob	`"file_*"`	`file_operations`, `file_read`
`@builtin`	`"@builtin"`	所有內建工具
`@builtin/name`	`"@builtin/shell"`	特定內建
`@server`	`"@git"`	來自 MCP 伺服器的所有工具
`@server/tool`	`"@git/git_status"`	特定 MCP 工具
`@server/glob`	`"@git/read_*"`	伺服器內的 Glob
`@*/tool`	`"@*-mcp/status"`	跨伺服器的 Glob

注意

allowedTools InvokeHarness僅在期間範圍 LLM 工具選擇。它不會影響 InvokeAgentRuntimeCommand，InvokeAgentRuntimeCommand 是一個單獨的 API，具有自己的 IAM 動作 (bedrock-agentcore:InvokeAgentRuntimeCommand)，可直接執行命令，而無需傳遞 LLM。為了防止直接命令執行，請勿在 IAM 政策bedrock-agentcore:InvokeAgentRuntimeCommand中授予。

新增工具

範例

AWS CLI/boto3

tools 在建立、更新或叫用時傳遞：


tools = [
    # MCP server
    {
        "type": "remote_mcp",
        "name": "exa",
        "config": {"remoteMcp": {"url": "https://mcp.exa.ai/mcp"}},
    },
    # MCP server with authentication headers (plain text)
    {
        "type": "remote_mcp",
        "name": "my-private-mcp",
        "config": {"remoteMcp": {
            "url": "https://mcp.example.com/api",
            "headers": {"Authorization": "Bearer <your-token>"}
        }},
    },
    # MCP server with API key stored in AgentCore Identity Token Vault.
    # Use ${arn:...} to reference a credential provider - the ARN is resolved
    # to the actual API key at invocation time.
    {
        "type": "remote_mcp",
        "name": "exa-secure",
        "config": {"remoteMcp": {
            "url": "https://mcp.exa.ai/mcp",
            "headers": {"x-api-key": "${arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-exa-key}"}
        }},
    },
    # For managed credential rotation and OAuth-protected tools, put your MCP server
    # behind AgentCore Gateway and use AgentCore Identity instead of raw headers.
    #
    # AgentCore Gateway with SigV4 auth (default)
    {
        "type": "agentcore_gateway",
        "name": "my-gateway",
        "config": {"agentCoreGateway": {"gatewayArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway"}},
    },
    # AgentCore Gateway with OAuth auth
    {
        "type": "agentcore_gateway",
        "name": "my-oauth-gateway",
        "config": {"agentCoreGateway": {
            "gatewayArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-oauth-gateway",
            "outboundAuth": {"oauth": {
                "credentialProviderName": "my-oauth-provider",
                "scopes": ["read", "write"]
            }}
        }},
    },
    # AgentCore Browser
    {"type": "agentcore_browser", "name": "browser"},
    # AgentCore Code Interpreter
    {"type": "agentcore_code_interpreter", "name": "code_interpreter"},
    # Inline function - executes on the client side, not on the harness VM.
    # When the agent calls this tool, the call is returned to your code for handling.
    {
        "type": "inline_function",
        "name": "approve_purchase",
        "config": {
            "inlineFunction": {
                "description": "Request human approval for a purchase.",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "item": {"type": "string"},
                        "amount": {"type": "number"},
                    },
                    "required": ["item", "amount"],
                },
            }
        },
    },
]

response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    tools=tools,
    messages=[{"role": "user", "content": [{"text": "Find a mechanical keyboard under $200 and request approval."}]}],
)

AgentCore CLI

以互動方式建立新工具時，agentcore add harness精靈可讓您選取工具。若要透過 CLI 新增工具，請在建立繫帶agentcore add tool後使用：

注意

--type 旗標使用底線分隔名稱（例如 agentcore_browser)，其符合中的工具類型識別符harness.json。


# Add a remote MCP server
agentcore add tool --harness my-agent --type remote_mcp \
  --name exa --url https://mcp.exa.ai/mcp

# Add a remote MCP server with an API key from AgentCore Identity Token Vault.
# Use ${arn:...} syntax in header values to reference a credential provider.
agentcore add tool --harness my-agent --type remote_mcp \
  --name exa-secure --url https://mcp.exa.ai/mcp \
  --header 'x-api-key=${arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-exa-key}'

# Add Browser
agentcore add tool --harness my-agent --type agentcore_browser --name browser

# Add Code Interpreter
agentcore add tool --harness my-agent --type agentcore_code_interpreter --name code-interpreter

# Add Gateway by ARN
agentcore add tool --harness my-agent --type agentcore_gateway \
  --name my-gateway --gateway-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway

# Add Gateway by project-local name
agentcore add tool --harness my-agent --type agentcore_gateway \
  --name my-gateway --gateway my-gateway

# Add an inline function tool (executes client-side, not on the harness VM)
agentcore add tool --harness my-agent --type inline_function \
  --name approve_purchase \
  --description "Request human approval for a purchase" \
  --input-schema '{"type": "object", "properties": {"item": {"type": "string"}, "amount": {"type": "number"}}, "required": ["item", "amount"]}'

部署以套用。

在單一調用上覆寫工具：


agentcore invoke --harness research-agent --tools agentcore-browser "Find the latest news on AI agents"

Interactive

agentcore 在專案目錄中執行，選取新增，選擇繫結，然後進入進階設定 。啟用具有空格的工具 ，然後按 Enter 。

選取您工具的工具：AgentCore 瀏覽器 、AgentCore Code Interpreter 、AgentCore Gateway 或遠端 MCP Server 。使用空格切換每個項目，然後按 Enter 鍵。
對於遠端 MCP 伺服器 ，精靈會提示伺服器名稱、URL 和選用的請求標頭。
對於 AgentCore Gateway ，輸入閘道 ARN，然後選擇其傳出身分驗證： AWS IAM （預設）、無或 OAuth。
檢閱組態摘要並確認。

然後執行 agentcore deploy 以套用。

Web 搜尋

若要為您的代理程式提供 Web 搜尋，請將 Web 搜尋工具連接器放在 AgentCore Gateway 後方，並將該閘道做為agentcore_gateway工具連接到您的集合。閘道會將 Web 搜尋公開為標準 MCP WebSearch工具。您的代理程式會像任何其他閘道工具一樣探索和呼叫它。AgentCore Gateway 完全提供所有查詢 AWS。如需隱私權模型和專用 Web 索引的詳細資訊，請參閱 Web 搜尋工具連接器頁面。

區域可用性

Web 搜尋工具在美國東部（維吉尼亞北部） us-east-1區域提供。在中建立閘道和繫帶us-east-1。

完成下列步驟，以設定您繫帶的 Web 搜尋。

建立閘道和連接器目標。依照設定 Web 搜尋工具中的步驟來建立閘道 (MCP 通訊協定、AWS_IAM傳入身分驗證），並使用新增目標connectorId: "web-search"。該目標需要在連接器bedrock-agentcore:InvokeWebSearch上使用的閘道服務角色。如需詳細資訊，請參閱設定閘道服務角色。閘道 ARN 到達後，請加以記下READY。
授予繫帶執行角色存取權。閘道 ARN bedrock-agentcore:InvokeGateway上需要的繫帶執行角色（與上一個步驟中的閘道服務角色不同）。如需所需許可的詳細資訊，請參閱安全主題中的 AgentCore Gateway 選用許可政策。如果您的繫帶使用受管記憶體（預設值），執行角色也需要 AgentCore 記憶體許可。代理程式會在每次調用時讀取和寫入工作階段記憶體。
將閘道連接至繫帶。將其新增為具有預設AWS_IAM傳出身分驗證agentcore_gateway的工具。下列範例示範如何在建立時間連接閘道。

範例

內嵌函數呼叫

內嵌函數可讓您定義在程式碼中執行的工具，而不是在繫帶上執行的工具。這適用於human-in-the-loop核准、呼叫內部 APIs，或您想要控制用戶端的任何邏輯。

範例

AWS CLI/boto3

在調用時間傳遞內嵌函數工具：


# 1. Invoke with an inline function tool
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    tools=[{
        "type": "inline_function",
        "name": "get_weather",
        "config": {"inlineFunction": {
            "description": "Get the current weather for a city.",
            "inputSchema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"]
            }
        }}
    }],
    messages=[{"role": "user", "content": [{"text": "What's the weather in Seattle?"}]}],
)

# 2. The agent calls the tool - capture the toolUseId and input from the stream
tool_use_id = None
tool_name = None
tool_input = None
for event in response["stream"]:
    if "contentBlockStart" in event:
        start = event["contentBlockStart"].get("start", {})
        if "toolUse" in start and start["toolUse"].get("name") == "get_weather":
            tool_use_id = start["toolUse"]["toolUseId"]
            tool_name = start["toolUse"]["name"]
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"].get("delta", {})
        if "toolUse" in delta:
            tool_input = (tool_input or "") + delta["toolUse"].get("input", "")

# 3. Execute the tool yourself and send the result back
# Include the assistant's toolUse message followed by your toolResult
client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    messages=[
        {
            "role": "assistant",
            "content": [{"toolUse": {"toolUseId": tool_use_id, "name": tool_name, "input": json.loads(tool_input)}}],
        },
        {
            "role": "user",
            "content": [{
                "toolResult": {
                    "toolUseId": tool_use_id,
                    "content": [{"text": "72°F, partly cloudy"}],
                    "status": "success",
                }
            }],
        },
    ],
)

注意

您必須在步驟 3 toolResult中同時包含助理toolUse訊息和您的。集合刻意不會保留內嵌函數向工作階段的輪換 - 如果用戶端從未傳回結果，則保留部分輪換（在沒有相符 toolUse的輔助toolResult) 會使工作階段處於損毀狀態。透過要求用戶端傳送兩個訊息，無論用戶端是否完成工具呼叫，工作階段都會保持乾淨。

代理程式會使用工具結果繼續推理，並串流最終回應。

AgentCore CLI

將內嵌函數工具新增至繫帶：


agentcore add tool --harness my-agent --type inline_function \
  --name get_weather

然後在中定義描述和輸入結構描述app/my-agent/harness.json：


{
  "type": "inline_function",
  "name": "get_weather",
  "config": {
    "inlineFunction": {
      "description": "Get the current weather for a city.",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }
}

執行 agentcore deploy以套用。當客服人員在調用期間呼叫內嵌函數時，TUI 會暫停並提示您內嵌提供工具結果。在非互動式 (CLI) 模式中，串流會傳回，stopReason: "tool_use"而您會透過後續叫用呼叫將結果傳回。

進一步了解每個工具：

工具

注意

新增工具

範例

注意

Web 搜尋

區域可用性

範例

內嵌函數呼叫

範例

注意

相關主題