Uso de ferramentas (chamada de função)
As ferramentas ampliam os recursos do Amazon Nova conectando o modelo a funcionalidades externas, como APIs, bancos de dados e ambientes de execução de código. O uso de ferramentas permite que o Amazon Nova acesse informações em tempo real, realize cálculos e interaja com sistemas externos.
Compreensão do fluxo de trabalho do uso de ferramentas
O uso de ferramentas com o Amazon Nova envolve três fases principais:
- Consulta do usuário e definição da ferramenta
-
Defina ferramentas fornecendo esquemas JSON que descrevam a funcionalidade e os requisitos de entrada de cada ferramenta. A configuração da ferramenta deve incluir detalhes explícitos sobre quando e como usar cada ferramenta.
- Seleção da ferramenta
-
Quando um usuário envia uma mensagem, o Amazon Nova a analisa para determinar se uma ferramenta é necessária. Essa escolha automática de ferramenta examina o contexto e decide qual ferramenta (se houver) invocar. Se o Amazon Nova identificar uma ferramenta adequada, ele retornará o nome da ferramenta e os parâmetros necessários.
Você é responsável por executar a ferramenta com base na solicitação do modelo. Isso significa que é necessário escrever o código que invoca a funcionalidade da ferramenta e processa os parâmetros de entrada fornecidos pelo modelo.
- Retorno dos resultados
-
Depois de executar a ferramenta, envie os resultados de volta para o Amazon Nova em um formato estruturado usando JSON ou uma combinação de texto e imagens. O Amazon Nova incorpora a saída da ferramenta à resposta final. Se ocorrerem erros durante a execução, indique isso na resposta da ferramenta para permitir que o Amazon Nova se ajuste adequadamente.
Criar uma ferramenta
Defina ferramentas usando uma configuração de ferramenta que inclua uma matriz de ferramentas e, opcionalmente, um parâmetro de escolha de ferramenta. Cada especificação de ferramenta deve incluir:
-
Nome: um identificador claro para a ferramenta
-
Descrição: explicação concisa da funcionalidade da ferramenta
-
Esquema de entrada: esquema JSON que define os parâmetros obrigatórios e opcionais
exemplo Exemplo de configuração de ferramenta
tool_config = { "tools": [ { "toolSpec": { "name": "calculator", "description": "A calculator tool that can execute a math equation", "inputSchema": { "json": { "type": "object", "properties": { "equation": { "type": "string", "description": "The full equation to evaluate" } }, "required": ["equation"] } } } } ] }
Práticas recomendadas para definições de ferramentas
-
Certifique-se de que o nome e a descrição transmitam explicitamente a funcionalidade exata da ferramenta; evite ferramentas que sejam muito semelhantes semanticamente
-
Inclua os principais diferenciais na descrição para ajudar o modelo a distinguir entre ferramentas similares
-
Limite os esquemas JSON a duas camadas de aninhamento para obter o melhor desempenho
-
Restrinja as entradas usando tipos de esquema (por exemplo, enum, int, float) em vez de descrever a estrutura em texto simples
-
Indique parâmetros obrigatórios vs opcionais usando a notação de esquema JSON (por exemplo, "required": ["param1", "param2"])
-
Valide seu esquema JSON usando um validador padrão antes de enviar
-
Coloque argumentos longos de string por último no esquema e evite aninhá-los
Saída estruturada com decodificação restrita
Os modelos do Amazon Nova utilizam a decodificação restrita para garantir alta confiabilidade nas saídas geradas. Essa técnica usa gramática para restringir possíveis tokens em cada etapa de geração, evitando chaves inválidas e impondo tipos de dados corretos com base no esquema definido.
exemplo Exemplo de saída estruturada
tool_config = { "tools": [ { "toolSpec": { "name": "ProductAnalysis", "description": "Analyze product information from text.", "inputSchema": { "json": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "rating": { "maximum": 5, "description": "Customer rating 1-5", "type": ["number", "null"], "minimum": 1 }, "features": { "description": "Key product features", "type": "array", "items": {"type": "string"} }, "category": { "type": "string", "description": "Product category" }, "price": { "type": "number", "description": "Price in USD" } }, "required": ["name", "category", "price", "features"] } } } } ], "toolChoice": { "tool": {"name": "ProductAnalysis"} } }
Opções de escolha de ferramentas
O Amazon Nova é compatível com três parâmetros de escolha de ferramentas:
- Ferramenta
-
A ferramenta especificada será chamada uma vez, ideal para casos de uso de saída estruturada
- Any
-
Uma das ferramentas fornecidas será chamada pelo menos uma vez, útil para cenários de seleção de API
- Auto
-
O modelo decide se deve chamar uma ferramenta e quantas ferramentas chamar (comportamento padrão)
Chamar uma ferramenta
Se o Amazon Nova decidir chamar uma ferramenta, um bloco de uso da ferramenta será retornado como parte da mensagem do assistente com stopReason definido como “tool_use”. O bloco da ferramenta contém o nome da ferramenta e suas entradas.
nota
Execute as seguintes seções de código sequencialmente (Chamando uma ferramenta → Processando chamada da ferramenta → Retornando resultados da ferramenta) em uma única sessão de Python. Para executar os exemplos novamente, reinicie sua sessão de Python.
exemplo Chamada de uma ferramenta
import boto3 import json # Create Bedrock client bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') # Complex calculation that benefits from precise computation messages = [{ "role": "user", "content": [{ "text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7" }] }] # Define tool configuration with calculator tool_config = { "tools": [{ "toolSpec": { "name": "calculator", "description": "Perform mathematical calculations", "inputSchema": { "json": { "type": "object", "properties": { "expression": { "type": "string", "description": "Mathematical expression to evaluate" } }, "required": ["expression"] } } } }] } # Invoke Model response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=messages, toolConfig=tool_config ) # Extract tool use from response tool = next( block["toolUse"] for block in response["output"]["message"]["content"] if "toolUse" in block ) print(f"Tool: {tool['name']}") print(f"Expression: {tool['input']['expression']}")
Processamento de chamadas de ferramentas
Extraia o nome e os argumentos da ferramenta da mensagem e, em seguida, invoque a ferramenta:
def calculate(expression): """Evaluate mathematical expression""" print(f"Calculating: {expression}") P = 10000 r = 0.0475 n = 4 t = 7 result = P * (1 + r/n) ** (n*t) return result stop_reason = response["stopReason"] if stop_reason == "tool_use": if tool["name"] == "calculator": result = calculate(tool["input"]["expression"])
Retornar resultados da ferramenta
Retorne os resultados da ferramenta usando o esquema ToolResultBlock:
messages.append(response["output"]["message"]) # Add the tool result messages.append({ "role": "user", "content": [{ "toolResult": { "toolUseId": tool['toolUseId'], "content": [{"json": {"result": result}}], "status": "success" } }] }) # Send the tool result to the model response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=messages, toolConfig=tool_config ) # Extract and display final response final_text = next( block["text"] for block in response["output"]["message"]["content"] if "text" in block ) print(f"\nFinal Response:\n{final_text}")
Tratamento de erros
Relate os erros ao Amazon Nova para permitir a modificação da solicitação e tente novamente:
tool_result_message = { "role": "user", "content": [ { "toolResult": { "toolUseId": tool["toolUseId"], "content": [{"text": "A validation exception occurred on field: sample.field"}], "status": "error" } } ] }
Considerações sobre segurança
-
Valide a existência de ferramentas antes de invocá-las
-
Certifique-se de que as entradas estejam formatadas corretamente
-
Verifique se as permissões apropriadas estão em vigor antes da execução da ferramenta
-
Confie nos detalhes da sessão em vez de permitir que o Amazon Nova injete informações do usuário nas chamadas de ferramentas
-
Lembre-se de que os LLMs podem gerar alucinações nas chamadas de ferramentas; sempre valide antes da execução
Ferramentas de sistema integradas
Os modelos do Amazon Nova 2.0 incluem ferramentas integradas totalmente gerenciadas que não exigem implementação personalizada. Habilite essas ferramentas com uma simples alternância na API Converse.
Interpretador de Código
O Code Interpreter permite que o Nova execute com segurança o código Python em ambientes de sandbox isolados. Essa ferramenta foi projetada para cálculos matemáticos, operações lógicas e algoritmos iterativos.
nota
O Interpretador de Código está disponível nas regiões IAD, PDX e NRT da AWS. Para garantir que suas solicitações sejam encaminhadas para uma região com suporte, use o Global CRIS. Ao usar as chaves da API do Bedrock, você precisará adicionar permissões InvokeTool manualmente às definições da política. O perfil padrão do Bedrock não permite a ação InvokeTool.
Habilite o Interpretador de Código especificando o parâmetro systemTool:
import boto3 import json bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') tool_config = { "tools": [{ "systemTool": { "name": "nova_code_interpreter" } }] } response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=[{ "role": "user", "content": [{ "text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82" }] }], toolConfig=tool_config, inferenceConfig={"maxTokens": 10000, "temperature": 0} ) # Pretty print the response for block in response["output"]["message"]["content"]: if "toolUse" in block: print("=== Tool Use ===") print(f"Tool: {block['toolUse']['name']}") print(f"Code:\n{block['toolUse']['input']['snippet']}\n") elif "toolResult" in block: print("=== Tool Result ===") result = block['toolResult']['content'][0]['json'] print(f"Output: {result['stdOut']}") if result['stdErr']: print(f"Error: {result['stdErr']}") print(f"Exit Code: {result['exitCode']}\n") elif "text" in block: print("=== Final Answer ===") print(block["text"])
O interpretador executa esse código em uma sandbox e retorna resultados em um esquema padrão:
{ "stdOut": "String", "stdErr": "String", "exitCode": "int", "isError": "boolean" }
Web grounding
A Ancoragem na Web permite que o Amazon Nova acesse informações em tempo real da internet, fornecendo respostas atualizadas e reduzindo as alucinações. Habilite especificando a ferramenta do sistema nova_grounding:
tool_config = { "tools": [{ "systemTool": {"name": "nova_grounding"} }] }
Para obter informações detalhadas sobre a Ancoragem na Web, consulte Web grounding.
Protocolo de contexto para modelos (MCP)
O protocolo de contexto para modelos (MCP) é um padrão aberto que possibilita conexões bidirecionais seguras entre suas fontes de dados e as ferramentas baseadas em IA. Em vez de escrever adaptadores personalizados para cada API ou serviço, execute um servidor MCP e permita que o Amazon Nova descubra suas ferramentas automaticamente por meio de uma ponte de cliente.
Uma vez conectado, o Amazon Nova trata essas ferramentas de MCP como qualquer outra integração externa: ele decide quando chamá-las, envia os parâmetros necessários e incorpora os resultados em sua resposta. Usar o Amazon Nova com o Strands torna essa tarefa mais simples por meio de um MCPClient integrado que gerencia automaticamente a descoberta, a conexão e o mapeamento de resultados.
