Agno: criando agentes e sistemas multiagente

Criando seu primeiro agente com Agno - Apresentação do Curso

Apresentando o curso e o instrutor

Olá! Bem-vindas e bem-vindos ao nosso curso Criando Agente GA com Agno. Meu nome é Fábio Contreira, sou arquiteto de soluções de IA.

Audiodescrição: Sou um homem de pele morena, de cabelo castanho curto. Estou usando uma camiseta preta e óculos de armação preta. Ao fundo, há iluminação em tons de azul e roxo. Tenho uma barba curta de alguns dias.

Apresentando o problema e os objetivos do curso

Neste curso, construiremos desde o zero um sistema multiagente usando o framework (estrutura) Agno. Se você já tentou usar IA em um contexto real, provavelmente se deparou com uma situação em que o modelo responde bem, mas o sistema não se sustenta. Falta organização, falta controle e falta uma forma clara de dividir responsabilidades.

É exatamente esse tipo de problema que este curso buscará resolver. A ideia aqui não é apresentar um agente isolado. Nós vamos estruturar um sistema em que diferentes agentes colaborem, utilizem ferramentas, tomem decisões e produzam saídas consistentes a partir de fluxos de trabalho e critérios de decisão que definiremos aqui.

Contextualizando o caso prático Scout AIFC

Trabalharemos sobre um caso prático, o Scout AIFC, uma plataforma de inteligência artificial orientada à análise da seleção brasileira masculina de futebol.

Esse é um caso hipotético com o qual trabalharemos definindo agentes e tarefas necessárias para a pessoa usuária — seja pessoa torcedora, pessoa analista, pessoa técnica ou qualquer pessoa relacionada ao futebol.

Estruturando as etapas do curso

Ao longo do curso, evoluiremos esse sistema por etapas:

• Primeiro, criaremos um agente funcional.
• Em seguida, conectaremos esse agente a ferramentas e fontes externas.
• Depois, organizaremos múltiplos agentes com papéis bem definidos.
• Na sequência, estruturaremos fluxos de trabalho, workflows (fluxos de trabalho), com saídas organizadas.
• Por fim, levaremos tudo para um formato o mais próximo possível do de produção, considerando execução contínua e governança.

Definindo objetivos e atividades práticas

Nosso objetivo é que você leve um padrão claro de construção que permita aplicar esse modelo em outros contextos, como análise de documentos, automação de processos, suporte à tomada de decisões, atendimento ao cliente e similares.

O curso também inclui atividades práticas ao longo das aulas; na implementação, aparecerão os pontos críticos da arquitetura.

Encerrando a introdução e iniciando o curso

Estou muito entusiasmado e muito feliz de estar aqui.

Vamos começar.

Criando seu primeiro agente com Agno - Por que usar Agno

Apresentando a aula e agentes de ia

Olá.

Na aula anterior, apresentamos uma introdução geral e descrevemos o que vamos construir ao longo deste curso, ao longo das lições, e quais temas vamos tratar. Partiremos da premissa de que você já sabe o que é um agente de IA: basicamente, um sistema que combina um modelo de linguagem com instruções, ferramentas, memória e a capacidade de decidir o que fazer a partir de uma entrada.

Posicionando o agno no ecossistema

Vamos então a uma pergunta que ouvimos com frequência, pois temos desenvolvido algumas aplicações usando Agno: por que usar Agno e por que construir agentes de IA com Agno? Antes disso, vamos posicionar o Agno entre as outras opções disponíveis no mercado.

• Desenvolvimento com código “manual”: consiste em criar a própria estrutura para agentes de IA. Muitas empresas fazem isso, desenvolvendo seu próprio arcabouço. Porém, isso exige estratégia, conhecimento do time disponível e gestão do tempo, pois é possível chamar diretamente as interfaces de programação de aplicações (APIs) da OpenAI, da Anthropic e da Google e construir a sua estrutura. No entanto, isso implica reinventar componentes como ferramentas de análise sintática, mecanismos de novas tentativas e observabilidade, o que pode custar tempo. A escolha está relacionada ao objetivo e à estratégia da empresa.

