# Rufen Sie einen Runtime-Agenten auf AgentCore
<a name="runtime-invoke-agent"></a>

Mit diesem [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)Vorgang können Sie Anfragen an bestimmte AgentCore Runtime-Endpunkte senden, die anhand ihres Amazon-Ressourcennamens (ARN) identifiziert werden, und Streaming-Antworten erhalten, die die Ausgabe des Agenten enthalten. Die API unterstützt die Sitzungsverwaltung mithilfe von Sitzungs-IDs, sodass Sie den Konversationskontext über mehrere Interaktionen hinweg aufrechterhalten können. Mithilfe optionaler Qualifier können Sie auf bestimmte Agenten-Endpunkte abzielen.

Um anzurufen`InvokeAgentRuntime`, benötigen `bedrock-agentcore:InvokeAgentRuntime` Sie Berechtigungen. In dem Anruf können Sie auch ein Bearer-Token übergeben, das der Agent für die Benutzerauthentifizierung verwenden kann.

Der `InvokeAgentRuntime` Vorgang akzeptiert Ihre Anforderungsnutzdaten als Binärdaten mit einer Größe von bis zu 100 MB und gibt eine Streaming-Antwort zurück, die Datenblöcke in Echtzeit überträgt, während der Agent Ihre Anfrage verarbeitet. Dieser Streaming-Ansatz ermöglicht es Ihnen, Teilergebnisse sofort zu erhalten, anstatt auf die vollständige Antwort zu warten, was ihn ideal für interaktive Anwendungen macht.

Um Shell-Befehle (wie das Ausführen von Tests, Git-Operationen oder das Einrichten der Umgebung) in derselben Sitzung [auszuführen, verwenden Sie den Vorgang Shell-Befehle in AgentCore Runtime-Sitzungen](runtime-execute-command.md) ausführen. Beide Operationen funktionieren auf derselben Agenten-Laufzeit und Sitzung.

Wenn Sie vorhaben, Ihren Agenten in OAuth zu integrieren, können Sie das AWS SDK nicht für Anrufe verwenden. `InvokeAgentRuntime` Stellen Sie stattdessen eine HTTPS-Anfrage an. InvokeAgentRuntime Weitere Informationen finden Sie unter [Authentifizieren und Autorisieren mit Inbound Auth und Outbound Auth.](runtime-oauth.md)

## Rufen Sie Streaming-Agenten auf
<a name="runtime-invoke-streaming-example"></a>

Das folgende Beispiel zeigt, wie man boto3 verwendet, um eine Agenten-Laufzeit aufzurufen:

```
import boto3
import json

# Initialize the Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)


# Process and print the response
if "text/event-stream" in response.get("contentType", ""):

    # Handle streaming response
    content = []
    for line in response["response"].iter_lines(chunk_size=10):
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                line = line[6:]
                print(line)
                content.append(line)
    print("\nComplete response:", "\n".join(content))

elif response.get("contentType") == "application/json":
    # Handle standard JSON response
    content = []
    for chunk in response.get("response", []):
        content.append(chunk.decode('utf-8'))
    print(json.loads(''.join(content)))

else:
    # Print raw response for other content types
    print(response)
```

## Rufen Sie multimodale Agenten auf
<a name="runtime-invoke-multimodal"></a>

Sie können den `InvokeAgentRuntime` Vorgang verwenden, um multimodale Anfragen zu senden, die sowohl Text als auch Bilder enthalten. Das folgende Beispiel zeigt, wie ein multimodaler Agent aufgerufen wird:

```
import boto3
import json
import base64

# Read and encode image
with open("image.jpg", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

# Prepare multi-modal payload
payload = json.dumps({
    "prompt": "Describe what you see in this image",
    "media": {
        "type": "image",
        "format": "jpeg",
        "data": image_data
 }
}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)
```

## Verwaltung von Sitzungen
<a name="runtime-invoke-session-management"></a>

Die `InvokeAgentRuntime` Operation unterstützt die Sitzungsverwaltung über den `runtimeSessionId` Parameter. Indem Sie dieselbe Sitzungs-ID für mehrere Anfragen angeben, können Sie den Konversationskontext beibehalten, sodass der Agent auf frühere Interaktionen verweisen kann.

Um eine neue Konversation zu beginnen, generieren Sie eine eindeutige Sitzungs-ID. Um eine bestehende Konversation fortzusetzen, verwenden Sie dieselbe Sitzungs-ID aus früheren Anfragen. Dieser Ansatz ermöglicht es Ihnen, interaktive Anwendungen zu erstellen, die den Kontext im Laufe der Zeit beibehalten.

**Tipp**  
Um optimale Ergebnisse zu erzielen, verwenden Sie eine UUID oder eine andere eindeutige Kennung für Ihre Sitzungs-IDs, um Kollisionen zwischen verschiedenen Benutzern oder Konversationen zu vermeiden.

## Fehlerbehandlung
<a name="runtime-invoke-error-handling"></a>

Bei der Verwendung des `InvokeAgentRuntime` Vorgangs können verschiedene Fehler auftreten. Hier sind einige häufig auftretende Fehler und deren Behebung:

 **ValidationException**   
Tritt auf, wenn die Anforderungsparameter ungültig sind. Vergewissern Sie sich, dass Ihr Agenten-ARN, Ihre Sitzungs-ID und Ihre Payload korrekt formatiert sind.

 **ResourceNotFoundException**   
Tritt auf, wenn die angegebene Agenten-Laufzeit nicht gefunden werden kann. Stellen Sie sicher, dass der Agenten-ARN korrekt ist und dass der Agent in Ihrem AWS Konto vorhanden ist.

 **AccessDeniedException**   
Tritt auf, wenn Sie nicht über die erforderlichen Berechtigungen verfügen. Stellen Sie sicher, dass Ihre IAM-Richtlinie die `bedrock-agentcore:InvokeAgentRuntime` Erlaubnis beinhaltet.

 **ThrottlingException**   
Tritt auf, wenn Sie die Grenzwerte für die Anforderungsrate überschreiten. Implementieren Sie eine exponentielle Backoff- und Wiederholungslogik in Ihrer Anwendung.

Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung, um eine bessere Benutzererfahrung zu bieten und Probleme effektiv zu beheben.

## Bewährte Methoden
<a name="runtime-invoke-best-practices"></a>

Beachten Sie bei der Verwendung des `InvokeAgentRuntime` Vorgangs die folgenden bewährten Methoden:
+ Verwenden Sie die Sitzungsverwaltung, um den Konversationskontext für eine bessere Benutzererfahrung aufrechtzuerhalten.
+ Verarbeiten Sie Streaming-Antworten inkrementell, um Benutzern Feedback in Echtzeit zu geben.
+ Implementieren Sie die richtige Fehlerbehandlung und Wiederholungslogik für eine robuste Anwendung.
+ Beachten Sie beim Senden von Anfragen die Größenbeschränkungen für die Nutzlast (100 MB), insbesondere bei multimodalen Inhalten.
+ Verwenden Sie geeignete Qualifier, um bestimmte Agentenversionen oder Endpunkte ins Visier zu nehmen.
+ Implementieren Sie bei Bedarf Authentifizierungsmechanismen mithilfe von Bearer-Token.
+ Wird `InvokeAgentRuntimeCommand` für deterministische Operationen (Tests, Git, Builds) verwendet, anstatt sie über das LLM des Agenten weiterzuleiten. Siehe [Shell-Befehle in AgentCore Runtime-Sitzungen](runtime-execute-command.md) ausführen.