工具

工具是声明性的。您可以列出代理可以调用的内容； AgentCore 处理调用、凭证和结果。该工具支持五种工具类型，以及内置的文件系统和外壳工具。

MCP 服务器：通过 URL 连接到任何远程模型上下文协议端点。对于简单的案例，无需网关。
AgentCore 网关：通过 inbound/outbound 身份验证、访问控制和策略执行来管理与 API 和 MCP 服务器的连接。参考网关 ARN，在该网关上配置的所有工具都可用。当您需要托管的、受策略支持的工具界面时，请使用 Gateway。
AgentCore 浏览器：托管式网页浏览和自动化。
AgentCore 代码解释器：用于数据分析和计算的沙盒化 Python/JavaScript/TypeScript 代码执行。
内联函数：在客户端执行的工具架构，而不是在安全带虚拟机上执行的工具架构。调用该工具时，安全带会暂停，并将调用返回到您的代码，由代码决定要做什么并将结果发送回去。这是人工在环审批和自定义集成的模式。

默认工具shell，file_operations除非您对其进行限制，否则它们在每个会话中都可用allowedTools。shell执行 bash 命令；file_operations支持查看、创建和编辑文件。

该allowedTools参数控制代理可以使用哪些工具。如果省略，则允许使用所有工具。

工具定义产生的代币开销

即使代理不调用工具，工具定义也会计入模型输入标记。默认值shell和file_operations定义一起为每个模型请求添加了大约 900 个输入标记。确切数量因型号而异，并且会随着工具定义的变化而变化。由于一次调用可以发出多个模型请求，因此每次调用可能会产生不止一次的开销。allowedTools用于仅公开请求所需的工具并减少令牌的使用。

支持的模式：

模式	示例	Matches
`*`	`"*"`	所有工具
普通的名字	`"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"`	跨服务器全局浏览

注意

allowedToolsInvokeHarness仅在 LLM 工具选择期间适用。它不影响 InvokeAgentRuntimeCommand，这是一个具有自己的 IAM 操作 (bedrock-agentcore:InvokeAgentRuntimeCommand) 的单独的 API，无需通过 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

# Create a harness with a remote MCP server and request headers.
# Use ${arn:...} syntax to reference a credential provider.
agentcore add harness \
  --name secure_agent \
  --model-provider bedrock \
  --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
  --tools remote_mcp \
  --mcp-name exa-secure \
  --mcp-url https://mcp.exa.ai/mcp \
  --mcp-headers '{"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中运行，选择 “添加”，选择 “H ar ness”，然后进入高级设置。启用 “带空格的工具”，然后按 Enter 。

为您的工具选择工具：AgentCore 浏览器、AgentCore 代码解释器、AgentCore 网关或远程 MCP 服务器。使用空格键切换每个，然后按 Enter 。
对于远程 MCP 服务器，向导会提示输入服务器名称、URL 和可选的请求标头。
对于AgentCore 网关，输入网关 ARN 并选择其出站身份验证： AWS IAM（默认）、无或 O Auth。
查看配置摘要并确认。

然后运行agentcore deploy申请。

网络搜索

要为您的代理提供网络搜索，请将 Web 搜索工具连接器放在AgentCore 网关后面，并将该网关作为agentcore_gateway工具连接到您的安全带上。该网关将网络搜索作为标准的 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，请注意它。
授予线束执行角色访问权限。线束执行角色（不同于bedrock-agentcore:InvokeGateway上一步中的网关服务角色）需要网关 ARN。有关所需权限的更多信息，请参阅安全主题中的AgentCore 网关可选权限策略。如果您的工具使用托管内存（默认），则执行角色还需要AgentCore 内存权限。代理在每次调用时读取和写入会话内存。
将网关连接到安全带上。将其添加为具有默认AWS_IAM出站身份验证的agentcore_gateway工具。以下示例显示如何在创建时连接网关。

例

内联函数调用

内联函数允许您定义在代码中执行的工具，而不是在安全带上执行的工具。这对于人工在环审批、调用内部 API 或任何你想控制客户端的逻辑都很有用。

例

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",
                }
            }],
        },
    ],
)

注意

您必须toolResult在步骤 3 中同时包含助手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"，您通过后续调用将结果发送回去。

了解有关每种工具的更多信息：

工具

工具定义产生的代币开销

注意

添加工具

例

注意

网络搜索

区域可用性

例

内联函数调用

例

注意

相关主题