• LangChain e LangGraph: formam hoje o ecossistema mais popular. Porém, introduzem conceitos que precisamos entender e que tornam a curva de aprendizagem mais lenta, como estado, arestas, fluxo e o próprio conceito de grafos. Oferecem controle total, mas é necessário dominar esses conceitos.

• LlamaIndex: é uma estrutura muito utilizada em aplicações RAG (geração aumentada por recuperação), quando precisamos recuperar informações a partir de documentos.

• CrewAI e AutoGen: são estruturas voltadas para sistemas multiagente, mas apresentam limitações em organização e colaboração entre equipes.

• Agno.

Detalhando capacidades e princípios do agno

Quais são as principais capacidades e princípios do Agno?

• Suporte multimodelo: oferece suporte nativo a diversos modelos de IA, de diferentes provedores, permitindo alternar facilmente de um provedor para outro alterando apenas um parâmetro. Como modelos são frequentemente descontinuados ou atualizados, trocar o modelo na aplicação se torna simples, o que é uma grande vantagem do Agno.

• Multimodalidade nativa: processa diversos tipos de dados — texto, imagem, vídeo e áudio — o que facilita bastante o desenvolvimento.

• Desempenho: possibilita instanciação rápida de agentes, na ordem de microssegundos, com baixo consumo de memória. Em aplicações maiores, nas quais vários agentes colaboram simultaneamente, isso contribui para menor latência e menos bloqueios no sistema.

• Simplicidade: o Agno é muito pythônico e simples no código. Podemos criar e instanciar um agente funcional e útil em menos de 10 linhas, além de ser fácil de entender.

Essas quatro capacidades são especialmente interessantes para quem está desenvolvendo, começando, tem tempo limitado ou deseja entender mais sobre IA. Vale a pena experimentá-las.

Apresentando os blocos funcionais dos agentes

Tornando isso mais concreto, o Agno possui vários blocos funcionais que compõem os agentes. Listamos diversos aqui; não vamos tratar todos neste momento, mas ao longo do curso veremos cada um deles:

• modelos
• instruções
• ferramentas
• raciocínio
• memória
• armazenamento
• conhecimento
• equipes
• fluxos de trabalho
• Engine.js

Abordando modelos e instruções

Hoje vamos abordar dois deles: modelos e instruções. Como mencionamos anteriormente, o suporte multimodelo permite configurar e alternar entre vários provedores de IA de forma pronta para uso. O Agno já funciona de forma nativa com o provedor OpenAI.

Se não deixarmos claro na descrição do agente qual modelo será utilizado, por padrão ele usará OpenAI.

Quanto às instruções, podemos definir identidade e comportamento. Podemos nomear o agente, o que é útil quando esses agentes colaboram em equipe, e também fornecer uma descrição para o agente. Isso será útil quando estiver em um workflow (fluxo de trabalho) e houver necessidade de delegar tarefas entre agentes. Além disso, podemos incluir instruções como em qualquer outra descrição de agente e habilitar blocos e parâmetros específicos. Um parâmetro especialmente relevante é ativar ou não a opção de Markdown (formatação de marcação), que permite criar listas e saídas formatadas. No Agno, esses pontos são importantes e os abordaremos nesta primeira aula.

Incorporando desenvolvimento assistido por ia

Consideramos valioso incorporar desenvolvimento assistido por IA no ciclo de criação de agentes com Agno. Podemos utilizar ferramentas como Cloud Code, Codex, GitHub Copilot, Cursor e Windsurf. Como sugestão, organizamos como essas ferramentas podem ajudar em duas frentes:

• Construção

  • Gerar um boilerplate (modelo base) inicial e um padrão de projeto estruturado, com um diretório contendo "agents", "tools" e "workflows", além das partes de configuração do projeto.
  • Criar "tools" personalizadas. Neste curso, trabalharemos com um problema relacionado ao futebol. Como exemplo, poderemos criar uma ferramenta que consulte uma API de futebol e retorne o placar de uma partida recente, entre outras possibilidades.

