# Web grounding
<a name="web-grounding"></a>

A Ancoragem na Web permite que o Amazon Nova pesquise na web informações atuais e forneça respostas com citações. Esse recurso é útil para consultas que exigem informações atualizadas além dos dados de treinamento do modelo.

## Como funciona o Web Grounding
<a name="how-web-grounding-works"></a>

Quando o Web Grounding está habilitado para um prompt, as seguintes etapas são executadas:

1. **Configuração da solicitação**: sua aplicação envia um prompt de usuário para a API do Amazon Bedrock com nova\$1grounding habilitado como `systemTool`.

1. **Pesquisa e análise**: o modelo determina se é necessário pesquisar, realiza uma ou mais pesquisas por informações relevantes e avalia se pesquisas adicionais são necessárias para expandir sua compreensão ou se aprofundar em subtópicos específicos.

1. **Geração de resposta**: o Amazon Nova sintetiza automaticamente as informações dos resultados da pesquisa para gerar uma resposta final da API baseada em informações em tempo real, completa com citações de suas fontes.

## Como usar o Web Grounding
<a name="enable-web-grounding"></a>

Para obter exemplos completos de código que utiliza a Ancoragem na Web, consulte a seção Exemplos de código.

Para incluir a Ancoragem na Web em seus resultados, especifique o seguinte parâmetro `systemTool` em seu bloco toolConfig:

```
import boto3
from botocore.config import Config

# Create the Bedrock Runtime client with extended timeout
bedrock = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",
    config=Config(read_timeout=3600)
)

# Define the tool configuration
tool_config = {
    "tools": [{
        "systemTool": {
            "name": "nova_grounding"
        }
    }]
}

# Send the request
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=[{
        "role": "user",
        "content": [{"text": "What are the latest developments in quantum computing?"}]
    }],
    toolConfig=tool_config
)

# Extract text with interleaved citations
output_with_citations = ""
content_list = response["output"]["message"]["content"]
for content in content_list:
    if "text" in content:
        output_with_citations += content["text"]
    elif "citationsContent" in content:
        citations = content["citationsContent"]["citations"]
        for citation in citations:
            url = citation["location"]["web"]["url"]
            output_with_citations += f" [{url}]"

print(output_with_citations)
```

## Disponibilidade regional
<a name="web-grounding-availability"></a>

Atualmente, a Ancoragem na Web está disponível apenas nas regiões dos EUA e é compatível somente com os perfis CRIS dos EUA.

## Estrutura de respostas
<a name="web-grounding-response-structure"></a>

O seguinte é um exemplo de resposta. A resposta foi abreviada para ser breve:

```
{
  "output": {
    "message": {
      "content": [
        {
          "text": "Recent quantum computing developments include...",
          "citationsContent": [
            {
              "location": {
                "web": {
                  "url": "https://example.com/quantum-news",
                  "domain": "example.com"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
```

Cada citação inclui:
+ `text`: um segmento da resposta gerada pelo modelo.
+ `citationsContent`: o contêiner primário dos dados de citação relacionados a um segmento de texto.
+ `citations`: um contêiner com `citationsContent` que contém a localização de uma citação.
+ `location`: um contêiner com `citations` que contém a fonte de uma citação.
+ `web`: um contêiner com `location` que contém os detalhes da fonte da web.
+ `url`: o endereço completo da web (URL) da fonte da citação.
+ `domain`: o domínio raiz do URL da fonte.

## Segurança da ancoragem
<a name="web-grounding-safety"></a>

Seus dados nunca saem da infraestrutura AWS. As consultas geradas pelo modelo permanecem nos serviços AWS e nunca são enviadas para a internet geral. Nosso abrangente índice interno de pesquisa na web e gráficos de conhecimento priorizam fontes confiáveis e de alta qualidade e filtram conteúdo malicioso na entrada. Por fim, protegemos seu aplicativo contra injeção indireta de prompt e desinformação com a filtragem de runtime (observe que essa mitigação é limitada para idiomas que não sejam o inglês).

## Tratamento de erros
<a name="web-grounding-error-handling"></a>

Não inclua uma entrada `toolSpec` com o nome `nova_grounding`. Incluir uma ferramenta com esse nome resultará em um erro.

Veja a seguir uma lista de possíveis erros que podem ocorrer ao usar o Web Grounding:
+ `malformed_tool_use`
+ `max_tokens`
+ `malformed_model_output`

## Permissões necessárias para ferramentas integradas
<a name="permissions"></a>

Para garantir que seu perfil tenha acesso à Ancoragem na Web no Amazon Bedrock, você tem duas opções:

1. **Habilite o BedrockFullAccess em seu perfil do IAM**: se seu perfil tiver BedrockFullAccess, ela terá acesso automático à Ancoragem na Web.

1. **Adicione permissões específicas (se necessário)**: se você precisar de um controle de acesso mais granular, adicione essa política à política do IAM do seu perfil, substituindo o ID da conta pelo ID da sua Conta da AWS:

```
{
    "Statement": [ 
        { 
            "Effect": "Allow", 
            "Action": ["bedrock:InvokeTool"], 
            "Resource": ["arn:aws:bedrock::{111122223333}:system-tool/amazon.nova_grounding"] 
        } 
    ] 
}
```

A Ancoragem na Web tem a chave de condição `aws:requestedRegion` definida como “unspecified”. Se suas políticas existentes ou Políticas de Controle de Serviços (SCPs) impuserem essa condição, você poderá encontrar problemas de acesso. Atualizar a condição para permitir uma requestedRegion “não especificada” pode resolver esse problema.

**nota**  
Ao habilitar a ferramenta Web Grounding, você se torna responsável pelo seu uso, e por qualquer uso por parte de seus usuários finais, do conteúdo gerado que incorpore informações fundamentadas. Você saberá quando sua resposta incluir informações fundamentadas em citações ou links para o material de origem. Você deve reter e exibir essas citações e links no resultado que fornecer aos seus usuários finais.

**nota**  
O Web Grounding tem um custo adicional. Para obter mais informações, acesse [Preços do AWS Bedrock](https://aws.amazon.com/bedrock/pricing/).