View a markdown version of this page

Tools (Herramientas) - Base amazónica AgentCore
Añada herramientasBúsqueda en la webLlamadas a funciones en línea

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Tools (Herramientas)

Las herramientas son declarativas. Enumera a qué puede llamar el agente; AgentCore gestiona la invocación, las credenciales y los resultados. El arnés admite cinco tipos de herramientas, además de las herramientas integradas de sistema de archivos y shell.

  • Servidores MCP: conéctese a cualquier punto final remoto del Model Context Protocol mediante una URL. No se requiere ninguna puerta de enlace en casos sencillos.

  • AgentCore Puerta de enlace: conectividad controlada con las API y los servidores MCP con inbound/outbound autenticación, control de acceso y aplicación de políticas. Haga referencia al ARN de una puerta de enlace y todas las herramientas configuradas en esa puerta de enlace estarán disponibles. Utilice Gateway cuando necesite una superficie de herramientas gestionada y respaldada por políticas.

  • AgentCore Navegador: navegación web gestionada y automatización.

  • AgentCore Intérprete de código: ejecución de Python/JavaScript/TypeScript código en espacio aislado para el análisis y el cálculo de datos.

  • Funciones en línea: esquemas de herramientas que se ejecutan en el lado del cliente, no en la máquina virtual del arnés. El arnés hace una pausa cuando se llama a la herramienta y devuelve la llamada a su código, que decide qué hacer y devuelve el resultado. Este es el patrón para las aprobaciones y las integraciones personalizadas de forma automática.

Las herramientas son predeterminadas shell y file_operations están disponibles en todas las sesiones, a menos que las restrinjas. allowedTools shellejecuta los comandos de bash; file_operations permite ver, crear y editar archivos.

El allowedTools parámetro controla qué herramientas puede usar el agente. Si se omite, se permiten todas las herramientas.

Una sobrecarga simbólica derivada de las definiciones de las herramientas

Las definiciones de las herramientas se tienen en cuenta a la hora de modelar los tokens de entrada, incluso cuando el agente no llama a las herramientas. En conjunto, los valores predeterminados shell y file_operations las definiciones agregan aproximadamente 900 tokens de entrada a cada solicitud de modelo. El recuento exacto varía según el modelo y puede cambiar a medida que evolucionan las definiciones de las herramientas. Como una invocación puede realizar varias solicitudes de modelos, esta sobrecarga puede producirse más de una vez por invocación. allowedToolsUtilícelo para mostrar solo las herramientas necesarias para una solicitud y reducir el uso de tokens.

Patrones compatibles:

Patrón Ejemplo Coincide

*

"*"

Todas las herramientas

Nombre sencillo

"shell"

Incorporado por nombre

Globo incorporado

"file_*"

file_operations, file_read

@builtin

"@builtin"

Todas las herramientas integradas

@builtin/name

"@builtin/shell"

Incorporado específico

@server

"@git"

Todas las herramientas de un servidor MCP

@server/tool

"@git/git_status"

Herramienta MCP específica

@server/glob

"@git/read_*"

Glob dentro de un servidor

@*/tool

"@*-mcp/status"

Globe entre servidores
nota

allowedToolsabarca la selección de herramientas de LLM únicamente durante. InvokeHarness No afecta InvokeAgentRuntimeCommand, ya que se trata de una API independiente con su propia acción de IAM (bedrock-agentcore:InvokeAgentRuntimeCommand) que ejecuta los comandos directamente sin pasar por el LLM. Para evitar la ejecución directa de comandos, no aceptes tus políticas de bedrock-agentcore:InvokeAgentRuntimeCommand IAM.

Añada herramientas

ejemplo
AWS CLI/boto3

Pase tools al momento de crear, actualizar o invocar:

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

Al crear un nuevo arnés de forma interactiva, el agentcore add harness asistente le permite seleccionar las herramientas. Para agregar herramientas mediante la CLI, utilice agentcore add tool después de crear el arnés:

nota

La --type marca usa nombres separados por guiones bajos (por ejemplo,agentcore_browser), que coinciden con los identificadores de tipo de herramienta que aparecen en. 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"]}'

Implemente para aplicar.

Anule las herramientas en una sola invocación:

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

Ejecute agentcore en el directorio de un proyecto, seleccione Agregar, elija Harness y avance a la configuración avanzada. Activa Tools with Space y, a continuación, pulsa Entrar.

  1. Seleccione las herramientas que desee utilizar: AgentCore navegador, intérprete de AgentCore código , AgentCore puerta de enlace o servidor MCP remoto. Use la barra espaciadora para alternar entre sí y, a continuación, presione Entrar.

    Seleccione las siguientes herramientas: navegador, intérprete de código, puerta de enlace, servidor MCP remoto

  2. En el caso de un servidor MCP remoto, el asistente solicita el nombre del servidor, la URL y los encabezados de solicitud opcionales.

    Introduzca la URL del servidor MCP

  3. Para una AgentCore puerta de enlace, introduzca el ARN de la puerta de enlace y elija su autenticación de salida: AWS IAM (predeterminada), Ninguna u OAuth.

    Seleccione la autenticación saliente de la puerta de enlace

  4. Revise el resumen de la configuración y confirme.

    Revise la configuración de la herramienta de arnés