• Qualidade

  • Realizar debug (depuração) do fluxo agêntico: coletar o log (registro), identificar um possível loop (laço) e sugerir ajustes no prompt (instrução) ou em qualquer outra parte.
  • Fazer testes de prompt. Em um agente de RAG (recuperação aumentada por geração), por exemplo, podemos definir 10 perguntas que o agente deve rejeitar e 10 perguntas que deve responder.
  • Ao final, obter um agente Agno funcional, estruturado, testado e depurado.

Nós vamos utilizar bastante essas abordagens ao longo do curso, especialmente Cloud Code. Recomendamos começar a experimentá-las, pois isso acelerará nosso desenvolvimento.

Consultando recursos oficiais do agno

Quanto às páginas oficiais do Agno:

• Em agno.com, é possível ver como o ecossistema Agno está estruturado, incluindo opções para contratação de serviços do Agno.
• A documentação está em docs.agno.com.
• Há também o repositório do Agno no GitHub, no qual é possível contribuir e explorar o projeto de open source (código aberto).

Ao acessar docs.agno.com, a documentação do Agno é uma excelente fonte de estudo. Em especial, na seção de SDK (kit de desenvolvimento de software) encontramos exemplos que vão:

• Do básico: agentes, teams (equipes), workflows (fluxos de trabalho), input/output (entrada e saída), database (banco de dados) e memória.
• Ao avançado (voltado a produção): guardrails (barreiras de segurança), human in the loop (humano no ciclo), eval (avaliação), tracing (rastreamento) e scheduler (agendador).

Vale a pena consultar esse material, e nós o exploraremos ao longo do curso.

Estudando fluxos e exemplos práticos

Na parte básica, podemos estudar o que são agentes, entender os fluxos e como construir, executar e fazer debug de cada agente. Sempre há um exemplo prático com um código e uma explicação correspondente.

Existe também a seção de exemplos, com casos mais orientados a aplicações específicas, como agentes com ferramentas e agentes com saída estruturada. Vamos explorar esses casos ao longo do curso e realizar alguns testes práticos.

Antecipando a próxima aula

Na próxima aula, vamos criar nosso primeiro agente com Agno. Teremos um exemplo que vai de um agente simples, que utiliza apenas LLM (modelo de linguagem grande), até um agente com instruções e com algumas opções de Markdown (formatação de marcação).

Até a próxima aula e até o próximo vídeo.

Criando seu primeiro agente com Agno - Construindo seu primeiro agente

Apresentando os objetivos e passos da aula

Na aula anterior, discutimos por que usar Agno e por que construir um agente de IA utilizando Agno em comparação com as opções disponíveis no mercado. Neste vídeo, vamos explorar como construir, de fato, um agente de IA. Vamos criar nosso primeiro agente e seguir cinco passos curtos para isso.

• Primeiro, vamos criar um agente com o mínimo absoluto, isto é, um agente sem nenhuma configuração.
• Em seguida, vamos declarar explicitamente um modelo dentro de um agente.
• Depois, vamos dar identidade a um agente.
• Na sequência, vamos atribuir um comportamento ao agente por meio de instruções.
• Por fim, vamos criar um agente funcional e realizar alguns testes.

Contextualizando o caso ScoutAI FC

Para isso, usaremos o caso do curso, que é o ScoutAI FC, uma plataforma que ajuda pessoas entusiastas, pessoas analistas e comissões técnicas a tomar decisões sobre a Seleção Masculina de Futebol do Brasil usando IA. A plataforma tem como principais entregas respostas para dúvidas sobre a Seleção, análises de dados de partidas e recomendação de escalação. Nos bastidores, trabalharemos com agentes atuando em equipe, orquestração em workflows (fluxos de trabalho) e gestão em produção.

Instalando dependências e configurando chaves

Para começar, vamos instalar os pacotes necessários. Instalaremos Agno, que é nosso framework (estrutura) de IA, o pacote da OpenAI e o pacote da Anthropic usando o comando pip install. É um processo rápido.

Para fazer isso no Colab, execute:

