

# Tools

Tools sind deklarativ. Sie listen auf, was der Agent aufrufen kann; AgentCore verarbeitet Aufrufe, Anmeldeinformationen und Ergebnisse. Der Harness unterstützt fünf Werkzeugtypen sowie die integrierten Dateisystem- und Shell-Tools.
+  **MCP-Server:** Stellen Sie per URL eine Verbindung zu einem beliebigen Remote-Endpunkt des [Model Context Protocol](https://modelcontextprotocol.io) her. Für einfache Fälle ist kein Gateway erforderlich.
+  **[AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html):** Kontrollierte Konnektivität zu APIs und MCP-Servern mit inbound/outbound Authentifizierung, Zugriffskontrolle und [Richtliniendurchsetzung](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html). Wenn Sie auf einen Gateway-ARN verweisen, wird jedes auf diesem Gateway konfigurierte Tool verfügbar. Verwenden Sie Gateway, wenn Sie eine verwaltete, richtliniengestützte Tool-Oberfläche benötigen.
+  **[AgentCore Browser](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html):** Verwaltetes Surfen und Automatisierung im Internet.
+  **[AgentCore Code-Interpreter](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html):** Ausführung von Python/JavaScript/TypeScript Sandbox-Code zur Datenanalyse und Berechnung.
+  **Inline-Funktionen:** Toolschemas, die auf der Client-Seite und nicht auf der Harness-VM ausgeführt werden. Der Harness hält an, wenn das Tool aufgerufen wird, und gibt den Aufruf an Ihren Code zurück, der entscheidet, was zu tun ist, und ein Ergebnis zurücksendet. Dies ist das Muster für Genehmigungen und kundenspezifische Integrationen, die von einem Mitarbeiter selbst durchgeführt werden.

Standardtools `shell` und `file_operations` sind in jeder Sitzung verfügbar, sofern Sie sie nicht mit einschränken. `allowedTools` `shell`führt Bash-Befehle aus; `file_operations` unterstützt das Anzeigen, Erstellen und Bearbeiten von Dateien.

Der `allowedTools` Parameter steuert, welche Tools der Agent verwenden kann. Wenn nicht angegeben, sind alle Tools zulässig.

Unterstützte Muster:


| Muster | Beispiel | Entspricht | 
| --- | --- | --- | 
|  `*`  |  `"*"`  | Alle Tools | 
| Klarer Name |  `"shell"`  | Namentlich eingebaut | 
| Eingebauter Globus |  `"file_*"`  |  `file_operations`, `file_read`  | 
|  `@builtin`  |  `"@builtin"`  | Alle integrierten Tools | 
|  `@builtin/name`  |  `"@builtin/shell"`  | Spezifisch eingebaut | 
|  `@server`  |  `"@git"`  | Alle Tools von einem MCP-Server | 
|  `@server/tool`  |  `"@git/git_status"`  | Spezifisches MCP-Tool | 
|  `@server/glob`  |  `"@git/read_*"`  | Glob innerhalb eines Servers | 
|  `@*/tool`  |  `"@*-mcp/status"`  | Glob auf mehreren Servern | 

**Anmerkung**  
 `allowedTools`beschränkt sich auf die Auswahl von LLM-Tools während. `InvokeHarness` Dies hat keine Auswirkungen [InvokeAgentRuntimeCommand](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html). Dabei handelt es sich um eine separate API mit eigener IAM-Aktion (`bedrock-agentcore:InvokeAgentRuntimeCommand`), die Befehle direkt ausführt, ohne das LLM zu durchlaufen. Um die direkte Befehlsausführung zu verhindern, sollten Sie Ihre IAM-Richtlinien nicht `bedrock-agentcore:InvokeAgentRuntimeCommand` einbeziehen.

## Tools hinzufügen
<a name="_add_tools"></a>

**Example**  
`tools`Beim Erstellen, Aktualisieren oder Aufrufen übergeben:  

```python
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."}]}],
)
```
Wenn Sie interaktiv einen neuen Kabelbaum erstellen, können Sie mit dem `agentcore add harness` Assistenten Werkzeuge auswählen. Um Tools über die CLI hinzuzufügen, verwenden Sie `agentcore add tool` nach dem Erstellen des Kabelbaums:  
Das `--type` Flag verwendet durch Unterstriche getrennte Namen (z. B.`agentcore_browser`), die den Werkzeugtyp-Identifikatoren in entsprechen. `harness.json`

```bash
# 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"]}'
```
Bereitstellen, um sich zu bewerben.  
Tools bei einem einzigen Aufruf außer Kraft setzen:  

```bash
agentcore invoke --harness research-agent --tools agentcore-browser "Find the latest news on AI agents"
```
Führen Sie das Programm `agentcore` in einem Projektverzeichnis aus, wählen Sie **Hinzufügen**, wählen Sie **Harness** und wechseln Sie zu den **erweiterten Einstellungen**. Aktivieren Sie **Tools** with **Space** und drücken Sie dann **die Eingabetaste**.  

1. Wählen Sie die Tools für Ihren Kabelbaum aus: **AgentCore Browser**, **AgentCore Code Interpreter**, **AgentCore Gateway** oder **Remote MCP Server**. **Verwenden Sie die **Leertaste**, um zwischen den einzelnen Optionen umzuschalten, und drücken Sie dann die Eingabetaste.**  
![Wählen Sie die Tools aus: Browser, Codeinterpreter, Gateway, Remote-MCP-Server](https://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/harness-tools-02-picker.png)

1. Bei einem **Remote-MCP-Server** fordert der Assistent zur Eingabe des Servernamens, der URL und optionaler Anforderungsheader auf.  
![Geben Sie die URL des MCP-Servers ein](https://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/harness-tools-04-mcp-url.png)

1. **Geben Sie für ein **AgentCore Gateway** den Gateway-ARN ein und wählen Sie dessen ausgehende Authentifizierung aus: ** AWS IAM** (Standard), **None** oder OAuth.**  
![Wählen Sie Gateway-Authentifizierung für ausgehende Verbindungen](https://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/harness-tools-07-gateway-auth.png)

1. Lesen Sie die Zusammenfassung der Konfiguration und bestätigen Sie sie.  
![Überprüfen Sie die Konfiguration des Harness-Tools](https://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/harness-tools-08-confirm.png)
Starten Sie dann`agentcore deploy`, um sich zu bewerben.

## Websuche
<a name="_web_search"></a>

Um Ihrem Agenten eine Websuche zu ermöglichen, platzieren Sie den [Web Search Tool-Connector](gateway-target-connector-web-search-tool.md) hinter einem [AgentCore Gateway](gateway.md) und fügen Sie dieses Gateway als `agentcore_gateway` Tool an Ihren Kabelbaum an. Das Gateway stellt die Websuche als `WebSearch` Standard-MCP-Tool zur Verfügung. Ihr Agent erkennt es und ruft es wie jedes andere Gateway-Tool auf. AgentCore Gateway bedient alle Anfragen vollständig innerhalb von AWS Gateway. Weitere Informationen zum Datenschutzmodell und zum speziell erstellten Webindex finden Sie auf der Connector-Seite für das Web Search Tool.

**Verfügbarkeit in Regionen**  
Das Web Search Tool ist in der Region USA Ost (Nord-Virginia) `us-east-1` verfügbar. Erstellen Sie das Gateway und nutzen Sie es`us-east-1`.

Gehen Sie wie folgt vor, um die Websuche für Ihren Kabelbaum einzurichten.

1.  **Erstellen Sie das Gateway und das Connector-Ziel.** Folgen Sie den Schritten [unter Web Search Tool einrichten](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-web-search-setup), um ein Gateway (MCP-Protokoll, `AWS_IAM` eingehende Authentifizierung) zu erstellen und ein Ziel mit hinzuzufügen. `connectorId: "web-search"` Dieses Ziel benötigt eine Gateway-Dienstrolle mit `bedrock-agentcore:InvokeWebSearch` auf dem Connector. Weitere Informationen finden [Sie unter Konfigurieren der Gateway-Dienstrolle](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-web-search-service-role). Notieren Sie sich den Gateway-ARN, sobald er erreicht ist`READY`.

1.  **Gewähren Sie der Harness-Ausführungsrolle Zugriff.** Die Harness-Ausführungsrolle (die sich von der Gateway-Dienstrolle im vorherigen Schritt unterscheidet) muss `bedrock-agentcore:InvokeGateway` auf dem Gateway-ARN ARN sein. Weitere Informationen zu den erforderlichen Berechtigungen finden Sie in der Richtlinie für optionale [AgentCore Gateway-Berechtigungen](harness-security.md) im Sicherheitsthema. Wenn Ihr Kabelbaum verwalteten Speicher verwendet (Standardeinstellung), benötigt die Ausführungsrolle auch die [AgentCore Speicherberechtigungen](harness-security.md). Der Agent liest und schreibt den Sitzungsspeicher bei jedem Aufruf.

1.  **Schließen Sie das Gateway an den Kabelbaum an.** Fügen Sie es als `agentcore_gateway` Tool mit der standardmäßigen `AWS_IAM` ausgehenden Authentifizierung hinzu. Die folgenden Beispiele zeigen, wie das Gateway bei der Erstellung angehängt wird.

**Example**  
Hängen Sie das Gateway bei der Erstellung an (oder geben Sie`update_harness`/`tools`weiter`invoke_harness`):  

```python
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,
)
```
Die Tools des Gateways stehen dem Agenten jetzt zur Verfügung. Rufen Sie den Harness mit einer Aufforderung auf, für die aktuelle Informationen erforderlich sind:  

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

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

## Inline-Funktionsaufrufen
<a name="_inline_function_calls"></a>

Mit Inline-Funktionen können Sie ein Tool definieren, das in Ihrem Code und nicht im Harness ausgeführt wird. Dies ist nützlich für Genehmigungen durch einen Benutzer, den Aufruf interner APIs oder für jede Logik, die Sie clientseitig steuern möchten.

**Example**  
Übergeben Sie beim Aufrufen ein Inline-Funktionstool:  

```python
# 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",
                }
            }],
        },
    ],
)
```
Sie müssen sowohl die `toolUse` Assistentennachricht als auch Ihre `toolResult` in Schritt 3 angeben. Im Harness wird die Inline-Funktion „Turn to the Session“ absichtlich nicht beibehalten. Wenn der Client kein Ergebnis zurückgibt, würde das Fortbestehen eines teilweisen Zugangs (Assistent `toolUse` ohne Treffer`toolResult`) dazu führen, dass die Sitzung in einem fehlerhaften Zustand bleibt. Dadurch, dass der Client beide Nachrichten senden muss, bleibt die Sitzung sauber, unabhängig davon, ob der Client den Toolaufruf abschließt.
Der Agent setzt die Argumentation anhand des Tool-Ergebnisses fort und streamt die endgültige Antwort.
Fügen Sie einem Kabelbaum ein integriertes Funktionswerkzeug hinzu:  

```bash
agentcore add tool --harness my-agent --type inline_function \
  --name get_weather
```
Definieren Sie dann die Beschreibung und das Eingabeschema in`app/my-agent/harness.json`:  

```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"]
      }
    }
  }
}
```
Ausführen`agentcore deploy`, um sich zu bewerben. Wenn der Agent die Inline-Funktion während eines Aufrufs aufruft, hält die TUI an und fordert Sie auf, das Tool-Ergebnis inline bereitzustellen. Im nicht interaktiven Modus (CLI) kehrt der Stream mit zurück `stopReason: "tool_use"` und Sie senden das Ergebnis mit einem nachfolgenden Aufrufaufruf zurück.

Erfahren Sie mehr über die einzelnen Tools:
+  [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) · [ein Gateway erstellen](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create.html) · [Richtlinien](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html) 
+  [AgentCore Browser](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html) · [Browserprofile](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-profiles.html) · [Sitzungsaufzeichnung](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-session-recording.html) 
+  [AgentCore Code-Interpreter](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html) · [vorinstallierte Bibliotheken](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-preinstalled-libraries.html) 

### Verwandte Themen
<a name="_related_topics"></a>
+  [Modelle und Anleitungen](harness-models.md)- Modelle konfigurieren und pro Aufruf überschreiben
+  [Umgebung und Dateisystem](harness-environment.md)- Bringen Sie Ihren eigenen Container mit und führen Sie Shell-Befehle aus
+  [Sicherheit und Zugriffskontrollen](harness-security.md)- kontrollieren Sie anhand von Richtlinien, auf welche Tools der Agent zugreifen kann
+  [API-Dokumentation](harness-get-started.md#api-documentation) 