도구

도구는 선언적입니다. 에이전트가 호출할 수 있는 항목을 나열합니다. AgentCore는 호출, 자격 증명 및 결과를 처리합니다. 이 하네스는 5가지 도구 유형과 내장 파일 시스템 및 쉘 도구를 지원합니다.

MCP 서버: URL을 기준으로 원격 모델 컨텍스트 프로토콜 엔드포인트에 연결합니다. 간단한 경우에는 게이트웨이가 필요하지 않습니다.
AgentCore Gateway: 인바운드/아웃바운드 인증, 액세스 제어 및 정책 적용을 통해 APIs 및 MCP 서버에 대한 연결을 제어합니다. 게이트웨이 ARN을 참조하면 해당 게이트웨이에 구성된 모든 도구를 사용할 수 있게 됩니다. 관리형 정책 지원 도구 표면이 필요한 경우 Gateway를 사용합니다.
AgentCore 브라우저: 관리형 웹 브라우징 및 자동화.
AgentCore 코드 해석기: 데이터 분석 및 계산을 위한 샌드박스 Python/JavaScript/TypeScript 코드 실행.
인라인 함수: 하네스 VM이 아닌 클라이언트 측에서 실행되는 도구 스키마입니다. 도구가 호출되면 하네스가 일시 중지되고 호출을 코드에 반환하여 수행할 작업을 결정하고 결과를 다시 보냅니다. 이는 human-in-the-loop 승인 및 사용자 지정 통합의 패턴입니다.

로 제한하지 않는 한 모든 세션에서 기본 도구 shell 및를 사용할 수 있습니다allowedTools. file_operations는 bash 명령을 shell 실행하고 파일 보기, 생성 및 편집을 file_operations 지원합니다.

allowedTools 파라미터는 에이전트가 사용할 수 있는 도구를 제어합니다. 생략하면 모든 도구가 허용됩니다.

지원되는 패턴:

패턴	예제	일치 항목
`*`	`"*"`	모든 도구
일반 이름	`"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"`	서버 간 Glob

참고

allowedTools는 LLM 도구 선택의 범위를 도중InvokeHarness에만 지정합니다. LLM을 통과하지 않고 직접 명령을 실행하는 자체 IAM 작업(bedrock-agentcore:InvokeAgentRuntimeCommand)이 있는 별도의 API인 InvokeAgentRuntimeCommand에는 영향을 주지 않습니다. 직접 명령 실행을 방지하려면 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

# 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에서 실행하고 추가를 선택한 다음, 하네스를 선택하고 고급 설정으로 이동합니다. 스페이스가 있는 도구를 활성화한 다음 Enter 키를 누릅니다.

하네스에 사용할 도구: AgentCore Browser , AgentCore Code Interpreter , AgentCore Gateway 또는 원격 MCP Server를 선택합니다. 스페이스를 사용하여 각각을 전환한 다음 Enter 키를 누릅니다.
원격 MCP 서버의 경우 마법사는 서버 이름, URL 및 선택적 요청 헤더를 묻는 메시지를 표시합니다.
AgentCore 게이트웨이의 경우 게이트웨이 ARN을 입력하고 아웃바운드 인증인 AWS IAM(기본값), 없음 또는 OAuth를 선택합니다.
구성 요약을 검토하고 확인합니다.

그런 다음를 실행agentcore deploy하여 적용합니다.

웹 검색

에이전트 웹 검색을 제공하려면 AgentCore 게이트웨이 뒤에 웹 검색 도구 커넥터를 배치하고 해당 게이트웨이를 agentcore_gateway 도구로 하네스에 연결합니다. 게이트웨이는 웹 검색을 표준 MCP WebSearch 도구로 노출합니다. 에이전트는 다른 게이트웨이 도구처럼 이를 검색하고 호출합니다. AgentCore Gateway는 전체 내에서 모든 쿼리를 제공합니다 AWS. 개인 정보 보호 모델 및 특별히 구축된 웹 인덱스에 대한 자세한 내용은 웹 검색 도구 커넥터 페이지를 참조하세요.

리전 가용성

웹 검색 도구는 미국 동부(버지니아 북부) us-east-1 리전에서 사용할 수 있습니다. 에서 게이트웨이와 하네스를 생성합니다us-east-1.

다음 단계를 완료하여 하네스에 대한 웹 검색을 설정합니다.

게이트웨이 및 커넥터 대상을 생성합니다. 웹 검색 도구 설정의 단계에 따라 게이트웨이(MCP 프로토콜, AWS_IAM 인바운드 인증)를 생성하고를 사용하여 대상을 추가합니다connectorId: "web-search". 이 대상에는 커넥터bedrock-agentcore:InvokeWebSearch에가 있는 게이트웨이 서비스 역할이 필요합니다. 자세한 내용은 게이트웨이 서비스 역할 구성을 참조하세요. 게이트웨이 ARN이에 도달하면 기록해 둡니다READY.
하네스 실행 역할에 액세스 권한을 부여합니다. 하네스 실행 역할(이전 단계의 게이트웨이 서비스 역할과 다름)은 게이트웨이 ARNbedrock-agentcore:InvokeGateway에 필요합니다. 필요한 권한에 대한 자세한 내용은 보안 주제의 AgentCore Gateway optional-permissions 정책을 참조하세요. 하네스가 관리형 메모리(기본값)를 사용하는 경우 실행 역할에는 AgentCore 메모리 권한도 필요합니다. 에이전트는 각 호출에서 세션 메모리를 읽고 씁니다.
게이트웨이를 하네스에 연결합니다. 기본 AWS_IAM 아웃바운드 인증이 있는 agentcore_gateway 도구로 추가합니다. 다음 예제에서는 생성 시 게이트웨이를 연결하는 방법을 보여줍니다.

예

인라인 함수 호출

인라인 함수를 사용하면 하네스가 아닌 코드에서 실행되는 도구를 정의할 수 있습니다. 이는 루프 human-in-the-loop 승인, 내부 APIs 호출 또는 클라이언트 측을 제어하려는 로직에 유용합니다.

예

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단계에는 어시스턴트 toolUse 메시지와 toolResult를 모두 포함해야 합니다. 하네스는 의도적으로 세션에 대한 인라인 함수 턴을 유지하지 않습니다. 클라이언트가 결과를 반환하지 않으면 부분 턴(일치하는가 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"하고 후속 호출과 함께 결과를 다시 보냅니다.

각 도구에 대해 자세히 알아보세요.

도구

참고

도구 추가

예

참고

웹 검색

리전 가용성

예

인라인 함수 호출

예

참고

관련 주제