!pip install -q agno openai anthropic

Depois de instalar, vamos às plataformas da OpenAI e da Anthropic, realizar o cadastro e gerar uma chave de API para cada uma.

No Google Colab, nesta ferramenta que estamos usando, podemos abrir a seção em que configuramos Secrets (segredos), representada pelo ícone de chave no menu lateral, e salvar as chaves. Basta definir um nome para cada chave, informar seu valor e conceder acesso ao notebook. Aqui temos as duas chaves, da Anthropic e da OpenAI. Temos também a da Tavily, que usaremos depois. Há um trecho de código fornecido para acessarmos essas chaves: implementamos esse código, lemos as chaves de Secrets do Colab e as definimos como variáveis de ambiente. Aqui estamos lendo as chaves da OpenAI e da Anthropic.

Você pode usar o seguinte código para carregar os Secrets no ambiente:

import os
from google.colab import userdata

# Lê as chaves dos Secrets do Colab e seta como variáveis de ambiente.
os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")
os.environ["ANTHROPIC_API_KEY"] = userdata.get("ANTHROPIC_API_KEY")

Reforçando: em projetos locais, usamos o arquivo .env junto com o pacote python-dotenv. Em produção, usamos o gerenciador de credenciais da nuvem, e nunca expomos a chave diretamente no código.

Criando o agente mínimo

No primeiro passo, vamos criar um agente com o mínimo absoluto. Vamos importar a classe Agent e instanciá-la como um agente mínimo. Teremos esse objeto sem model, sem name e sem instructions. Ele simplesmente executará uma LLM (Modelo de Linguagem Grande) que, no Agno, por padrão, é um modelo da OpenAI. Em seguida, passaremos uma pergunta em uma frase: “O que é a Seleção Brasileira de Futebol?” e vamos imprimir o conteúdo da resposta.

Para isso, rode:

from agno.agent import Agent

# Sem modelo, sem nome, sem instructions.
agente_minimo = Agent()

resposta = agente_minimo.run("Em uma frase: o que é a seleção brasileira de futebol")
print(resposta.content)

Veremos que a resposta é adequada, explicando que a Seleção Brasileira de Futebol é a equipe nacional que representa o Brasil em competições internacionais organizadas pela CBF. Perfeito, funcionou.

Declarando explicitamente o modelo do agente

No passo dois, vamos declarar explicitamente o modelo para esse agente. Isso ajuda bastante no controle de custos e no controle de qual atividade cada agente vai executar, isto é, de qual modelo cada agente precisa, entre outros pontos. Vamos instanciar a classe OpenAIChat, atribuir o resultado a uma variável de modelo e, em seguida, passá-la ao agente por meio do parâmetro model.

Criando e testando o agente com OpenAI:

from agno.agent import Agent
from agno.models.openai import OpenAIChat

modelo_openai = OpenAIChat(id="gpt-5.4-mini")

treinador_openai = Agent(
    model= modelo_openai,
)

print(treinador_openai.run("Em uma frase: o que é a Seleção Brasileira de futebol?").content)

Faremos a mesma pergunta e imprimiremos em duas versões: na versão com OpenAI e na versão com Claude (Anthropic).

Aqui está a versão com Claude:

from agno.agent import Agent
from agno.models.anthropic import Claude

modelo_claude = Claude(id="claude-sonnet-4-0")

treinador_claude = Agent(
    model= modelo_claude,
)

print(treinador_claude.run("Em uma frase: o que é a Seleção Brasileira de futebol?").content)

As respostas serão muito semelhantes, pois é uma pergunta presente na base de treinamento de ambos os modelos, um conhecimento geral. Declarar explicitamente o modelo é fundamental para termos controle de custo e de qual modelo será utilizado.

Definindo identidade do agente

No passo três, vamos adicionar algo a mais: dar identidade ao agente. Vamos declarar o modelo, como fizemos anteriormente, e agora atribuir um nome a esse agente — neste caso, um agente treinador — e passar uma descrição. A descrição será: “É um assistente conversacional do ScoutAI FC; responde dúvidas combinando conhecimento técnico com linguagem clara.” Isso será muito importante quando tivermos vários agentes trabalhando em equipe.