A continuación, ejecute agentcore deploy para aplicar.

Búsqueda en la web

Para que su agente pueda buscar en Internet, coloque el conector de la herramienta de búsqueda web detrás de una AgentCore puerta de enlace y conecte esa puerta de enlace a su arnés como agentcore_gateway herramienta. La pasarela muestra la búsqueda en la web como una herramienta MCP WebSearch estándar. Su agente la descubre y la llama como cualquier otra herramienta de pasarela. AgentCore Gateway atiende todas las consultas en su totalidad desde dentro AWS. Para obtener más información sobre el modelo de privacidad y el índice web creado específicamente, consulte la página del conector de la herramienta de búsqueda web.

Disponibilidad por región

La herramienta de búsqueda web está disponible en la región EE.UU. Este (Norte de Virginia). us-east-1 Cree la puerta de enlace y aprovéchelaus-east-1.

Complete los siguientes pasos para configurar la búsqueda web de su arnés.

  1. Cree el objetivo de la puerta de enlace y el conector. Siga los pasos de Configurar la herramienta de búsqueda web para crear una puerta de enlace (protocolo MCP, autenticación AWS_IAM entrante) y agregar un objetivo con. connectorId: "web-search" Ese objetivo necesita una función de servicio de puerta de enlace incluida bedrock-agentcore:InvokeWebSearch en el conector. Para obtener más información, consulte Configurar la función de servicio de puerta de enlace. Anote el ARN de la puerta de enlace una vez que llegueREADY.

  2. Conceda acceso al rol de ejecución del arnés. La función de ejecución del arnés (distinta de la función de servicio de puerta de enlace del paso anterior) debe estar bedrock-agentcore:InvokeGateway en el ARN de la puerta de enlace. Para obtener más información sobre los permisos necesarios, consulte la política de permisos opcionales de AgentCore Gateway en el tema de seguridad. Si su arnés usa memoria gestionada (la predeterminada), el rol de ejecución también necesita los permisos de AgentCore memoria. El agente lee y escribe la memoria de la sesión en cada invocación.

  3. Acople la puerta de enlace al arnés. Agréguelo como una agentcore_gateway herramienta con la autenticación de AWS_IAM salida predeterminada. Los siguientes ejemplos muestran cómo conectar la puerta de enlace en el momento de la creación.

ejemplo
AWS CLI/boto3

Adjunte la puerta de enlace en el momento de la creación (o pase toolsupdate_harness/invoke_harness):

tools = [
    {
        "type": "agentcore_gateway",
        "name": "web-search",
        "config": {"agentCoreGateway": {
            "gatewayArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-web-search-gateway",
            "outboundAuth": {"awsIam": {}}
        }},
    },
]

client.create_harness(
    harnessName="research-agent",
    executionRoleArn="arn:aws:iam::123456789012:role/MyHarnessRole",
    tools=tools,
)

Las herramientas de la puerta de enlace ahora están disponibles para el agente. Invoque el arnés con un mensaje que necesite información actualizada:

response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    messages=[{"role": "user", "content": [{"text": "Search the web for the latest AWS announcements and cite your sources."}]}],
)
AgentCore CLI
# Attach the web-search gateway to your harness
agentcore add tool --harness research-agent --type agentcore_gateway \
  --name web-search \
  --gateway-arn arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-web-search-gateway

# Deploy, then invoke
agentcore deploy
agentcore invoke --harness research-agent "Search the web for the latest AWS announcements and cite your sources."

Llamadas a funciones en línea

Las funciones en línea permiten definir una herramienta que se ejecuta en el código, no en el arnés. Esto resulta útil para realizar aprobaciones independientes, para llamar a las API internas o para cualquier lógica que desees controlar desde el punto de vista del cliente.

ejemplo
AWS CLI/boto3

Utiliza una herramienta de funciones integrada en el momento de la invocación:

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

Debes incluir tanto el toolUse mensaje del asistente como el tuyo toolResult en el paso 3. El arnés no persiste intencionadamente, la función en línea pasa a la sesión: si el cliente nunca devuelve un resultado, si persiste un turno parcial (asistente toolUse sin ninguna coincidenciatoolResult), la sesión quedará dañada. Al solicitar al cliente que envíe ambos mensajes, la sesión permanece limpia independientemente de que el cliente complete la llamada a la herramienta.

El agente reanuda el razonamiento con el resultado de la herramienta y transmite la respuesta final.

AgentCore CLI

Agregue una herramienta de funciones en línea a un arnés:

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

A continuación, defina la descripción y el esquema de entrada enapp/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"]
      }
    }
  }
}

Ejecute agentcore deploy para aplicar. Cuando el agente llama a la función en línea durante una invocación, la TUI hace una pausa y le pide que proporcione el resultado de la herramienta en línea. En el modo no interactivo (CLI), la transmisión regresa con stopReason: "tool_use" y tú devuelves el resultado con una llamada de invocación de seguimiento.

Más información sobre cada herramienta:

Temas relacionados