View a markdown version of this page

Invocar um AgentCore Agente Runtime - Rocha da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Invocar um AgentCore Agente Runtime

O InvokeAgentRuntime operação permite que você envie solicitações para determinados AgentCore Os endpoints de execução são identificados pelo nome de recurso da Amazon (ARN) e recebem respostas de streaming contendo a saída do agente. A API oferece suporte ao gerenciamento de sessões por meio de identificadores de sessão, permitindo que você mantenha o contexto da conversa em várias interações. Você pode segmentar endpoints específicos do agente usando qualificadores opcionais.

Para ligar InvokeAgentRuntime , você precisa bedrock-agentcore:InvokeAgentRuntime permissões. Na chamada, você também pode passar um token de portador que o agente pode usar para autenticação do usuário.

O InvokeAgentRuntime A operação aceita a carga útil da solicitação como dados binários de até 100 MB e retorna uma resposta de streaming que fornece blocos de dados em tempo real à medida que o agente processa sua solicitação. Essa abordagem de streaming permite que você receba resultados parciais imediatamente, em vez de esperar pela resposta completa, tornando-a ideal para aplicativos interativos.

Para enviar a invocação POST para uma porta de serviço ou caminho de invocação diferente em seu contêiner, consulte Configure a porta de atendimento e o caminho de invocação do seu agente. Essas configurações funcionam sem habilitar os endpoints da sessão.

Para acessar rotas ou portas de aplicativos adicionais na mesma sessão, consulte Conecte-se às sessões de tempo de execução por meio de um endpoint de sessão. Para tempos de execução com endpoints de sessão habilitados, a resposta de invocação inclui um opcional X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url cabeçalho.

Para executar comandos shell (como executar testes, operações do git ou configuração do ambiente) na mesma sessão, use o Execute comandos shell em AgentCore Sessões de execução operação. Ambas as operações funcionam no mesmo tempo de execução e sessão do agente.

Se você planeja integrar seu agente ao OAuth, não pode usar o AWS SDK para ligar InvokeAgentRuntime . Em vez disso, faça uma solicitação HTTPS para InvokeAgentRuntime. Para obter mais informações, consulte Autentique e autorize com autenticação de entrada e autenticação de saída.

Invoque agentes de streaming

O exemplo a seguir mostra como usar o boto3 para invocar o tempo de execução de um 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)

Invoque agentes multimodais

Você pode usar o InvokeAgentRuntime operação para enviar solicitações multimodais que incluem texto e imagens. O exemplo a seguir mostra como invocar um 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 )

Gerenciamento de sessões

O InvokeAgentRuntime a operação suporta o gerenciamento de sessões por meio do runtimeSessionId parâmetro. Ao fornecer o mesmo identificador de sessão em várias solicitações, você pode manter o contexto da conversa, permitindo que o agente faça referência às interações anteriores.

Para iniciar uma nova conversa, gere um identificador de sessão exclusivo. Para continuar uma conversa existente, use o mesmo identificador de sessão das solicitações anteriores. Essa abordagem permite criar aplicativos interativos que mantêm o contexto ao longo do tempo.

dica

Para obter melhores resultados, use um UUID ou outro identificador exclusivo para seus IDs de sessão para evitar colisões entre diferentes usuários ou conversas.

Tratamento de erros

Ao usar o InvokeAgentRuntime durante a operação, você pode encontrar vários erros. Aqui estão alguns erros comuns e como lidar com eles:

ValidationException

Ocorre quando os parâmetros da solicitação são inválidos. Verifique se o ARN, o ID da sessão e a carga útil do agente estão formatados corretamente.

ResourceNotFoundException

Ocorre quando o tempo de execução do agente especificado não pode ser encontrado. Verifique se o ARN do agente está correto e se o agente existe em seu AWS conta.

AccessDeniedException

Ocorre quando você não tem as permissões necessárias. Certifique-se de que sua política de IAM inclua a bedrock-agentcore:InvokeAgentRuntime permissão.

ThrottlingException

Ocorre quando você excede os limites da taxa de solicitação. Implemente a lógica exponencial de recuo e repetição em seu aplicativo.

RetryableConflictException

Ocorre (HTTP 409) quando uma segunda operação tem como alvo uma sessão enquanto o serviço está provisionando ou desativando essa sessão. A mensagem é Session operation in progress, please retry. Essa condição é transitória e pode ser repetida. A janela é breve e as sessões já em execução não são afetadas. Tente novamente com um pequeno recuo exponencial. O AWS Os SDKs repetem automaticamente essa exceção quando as novas tentativas padrão estão habilitadas. Se você desativou as novas tentativas ou chamou a API diretamente, tente novamente você mesmo.

Implemente o tratamento adequado de erros em seu aplicativo para oferecer uma melhor experiência ao usuário e solucionar problemas de forma eficaz.

Práticas recomendadas

Siga estas melhores práticas ao usar o InvokeAgentRuntime operação:

  • Verifique se o campo prompt é uma string no ponto de entrada do seu agente—A carga útil chega como JSON analisado, então o prompt o campo pode ser qualquer tipo de JSON (string, lista, objeto). Se um valor que não seja uma string contendo um toolUse O bloco de conteúdo atinge sua estrutura de agente, a estrutura pode executar a ferramenta nomeada diretamente. O raciocínio do modelo e a avaliação do guardrail são ignorados. Sempre aplique isinstance(prompt, str) antes de passar a entrada para o agente. Para obter mais informações, consulte Práticas recomendadas de segurança para AgentCore Tempo de execução.

  • Use o gerenciamento de sessões para manter o contexto da conversa e melhorar a experiência do usuário.

  • Processe respostas de streaming de forma incremental para fornecer feedback em tempo real aos usuários.

  • Implemente o tratamento adequado de erros e a lógica de repetição para um aplicativo robusto.

  • Considere as limitações de tamanho da carga útil (100 MB) ao enviar solicitações, especialmente para conteúdo multimodal.

  • Use os qualificadores apropriados para atingir versões ou endpoints específicos do agente.

  • Implemente mecanismos de autenticação quando necessário usando tokens portadores.

  • Uso InvokeAgentRuntimeCommand para operações determinísticas (testes, git, compilações) em vez de roteá-las pelo LLM do agente. Veja Execute comandos shell em AgentCore Sessões de execução.