Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Invoca un AgentCore Agente de ejecución
El InvokeAgentRuntime la operación le permite enviar solicitudes a personas específicas AgentCore Los puntos de enlace se identifican por su nombre de recurso de Amazon (ARN) y reciben respuestas en streaming que contienen los resultados del agente. La API admite la administración de sesiones mediante identificadores de sesión, lo que le permite mantener el contexto de la conversación en varias interacciones. Puede dirigirse a puntos finales de agentes específicos mediante calificadores opcionales.
Para llamar InvokeAgentRuntime , necesitas bedrock-agentcore:InvokeAgentRuntime permisos. En la llamada, también puedes pasar un token de portador que el agente puede usar para la autenticación del usuario.
El InvokeAgentRuntime La operación acepta la carga útil de la solicitud en forma de datos binarios de hasta 100 MB de tamaño y devuelve una respuesta en streaming que entrega fragmentos de datos en tiempo real a medida que el agente procesa la solicitud. Este enfoque de transmisión permite recibir resultados parciales de forma inmediata en lugar de esperar a recibir la respuesta completa, por lo que es ideal para aplicaciones interactivas.
Para enviar el POST de invocación a un puerto de servicio o ruta de invocación diferente de su contenedor, consulte Configure el puerto de servicio y la ruta de invocación de su agente. Estas configuraciones funcionan sin habilitar los puntos finales de la sesión.
Para acceder a rutas o puertos de aplicaciones adicionales en la misma sesión, consulte Conéctese a las sesiones de ejecución a través de un punto final de sesión. Para los tiempos de ejecución con los puntos finales de sesión habilitados, la respuesta de invocación incluye una opción opcional X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url encabezado.
Para ejecutar comandos de shell (como ejecutar pruebas, operaciones de git o configurar el entorno) en la misma sesión, usa el Ejecuta los comandos de shell en AgentCore Sesiones de ejecución operación. Ambas operaciones funcionan en el mismo tiempo de ejecución y sesión del agente.
Si planeas integrar tu agente con OAuth, no puedes usar el AWS SDK para llamar InvokeAgentRuntime . En su lugar, haz una solicitud HTTPS a InvokeAgentRuntime. Para obtener más información, consulte Autentique y autorice con la autenticación entrante y la autenticación saliente.
Invoca a los agentes de streaming
El siguiente ejemplo muestra cómo usar boto3 para invocar el tiempo de ejecución de un agente:
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)
Invoca agentes multimodales
Puede utilizar el InvokeAgentRuntime operación para enviar solicitudes multimodales que incluyen texto e imágenes. El siguiente ejemplo muestra cómo invocar un agente multimodal:
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 )
Administración de sesiones
La InvokeAgentRuntime la operación admite la administración de sesiones a través del runtimeSessionId parámetro. Al proporcionar el mismo identificador de sesión en varias solicitudes, puede mantener el contexto de la conversación, lo que permite al agente hacer referencia a las interacciones anteriores.
Para iniciar una conversación nueva, genere un identificador de sesión único. Para continuar una conversación existente, usa el mismo identificador de sesión de las solicitudes anteriores. Este enfoque le permite crear aplicaciones interactivas que mantienen el contexto a lo largo del tiempo.
Para obtener mejores resultados, utilice un UUID u otro identificador único para los ID de sesión a fin de evitar colisiones entre diferentes usuarios o conversaciones.
Gestión de errores
Cuando utilices el InvokeAgentRuntime durante la operación, es posible que se produzcan varios errores. Estos son algunos errores comunes y cómo solucionarlos:
- ValidationException
-
Se produce cuando los parámetros de la solicitud no son válidos. Compruebe que el ARN de su agente, el ID de sesión y la carga útil estén formateados correctamente.
- ResourceNotFoundException
-
Se produce cuando no se puede encontrar el tiempo de ejecución del agente especificado. Compruebe que el ARN del agente es correcto y que el agente existe en su AWS cuenta.
- AccessDeniedException
-
Se produce cuando no tienes los permisos necesarios. Asegúrese de que su política de IAM incluya los
bedrock-agentcore:InvokeAgentRuntimepermiso. - ThrottlingException
-
Se produce cuando se superan los límites de frecuencia de solicitudes. Implemente la lógica de retroceso y reintento exponencial en su aplicación.
- RetryableConflictException
-
Se produce (HTTP 409) cuando una segunda operación tiene como objetivo una sesión mientras el servicio aprovisiona o interrumpe esa sesión. El mensaje es
Session operation in progress, please retry. Esta afección es transitoria y se puede volver a intentar. La ventana es breve y las sesiones que ya se están ejecutando no se ven afectadas. Vuelva a intentarlo con un breve retroceso exponencial. El AWS Los SDK reintentan automáticamente esta excepción cuando están habilitados los reintentos predeterminados. Si has desactivado los reintentos o has llamado directamente a la API, vuelve a intentarlo tú mismo.
Implementa una gestión de errores adecuada en tu aplicación para ofrecer una mejor experiencia de usuario y solucionar los problemas de forma eficaz.
Prácticas recomendadas
Siga estas prácticas recomendadas cuando utilice el InvokeAgentRuntime operación:
-
Valide que el campo de aviso sea una cadena en el punto de entrada de su agente—La carga útil llega en forma de JSON analizado, por lo que
promptel campo puede ser de cualquier tipo de JSON (cadena, lista, objeto). Si es un valor que no es una cadena y contiene untoolUseel bloque de contenido llega al marco de su agente, el marco podría ejecutar la herramienta mencionada directamente. Se pasa por alto el razonamiento modelo y la evaluación cautelar. Haga cumplir siempreisinstance(prompt, str)antes de pasar la información al agente. Para obtener más información, consulte Mejores prácticas de seguridad para AgentCore Tiempo de ejecución. -
Utilice la administración de sesiones para mantener el contexto de la conversación y mejorar la experiencia del usuario.
-
Procese las respuestas de transmisión de forma incremental para proporcionar comentarios en tiempo real a los usuarios.
-
Implemente el manejo de errores y la lógica de reintentos adecuados para una aplicación sólida.
-
Tenga en cuenta las limitaciones de tamaño de la carga útil (100 MB) al enviar las solicitudes, especialmente para el contenido multimodal.
-
Utilice los calificadores adecuados para dirigirse a versiones de agentes o puntos de enlace específicos.
-
Implemente mecanismos de autenticación cuando sea necesario utilizando tokens de portador.
-
Utilice
InvokeAgentRuntimeCommandpara operaciones deterministas (pruebas, git, compilaciones) en lugar de enrutarlas a través del LLM del agente. Consulte Ejecute comandos de shell en AgentCore Sesiones de ejecución.