Tools (Herramientas)

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

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

# 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"]}'

Despliegue 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"

Ejecute agentcore en un directorio de proyectos, seleccione agregar, elija Harness y avance a la configuración avanzada. Active Herramientas con espacio y, a continuación, pulse Entrar.

A continuación, ejecute agentcore deploy para aplicarla.

Adjunte la puerta de enlace en el momento de la creación (o tools update_harness transfiérala/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 pasarela ya están disponibles para el agente. Invoque el arnés con un mensaje que requiera 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."}]}],
)

# 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."

Pase una herramienta de función en línea 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",
                }
            }],
        },
    ],
)

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

Añada una herramienta de función 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 stopReason: "tool_use" y usted devuelve el resultado con una llamada de invocación de seguimiento.