工具

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

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

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

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

支持的模式：

模式	示例	Matches
`*`	`"*"`	所有工具
普通的名字	`"shell"`	按名称内置
内置地球仪	`"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范围 LLM 工具选择InvokeHarness仅在此期间。它不会影响 InvokeAgentRuntimeCommand，它是一个单独的 API，具有自己的 IAM 操作 (bedrock-agentcore:InvokeAgentRuntimeCommand)，无需通过 LLM 即可直接执行命令。为防止直接执行命令，请勿bedrock-agentcore:InvokeAgentRuntimeCommand在您的 IAM 策略中授权。

添加工具

例

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在项目目录中运行，选择添加，选择 H arn ess，然后进入高级设置。启用 “带空格的工具”，然后按 Enter。

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

然后跑agentcore deploy去申请。

网页搜寻

要让您的代理进行网络搜索，请将 Web S earch Tool 连接器放在AgentCore 网关后面，然后将该网关作为agentcore_gateway工具连接到您的安全带上。该网关将网络搜索作为标准的 MCP WebSearch 工具公开。您的代理会像任何其他网关工具一样发现并调用它。 AgentCore Gateway 完全在内部提供所有查询 AWS。有关隐私模型和专门构建的 Web 索引的更多信息，请参阅 Web 搜索工具连接器页面。

区域可用性

Web 搜索工具在美国东部（弗吉尼亚北部）us-east-1区域提供。在中创建网关和线束us-east-1。

完成以下步骤，为您的安全带设置网络搜索。

创建网关和连接器目标。按照设置 Web 搜索工具中的步骤创建网关（MCP 协议、AWS_IAM入站身份验证）并使用添加目标。connectorId: "web-search"该目标需要在连接器bedrock-agentcore:InvokeWebSearch上使用网关服务角色。有关更多信息，请参阅配置网关服务角色。当网关 ARN 到达时，请记下网关 ARN。READY
授予安全带执行角色访问权限。网关 ARN bedrock-agentcore:InvokeGateway 上需要的线束执行角色（不同于上一步中的网关服务角色）。有关所需权限的更多信息，请参阅安全主题中的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",
                }
            }],
        },
    ],
)

注意

在步骤 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"然后通过后续调用将结果发送回去。

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

工具

注意

添加工具

例

注意

网页搜寻

区域可用性

例

内联函数调用

例

注意

相关主题