AWS Builder Center

Builder Center

Seu primeiro agente de IA com Amazon Bedrock e Converse API

Seu primeiro agente de IA com Amazon Bedrock e Converse API

Entenda na prática como funciona o tool use: um agente em Python, sem frameworks, que decide sozinho quando chamar ferramentas externas para responder ao usuário.

Alexandre Alves

Security engineer

Por que agentes?

Um chatbot responde perguntas. Um agente decide o que fazer para responder: consulta uma API, busca um dado, executa uma ação e só então devolve a resposta. A diferença está em um recurso chamado tool use (uso de ferramentas): o modelo recebe a descrição de funções que pode chamar e escolhe quando usá-las.
Neste artigo, vamos montar um agente mínimo em Python usando a Converse API do Amazon Bedrock, sem frameworks, para entender o mecanismo por baixo dos panos.

Pré-requisitos

  • Conta AWS com acesso ao Amazon Bedrock habilitado para um modelo que suporte tool use
  • Python 3.10+ e boto3 instalado (pip install boto3)
  • Credenciais configuradas (aws configure) com permissão bedrock:InvokeModel

Como o ciclo funciona

  1. Enviamos a pergunta do usuário + a lista de ferramentas disponíveis.
  2. O modelo responde com texto ou pede para usar uma ferramenta (stopReason == "tool_use").
  3. Nosso código executa a ferramenta e devolve o resultado ao modelo.
  4. Repetimos até o modelo dar a resposta final.
O modelo nunca executa nada sozinho: quem roda a função é sempre o seu código. Isso é ótimo para segurança e controle.

O código

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import boto3

client = boto3.client("bedrock-runtime", region_name="us-east-1")
MODEL_ID = "SEU_MODEL_ID" # copie o ID do modelo no console do Bedrock

# 1. Descrição da ferramenta (o modelo lê isso para decidir quando usá-la)
tools = [{
"toolSpec": {
"name": "consultar_clima",
"description": "Retorna o clima atual de uma cidade.",
"inputSchema": {"json": {
"type": "object",
"properties": {"cidade": {"type": "string"}},
"required": ["cidade"]
}}
}
}]

# 2. Implementação real da ferramenta (aqui, um mock)
def consultar_clima(cidade):
return {"cidade": cidade, "temperatura_c": 27, "condicao": "ensolarado"}

FERRAMENTAS = {"consultar_clima": consultar_clima}

# 3. Loop do agente
def rodar_agente(pergunta):
messages = [{"role": "user", "content": [{"text": pergunta}]}]

while True:
resp = client.converse(
modelId=MODEL_ID,
messages=messages,
toolConfig={"tools": tools},
)
msg = resp["output"]["message"]
messages.append(msg)

if resp["stopReason"] != "tool_use":
return next(b["text"] for b in msg["content"] if "text" in b)

resultados = []
for bloco in msg["content"]:
if "toolUse" in bloco:
uso = bloco["toolUse"]
saida = FERRAMENTAS[uso["name"]](**uso["input"])
resultados.append({
"toolResult": {
"toolUseId": uso["toolUseId"],
"content": [{"json": saida}],
}
})
messages.append({"role": "user", "content": resultados})

print(rodar_agente("Preciso levar guarda-chuva em Recife hoje?"))

O que está acontecendo

  • toolSpec é o "contrato": nome, descrição e schema JSON dos parâmetros. Descrições claras fazem o modelo escolher melhor.
  • stopReason diz se o modelo terminou (end_turn) ou quer usar uma ferramenta (tool_use).
  • toolUseId liga cada resultado ao pedido correspondente, permitindo várias chamadas na mesma rodada.
  • O histórico messages cresce a cada volta: é a "memória de curto prazo" do agente.

Indo além

  • Ferramentas reais: troque o mock por uma chamada a uma API, uma consulta no DynamoDB ou uma função Lambda.
  • Limite de iterações: adicione um contador para evitar loops infinitos.
  • Validação: confira o input antes de executar qualquer ação com efeito colateral.
  • Observabilidade: registre cada chamada de ferramenta no CloudWatch para depurar o raciocínio do agente.
  • Gerenciado: quando o projeto crescer, vale avaliar os recursos de agentes gerenciados do próprio Bedrock.

Conclusão

Com menos de 60 linhas, temos um agente funcional que decide sozinho quando buscar informação externa. Entender esse loop de pergunta → ferramenta → resultado → resposta é a base para qualquer framework de agentes que você venha a usar depois.
E você, qual ferramenta vai dar ao seu primeiro agente? Conta nos comentários! 🚀
# amazon-bedrock# amazon-bedrock-agents# agentic-ai# agents
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article