Tools

Pass tools at create, update, or invoke time:

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": {
                "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/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."}]}],
)

Set the harness tools with the --tools JSON when you add it to a project. Include only the tool entries that the harness needs:

agentcore add harness \
  --name my_agent \
  --tools '[
    {"type":"remote_mcp","name":"exa","config":{"remoteMcp":{"url":"https://mcp.exa.ai/mcp"}}},
    {"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}"}}}},
    {"type":"agentcore_browser","name":"browser"},
    {"type":"agentcore_code_interpreter","name":"code-interpreter"},
    {"type":"agentcore_gateway","name":"my-gateway","config":{"agentCoreGateway":{"gatewayArn":"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway","outboundAuth":{"awsIam":{}}}}},
    {"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"]}}}}
  ]'
agentcore deploy

Use the SDK when you need to override the tools for one invocation without changing the deployed harness.

Attach the gateway at create time (or pass tools on update_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,
)

The gateway’s tools are now available to the agent. Invoke the harness with a prompt that needs current information:

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

With the AgentCore CLI, you can declare the gateway and its web-search connector target in the project instead of following the setup page. Deploy the project in us-east-1. On the first deploy, --region us-east-1 sets the Region of the default deployment target.

agentcore add gateway --name wsgw --protocol-type MCP --authorizer-type AWS_IAM
agentcore add gateway-connector --gateway wsgw --connector web-search --name web-search
agentcore deploy --region us-east-1

Run agentcore status --json and copy the arn of the wsgw gateway. Use it as the gatewayArn value in the --tools JSON:

# Attach the web-search gateway to your harness
agentcore add harness \
  --name research_agent \
  --tools '[{"type":"agentcore_gateway","name":"web-search","config":{"agentCoreGateway":{"gatewayArn":"<wsgw-gateway-arn>","outboundAuth":{"awsIam":{}}}}}]'

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

Attach the gateway at create time (or pass tools on update_harness / invoke_harness):

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

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

The Web Answer tool is now available to the agent. Invoke the harness with a question that needs current information:

response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    messages=[{"role": "user", "content": [{"text": "What are the Basel III minimum requirements for Tier 1 capital? Cite your sources."}]}],
)

Pass an inline function tool at invoke time:

import json

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

# 1. Invoke with the inline function tool
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    tools=tools,
    messages=[{"role": "user", "content": [{"text": "What's the weather in Seattle?"}]}],
)

# 2. Capture the toolUseId and input, then wait for the handoff boundary
tool_use_id = None
tool_block_index = None
tool_input = None
last_stop_reason = None
for event in response["stream"]:
    if "contentBlockStart" in event:
        content_block_start = event["contentBlockStart"]
        start = content_block_start.get("start", {})
        if (
            tool_use_id is None
            and "toolUse" in start
            and start["toolUse"].get("name") == "get_weather"
        ):
            tool_use_id = start["toolUse"]["toolUseId"]
            tool_block_index = content_block_start["contentBlockIndex"]
    if "contentBlockDelta" in event:
        content_block_delta = event["contentBlockDelta"]
        delta = content_block_delta.get("delta", {})
        if (
            content_block_delta.get("contentBlockIndex") == tool_block_index
            and "toolUse" in delta
        ):
            tool_input = (tool_input or "") + delta["toolUse"].get("input", "")
    if "messageStop" in event:
        last_stop_reason = event["messageStop"].get("stopReason")

if last_stop_reason != "tool_use" or tool_use_id is None:
    raise RuntimeError("The inline function was not handed off for execution.")

# 3. Execute the tool yourself and send the matching result back
tool_arguments = json.loads(tool_input or "{}")
# Run your client-side implementation with tool_arguments.
tool_result = "72°F, partly cloudy"
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    tools=tools,
    messages=[{
        "role": "user",
        "content": [{
            "toolResult": {
                "toolUseId": tool_use_id,
                "content": [{"text": tool_result}],
                "status": "success",
            }
        }],
    }],
)

For adjacent inline function calls in one model response, return the pending result and any immediately following results in one follow-up request. The harness processes them in order. If a harness-executed tool separates two inline calls, wait for another tool_use handoff before returning the later result.

Before using an after_tool_call event for an inline function as an authorization or audit signal, read Use tool-call hooks with inline functions.

Consume response["stream"] to receive the streamed tool result and any subsequent agent output. If the last messageStop has stopReason set to tool_use, repeat the handoff flow for the next inline function.

Add an inline function tool to a harness:

agentcore add harness \
  --name my_agent \
  --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"]}}}}]'
agentcore deploy

The CLI stores the tool in the tools collection of app/my_agent/harness.yaml. When the agent calls the inline function, agentcore invoke --harness my_agent shows the tool call and the turn ends with stopReason set to tool_use. To return the result and continue the session, use the SDK flow in the preceding tab.