Podemos montar assim:

from agno.agent import Agent
from agno.models.openai import OpenAIChat

modelo_openai = OpenAIChat(id="gpt-5.4-mini")

treinador = Agent(
    name="Treinador",
    description="""
    Assistente conversacional do ScoutAI FC. 
    Responde dúvidas sobre a Seleção brasileira masculina de futebol para torcedores, analistas e comissões técnicas,
    "combinando conhecimento técnico com linguagem clara."
    """,
    model= modelo_openai,
)

Em seguida, vamos imprimir o nome do agente, o modelo que está utilizando e sua descrição. Isso nos ajuda a inspecionar rapidamente a configuração.

print(f"Nome: \t\t{treinador.name}")
print(f"Modelo: \t{treinador.model.id}")
print(f"Descrição: \t{treinador.description[:50]}...")

Aqui, definimos o nome do treinador, o modelo que está sendo utilizado, a versão e a descrição.

Moldando o comportamento com instruções

No Passo 4, moldaremos o comportamento desse agente utilizando instruções. Ele já tem nome, descrição e modelo; agora daremos as instruções, divididas em partes para facilitar.

• Primeiro, definiremos quem é o agente. Diremos: você é o treinador, assistente do ScoutAI FC, uma plataforma; sua especialidade é a Seleção; seu público são pessoas torcedoras, pessoas analistas e comissões técnicas.
• Em seguida, definiremos o tom de voz, isto é, como se expressará. Será um tom profissional, direto, analítico, apaixonado pela Seleção, mas nunca caricaturesco nem presunçoso.
• Passaremos as restrições, uma parte muito importante, isto é, o que não faz e o que não deve fazer. Nunca inventar convocações e escalações. Quando não houver um dado específico, deixar isso claro e oferecer uma análise possível com o que já se sabe. Manter imparcialidade entre ídolos e jogadores. Neste caso, essas diretrizes são bastante específicas para esta aplicação.
• Definiremos o formato de resposta. Responder em até três parágrafos curtos, sempre em português do Brasil.
• Indicaremos o comportamento de borda, isto é, como o agente reagirá fora do escopo. Se a pergunta for sobre futebol, mas fora do escopo da Seleção, redirecionará com elegância para um domínio da plataforma. Se a pergunta sair completamente do futebol, redirecionará com bom humor de volta para a Seleção. Essa parte de restrições e comportamento é bastante importante quando temos agentes em produção.
• Ativaremos a flag markdown, que permitirá renderizar listas e negrito. Isso proporcionará uma saída formatada mais bonita, adequada para chat (conversa) e para Jupyter.

Vamos configurar tudo isso diretamente no agente:

modelo_openai = OpenAIChat(id="gpt-5.4-mini")

treinador = Agent(
    name="Treinador",
    description="""
    Assistente conversacional do ScoutAI FC. 
    Responde dúvidas sobre a Seleção brasileira masculina de futebol para torcedores, analistas e comissões técnicas,
    "combinando conhecimento técnico com linguagem clara."
    """,
    model= modelo_openai,
    instructions="""
    # Papel - Quem o agente é
    "Você é o Treinador, assistente do ScoutAI FC - uma plataforma de IA dedicada à Seleção brasileira masculina de futebol.",
    "Sua especialidade é a Seleção: história, conquistas, jogadores, técnicos, táticas e cultura ao redor do time.",
    "Seu público são torcedores, analistas e comissões técnicas. Adapte o nível técnico ao tipo de pergunta.",
    
    # Tom - como ele se expressa
    "Tom profissional, direto e analítico. Apaixonado pela Seleção, mas nunca caricato nem ufanista.",

    # Restrições - O que ele não faz
    "NUNCA invente convocações, escalações, resultados ou estatísticas que você não conhece com certeza.",
    "Quando não tiver um dado específico (especialmente sobre eventos recentes), diga claramente - e ofereça a análise possível com o que sabe.",
    "Mantenha imparcialidade entre eras e jogadores: evite eleger 'o melhor de todos os tempos' como verdade absoluta.",

    # Formato - como a saída deve ser estruturada
    "Responda em até 3 parágrafos curtos. Sempre em português do Brasil.",

    # comportamento de borda - como o agente reage fora do escopo
    "Se a pergunta for sobre futebol mas fora do escopo da Seleção (clubes, ligas estrangeiras), redirecione com elegância para o domínio da plataforma.",
    "Se a pergunta sair completamente do futebol, redirecione com bom humor para a Seleção.",
    """,
    markdown=True, # Renderiza listas, negrito, etc. - bom para chat e jupyter
)

