Bedrock Agents — orquestração multi-step
- ⬜📚 Bedrock Knowledge Bases — RAG gerenciado(AWS AI Practitioner (AIF-C01))
Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.
Um modelo sozinho só sabe escrever texto. Perguntado "cancele meu pedido", ele produz uma frase educada sobre cancelamento — e não cancela nada. Agent é a peça que fecha essa distância: dá ao modelo ferramentas que executam ação, e um laço que decide qual chamar, com qual argumento, e quando parar.
O que muda de RAG para Agent, em uma frase: RAG deixa o modelo saber mais; Agent deixa o modelo fazer. As duas coisas se combinam — um agent normalmente tem uma knowledge base entre as ferramentas dele.
As quatro peças de um Bedrock Agent
O exame não pede código de agent. Pede que você reconheça qual peça resolve o requisito descrito.
| Peça | O que é | Onde entra na questão |
|---|---|---|
| Instruction | O papel do agent em linguagem natural: quem ele é, o que pode e não pode fazer | "O assistente precisa recusar pedidos fora do escopo" — parte é instruction, parte é Guardrails |
| Action group | As ferramentas. Cada uma é uma função Lambda (ou um esquema de API) com parâmetros descritos | "Precisa consultar o estoque no sistema legado" — action group com Lambda |
| Knowledge base | A base de RAG anexada ao agent, para consultar documento | "Precisa responder pela política escrita" — knowledge base, não action group |
| Orchestration | O laço: o modelo decide a próxima ação, lê o resultado, decide de novo, até responder | "Precisa combinar duas consultas antes de responder" — é isso que o laço faz sozinho |
A descrição É a interface
A descrição de cada action group não é documentação: é o que o modelo lê para decidir se aquela ferramenta serve. Ferramenta com descrição vaga é ferramenta que o agent chama na hora errada — ou nunca chama. Na prática, escrever a descrição é escrever prompt.
O laço, passo a passo
Este é o desenho que vale decorar, porque quase toda questão de agent é uma pergunta sobre um ponto específico dele.
- → pedido
- → filtra entrada
- → contexto + ferramentas
- → chamar cancelaPedido(4821)
- → invoca
- → API interna
- → resultado
- → consulta política
- → registra passo
- → resposta final
- Fora da AWS
- IA e machine learning
- Gestão e governança
- Compute
O laço não é seu código: o agent decide, chama, lê o resultado e decide de novo, até concluir. Você fornece as ferramentas e a instrução. Onde isso dá errado é sempre num dos pontos numerados abaixo.
- Quem decide qual ferramenta usar é o modelo. Você não escreve "se o usuário pedir cancelamento, chame cancelaPedido". O modelo lê a descrição de cada ferramenta e escolhe. É poderoso e é a origem do comportamento imprevisível que assusta em produção.
- A ação real mora na sua Lambda. O agent não tem acesso ao seu sistema — ele invoca a Lambda, e a Lambda faz a chamada. Toda a autorização de verdade fica ali: é no código da Lambda que se valida se aquele usuário pode cancelar aquele pedido.
- O resultado volta para o modelo, não para o usuário. A Lambda devolve dado estruturado ao agent, que o entrega ao modelo como novo contexto. O modelo então decide: já dá para responder, ou preciso chamar outra ferramenta?
- Knowledge base é só mais uma fonte no laço. O agent consulta a base quando a pergunta pede documento. Por isso "responder pela política E cancelar o pedido" é um único agent, não dois sistemas.
- O trace é o que torna o agent operável. Cada decisão fica registrada: qual ferramenta, com que argumento, que resultado. Sem ler o trace é impossível depurar — o comportamento não está no seu código, está na decisão do modelo.
O código que você realmente escreve
Do lado do agent, quase nada. Do lado da ferramenta, uma Lambda que recebe o nome da ação e os parâmetros, e devolve num formato que o agent entende.
def lambda_handler(event, context):
acao = event["actionGroup"]
funcao = event["function"]
params = {p["name"]: p["value"] for p in event.get("parameters", [])}
if funcao == "cancelaPedido":
pedido_id = params["pedidoId"]
# A AUTORIZAÇÃO É AQUI. O agent decidiu chamar esta função porque o
# modelo julgou apropriado — isso não é permissão. Quem garante que o
# usuário pode cancelar ESTE pedido é este código.
if not usuario_pode_cancelar(event["sessionAttributes"]["userId"], pedido_id):
corpo = {"erro": "sem permissão para cancelar este pedido"}
else:
corpo = cancelar_no_erp(pedido_id)
else:
corpo = {"erro": f"função desconhecida: {funcao}"}
return {
"response": {
"actionGroup": acao,
"function": funcao,
# O agent entrega isto ao modelo como contexto do próximo passo.
"functionResponse": {"responseBody": {"TEXT": {"body": str(corpo)}}},
}
}O erro de segurança mais comum em agents
Nunca trate a decisão do agent como autorização. O modelo escolheu a ferramenta porque pareceu adequado ao pedido — isso é intenção, não permissão. Se a sua Lambda cancela qualquer pedido cujo id chegue no parâmetro, um prompt bem construído cancela o pedido de outra pessoa. A verificação tem que estar no código da ferramenta.
Uma operadora quer um assistente que, a partir de uma mensagem de texto do cliente, consulte o plano contratado no sistema interno, verifique a política de upgrade nos documentos da empresa e execute a mudança de plano. A sequência de passos varia conforme o caso. Qual arquitetura no Bedrock atende?
Quando NÃO usar agent
O exame gosta de cenários em que agent é tecnicamente possível e errado. A pista é sempre determinismo.
| Cenário | Escolha certa | Por quê |
|---|---|---|
| Fluxo com passos fixos e conhecidos | Step Functions | Se você já sabe a ordem, deixar o modelo decidir adiciona custo, latência e variabilidade sem ganho |
| Uma pergunta, uma consulta a documento | Knowledge base direta | Não precisa de laço. RetrieveAndGenerate resolve numa chamada |
| Precisa de garantia de execução exata | Código comum | O agent pode escolher não chamar a ferramenta. Onde "sempre acontece" é requisito, não delegue a decisão |
| Muitos passos, mas com ramificação por regra de negócio | Step Functions chamando o modelo em pontos específicos | Determinismo onde há regra, modelo onde há ambiguidade |
📋 Um time precisa automatizar "cliente pede reembolso": conferir a política, checar a data da compra, calcular o valor proporcional e lançar o estorno. Os quatro passos são sempre os mesmos, nessa ordem, e auditoria exige que todos aconteçam.
Os passos são fixos e a execução completa é requisito de auditoria — isso é a definição de workflow, não de agent. Step Functions garante que os quatro estados rodem, com retry e histórico auditável. O modelo entra num estado específico, por exemplo para interpretar o texto livre do pedido do cliente, onde a ambiguidade é real.
Alt: Bedrock Agent com quatro action groups — Funciona na demonstração e é frágil onde importa: o agent pode decidir que já tem informação suficiente e pular a checagem de data. "Normalmente chama" não passa em auditoria.
Alt: Uma Lambda monolítica com a lógica toda — Determinístico e auditável, mas perde a interpretação de texto livre e joga fora o retry e o histórico que o Step Functions dá de graça.
Alt: Agent com instrução detalhada exigindo os quatro passos — Instrução é influência, não garantia. Colocar em prompt uma regra que precisa ser determinística é o erro de desenho que o exame cobra.
Perguntas frequentes
❓ Como um Bedrock Agent executa ação?
❓ Quando usar Bedrock Agents em vez de escrever o laço?
❓ Como depurar um agente do Bedrock que decide errado?
Fixando
Numa auditoria de segurança, descobre-se que a Lambda do action group `cancelaPedido` cancela qualquer pedido cujo id receba, e que um usuário conseguiu cancelar o pedido de outro cliente conversando com o assistente. Qual é a correção correta?
O time relata que o agent "às vezes não chama a ferramenta de consulta de estoque e responde de cabeça". Qual investigação tem mais chance de achar a causa?
Próximo passo
Você já viu o modelo saber (RAG) e fazer (agents). O próximo módulo é sobre como pedir: prompt engineering aplicado, com as técnicas que o exame nomeia. É aif-prompt-engineering.
Terminou de ler?
Marcar como concluído registra o XP, mantém sua sequência e coloca 3 cartas deste módulo na fila de revisão espaçada.
Próximos passos sugeridos
Temas deste módulo
Discussão
Carregando comentários…