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á.
# Use a recuperação agente para consultar uma base de conhecimento
A recuperação agente usa um modelo básico para decompor de forma inteligente consultas complexas em subconsultas, recuperar iterativamente informações relevantes de suas bases de conhecimento e avaliar se os resultados recuperados são suficientes para responder à consulta original. Essa abordagem melhora a precisão da recuperação para questões complexas de várias etapas que uma única etapa de recuperação pode não resolver totalmente.
Por exemplo, dada a pergunta *“Qual revista foi criada primeiro, Arthur's Magazine ou First for Women?”* , a recuperação agente divide isso em subconsultas separadas, como *“Quando foi fundada a Arthur's* Magazine?” e *“Quando foi fundada a First for Women?”* , recupera os resultados de cada um e avalia se os resultados combinados são suficientes.
## Como funciona a recuperação de agentes
Quando você envia uma solicitação para a `AgenticRetrieveStream` API, ocorre o seguinte processo:
1. **Planejamento** — O modelo básico analisa sua consulta e cria um plano para decompô-la em uma ou mais subconsultas. Cada subconsulta tem como alvo um recuperador específico que você configurou. Depois que os resultados da recuperação são coletados, o modelo básico avalia se eles são suficientes para responder à consulta original. Caso contrário, ele planeja e executa iterações de recuperação adicionais, até o máximo configurado.
1. **Recuperação** — As subconsultas são executadas nos recuperadores da base de conhecimento configurados. Os resultados são coletados de cada recuperação.
1. **Expansão total do documento** — quando o modelo básico determina que o conteúdo completo de um documento é necessário (por exemplo, para resumir, verificar a integridade ou acessar seções específicas), ele chama a GetDocumentContent API para recuperar o conteúdo completo do documento.
1. **Geração de resposta** — Quando `generateResponse` definido como `true` (o padrão), o modelo básico sintetiza uma resposta em linguagem natural a partir dos resultados recuperados. A resposta é transmitida de volta para você por meio de `responseEvent` eventos.
1. **Evento de resultado** — Os resultados da recuperação desduplicada de todas as iterações, a resposta completa em linguagem natural sintetizada e as citações são devolvidas a você. Os eventos de rastreamento são transmitidos durante todo o processo para fins de observabilidade.
## Pré-requisitos
Antes de usar a recuperação agente, você deve ter o seguinte:
+ Uma base de conhecimento totalmente gerenciada do Amazon Bedrock. Atualmente, a recuperação de agentes oferece suporte somente a bases de conhecimento gerenciadas.
+ Acesso a um modelo básico no Amazon Bedrock para uso no planejamento e avaliação de consultas.
+ As permissões necessárias do IAM. Para obter mais informações, consulte [Permissões necessárias para recuperação de agentes](#kb-agentic-retrieve-permissions).
## Consulte uma base de conhecimento com recuperação agente
Para usar a recuperação agente, envie uma [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)solicitação. A resposta é um fluxo que inclui resultados de recuperação e eventos de rastreamento.
A tabela a seguir descreve os principais campos de solicitação:
**Campos obrigatórios**
| Campo | Description |
| --- | --- |
| mensagens | A consulta de entrada e o histórico da conversa. Cada mensagem contém um content campo com um text valor e um role campo (userouassistant). |
| retrievers | A base de conhecimento recupera os dados. Você pode especificar até 5 recuperadores, cada um apontando para uma base de conhecimento gerenciada por sua ID. Cada recuperador pode, opcionalmente, incluir filtros de metadados e um número máximo de resultados. |
| agêntico RetrieveConfiguration | A configuração de recuperação do agente, incluindo o modelo básico a ser usado para planejamento e avaliação de consultas e, opcionalmente, um modelo de reclassificação e a contagem máxima de iterações do agente. |
**Campos opcionais**
| Campo | Description |
| --- | --- |
| Configuração da política | Configura uma grade de proteção Amazon Bedrock para ser aplicada durante a recuperação do agente. Especifique um guardrailId guardrailVersion e. |
| Contexto do usuário | Fornece um contexto de usuário para filtragem de controle de acesso. |
| Gerar resposta | Um campo booleano que, quando definido como true (o padrão), instrui o modelo básico a gerar uma resposta em linguagem natural a partir dos resultados recuperados. A resposta é transmitida de volta como pedaços de texto e incluída no evento resultante. |
Para ver a sintaxe completa da solicitação e da resposta, consulte [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)a referência da API.
## Resposta de recuperação agente
A `AgenticRetrieveStream` resposta é um fluxo que contém os seguintes tipos de eventos:
+ **Evento resultante** (`AgenticRetrieveResultEvent`) — O evento final entregue quando o processamento é concluído. Contém os resultados da recuperação e, quando a geração de resposta está ativada, a resposta gerada. O evento resultante inclui:
+ **Resultados da recuperação** (`results`) — Os fragmentos de origem recuperados em todas as iterações. Cada resultado inclui conteúdo, identificador do recuperador de origem e metadados opcionais. Quando o mesmo fragmento é recuperado por várias subconsultas, ele aparece apenas uma vez nos resultados finais.
+ **Resposta gerada** (`generatedResponse`) — Quando `generateResponse` definido como `true` (o padrão), o evento resultante inclui um `generatedResponse` objeto contendo:
+ `answer`— O texto completo da resposta em linguagem natural sintetizado.
+ `citations`— Uma lista opcional que mapeia extensões da resposta para apoiar os resultados de recuperação. Cada citação contém:
+ `startIndex`— O deslocamento de caracteres em que a passagem citada começa dentro da `answer` string.
+ `endIndex`— O deslocamento de caracteres onde a passagem citada termina (exclusivo — o texto citado vai de `startIndex` até, mas não inclui`endIndex`).
+ `references`— Uma lista em que cada referência tem um `resultIndex` campo indexado na `results` matriz no mesmo evento de resultado, indicando qual resultado de recuperação suporta o intervalo citado.
+ **Eventos de resposta** (`AgenticRetrieveResponseEvent`) — Quando `generateResponse` definido como `true` (o padrão), os `responseEvent` eventos são transmitidos durante a geração da resposta. Cada evento contém um `text` campo com uma parte incremental da resposta sintetizada em linguagem natural.
+ **Trace events** (`AgenticRetrieveTraceEvent`) — Eventos transmitidos durante o processo de recuperação agente que fornecem visibilidade de cada etapa. Estes são os tipos de eventos de rastreamento:
+ **Planejamento** — Indica que o modelo básico está analisando a consulta e criando subconsultas. Inclui as ações planejadas e os recuperadores de alvos.
+ **Recuperação** — Indica que uma recuperação está sendo executada em uma base de conhecimento. Inclui a entrada de recuperação, a saída e quaisquer avisos ou falhas.
+ **Recuperação especulativa — Uma recuperação** inicial que é executada antes da primeira etapa de planejamento para reduzir a latência. Para uma única base de conhecimento, isso recupera os resultados usando a consulta bruta do usuário. Para várias bases de conhecimento, isso executa uma pesquisa de sondagem para ajudar a encaminhar as consultas para os recuperadores apropriados.
+ **Expansão total do documento** — indica que o agente está recuperando o conteúdo completo de um documento específico. Inclui a ID do documento, o recuperador de origem e o status (InProgress, Sucesso ou Falha).
## Permissões necessárias para recuperação de agentes
Para usar a `AgenticRetrieveStream` API, a identidade do IAM de chamada precisa ter as seguintes permissões:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "bedrock:AgenticRetrieveStream",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"bedrock:Retrieve",
"bedrock:GetDocumentContent"
],
"Resource": "arn:aws:bedrock:{{region}}:{{account-id}}:knowledge-base/*"
},
{
"Effect": "Allow",
"Action": "bedrock:InvokeModelWithResponseStream",
"Resource": "*"
}
]
}
```
Se você usa grades de proteção com recuperação agente, adicione as seguintes permissões:
```
{
"Effect": "Allow",
"Action": [
"bedrock:GetGuardrail",
"bedrock:ApplyGuardrail"
],
"Resource": "*"
}
```
## Considerações
Lembre-se do seguinte ao usar a recuperação agente:
+ A recuperação por agentes só oferece suporte às bases de conhecimento gerenciadas do Amazon Bedrock.
+ Para cotas de recuperadores por solicitação, resultados por chamada de recuperação e número máximo de iterações de agentes, consulte. [Cotas de serviço para bases de conhecimento gerenciadas](kb-managed-quotas.md)
+ Reduzir a contagem máxima de iterações pode fazer com que o agente pare mais cedo, potencialmente reduzindo a precisão de consultas complexas.
+ Ao configurar grades de proteção, somente a `BLOCK` ação é suportada. A `MASK` ação não é compatível com a recuperação de agentes.
+ O cliente fornece e possui o modelo básico, o modelo de incorporação e o modelo de reclassificação usados durante a recuperação do agente, se fornecido. Suas credenciais do IAM são usadas para invocar esses modelos.