Vamos imprimir o nome do agente, que é treinador, e as regras. As regras estão definidas em linhas separadas. Será indicado que há dez instruções definidas. Isso é muito útil quando precisamos versionar e evoluir os prompts (instruções) e o comportamento desse agente. É importante modificar linha por linha durante os testes; por isso é interessante descrever as instruções dessa forma.

print(f"Agente: {treinador.name}")
print(f"Regras: {len(treinador.instructions)} instructions definidas")

Testando o agente criado

No Passo 5, testaremos o agente que criamos. A primeira será uma pergunta de uma pessoa torcedora curiosa, para validar as regras implementadas: por que a Copa de 1970 é considerada o ápice da Seleção Brasileira? Ele responderá por que é assim, pois isso está na sua base de treinamento.

# Teste 1 - torcedor curioso
print(">>> Perfil 1: Torcedor")
print(treinador.run("Por que a copa de 1970 é considerada o auge da Seleção Brasileira?").content)

Na segunda, será uma pessoa analista pedindo um dado em tempo real. Como é um dado em tempo real, a resposta será diferente: quem foi convocado para a última lista da Seleção e como foi o último jogo? O agente dirá que não pode afirmar com segurança, que não tem dados em tempo real, entre outros esclarecimentos.

# Teste 2 - analista pedindo dado em tempo real
print(">>> Perfil 2: Analista")
print(treinador.run("Quem foi convocado pra última lista da Seleção e como foi o último jogo?").content)

Na terceira, faremos uma pergunta fora do escopo da Seleção: quem é o melhor zagueiro do Real Madrid hoje? O agente responderá que não pode determinar quem é o melhor e tentará redirecionar com elegância para o escopo da Seleção, conforme estabelecido nas instruções.

# Teste 3 - pergunta fora do escopo da Seleção
print(">>> Perfil 3: Fora do escopo")
print(treinador.run("Qual o melhor zagueiro do Real Madrid hoje?").content)

Concluindo e antecipando próximos passos

Consideramos que o resultado ficou muito bom e que é um bom ponto de partida. Conseguimos criar um agente mínimo: inicialmente, sem regras; depois, declaramos explicitamente o modelo nas versões da OpenAI e de Claude (Anthropic), mas, a partir de agora, seguiremos com a OpenAI. Atribuímos uma identidade com nome e descrição, um comportamento controlado por instruções e avaliamos a capacidade de reconhecer o que realmente não sabe, isto é, quando não possui dados em tempo real ou quando precisa acessar informações fora do seu treinamento.

Nas próximas aulas, trabalharemos os aspectos que faltam. O agente projetado hoje não busca dados em tempo real, trabalha de forma isolada, não tem fluxo determinístico, não possui artefatos para produção, memória ou monitoramento. Tudo isso será abordado nas próximas aulas.

Na próxima aula, Aula 2.1, entenderemos por que os agentes precisam de tools (ferramentas). Até então.

Sobre o curso Agno: criando agentes e sistemas multiagente

O curso Agno: criando agentes e sistemas multiagente possui 169 minutos de vídeos, em um total de 43 atividades. Gostou? Conheça nossos outros cursos de IA para Dados em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Criando seu primeiro agente com Agno
• Turbinando agentes com Tools
• Times de IA: como fazer agentes trabalharem juntos
• Orquestrando agentes com workflows
• Gerenciando agentes com AgentOS