Building Your First Rovo Agent

1. A Anatomia de um Agente Rovo

Todo Agente Rovo, independentemente de sua complexidade, é composto por quatro módulos fundamentais. Pense neles como os traços de personalidade e as competências de um novo membro da equipe.

Resumindo, os quatro componentes são:

1. Identidade: O nome, o avatar e a descrição do agente. É como ele se apresenta.
2. Instruções: O componente mais crucial. É um prompt detalhado que define o papel, os objetivos, a personalidade e as regras de operação do agente. É aqui que você passará a maior parte do tempo, refinando o comportamento do agente.
3. Conhecimento: As fontes de informação que o agente pode consultar. Isso define o escopo do que o agente "sabe", permitindo que você o restrinja a espaços específicos do Confluence, projetos do Jira ou conectores de terceiros.
4. Habilidades (ou Ações): As ferramentas que o agente pode usar para realizar tarefas, como criar uma issue no Jira, comentar em uma página ou — crucial para o seu objetivo — executar uma lógica personalizada via Forge para interagir com APIs externas, como a do GitHub.

2. Duas Abordagens para a Criação de Agentes

A plataforma Atlassian oferece dois caminhos para criar agentes, atendendo a diferentes necessidades e níveis de complexidade.

As duas abordagens são:

• No-Code (Sem Código):

  • Realizada diretamente na interface de usuário do Atlassian, usando linguagem natural.
  • Ideal para agentes mais simples, automação de tarefas rotineiras ou para usuários que não são desenvolvedores.
  • Ótima para prototipar rapidamente o comportamento de um agente.

• With Code (Com Código usando Forge):

  • Realizada por desenvolvedores usando a plataforma Atlassian Forge.
  • Essencial para o seu objetivo, pois permite:
    • Implementar lógica de programação complexa.
    • Conectar-se a fontes de dados e APIs externas (como GitHub e seu banco de dados MariaDB).
    • Manter a lógica e os prompts detalhados de forma privada (não expostos na UI).
    • Distribuir o agente de forma controlada.

Vamos primeiro entender os conceitos usando a abordagem no-code e, em seguida, aplicá-los na prática com Forge.

3. Definindo Instruções e Escopo

A eficácia de um agente depende diretamente da qualidade de suas instruções e da clareza de seu escopo.

Escrevendo Instruções Eficazes (A Arte do Prompt)

As "instruções" de um agente são, na essência, um prompt de engenharia avançado. Dado seu background técnico, você pode pensar nisso como o "programa" principal que guia a execução do LLM.

As quatro dicas principais para escrever boas instruções são:

1. Defina o Papel e os Objetivos: Trate o agente como um novo membro da equipe. Diga a ele qual é sua função (ex: "Você é um assistente de desenvolvimento sênior especializado em C# e React") e quais são seus objetivos claros.
2. Quebre as Tarefas em Passos: Detalhe o processo que o agente deve seguir, passo a passo, como se estivesse explicando para alguém sem conhecimento prévio do contexto.
3. Dê Exemplos: Forneça exemplos concretos de bons resultados e, igualmente importante, de maus resultados a serem evitados. LLMs aprendem muito bem com exemplos (técnica conhecida como few-shot prompting). Você pode usar tabelas em Markdown ou até mesmo links para páginas do Confluence que sirvam de modelo.
4. Itere e Refine: Teste seu agente com dados reais. Quando ele falhar ou não se comportar como esperado, volte às instruções e adicione novas regras ou esclarecimentos para corrigir o comportamento. Este é um ciclo contínuo de melhoria.

Definindo o Escopo com Cenários, Conhecimento e Habilidades

Além das instruções, você define o escopo do agente controlando o que ele pode acessar e fazer.

• Cenários (Scenarios): Uma funcionalidade poderosa que permite agrupar instruções, conhecimento e habilidades para diferentes "gatilhos" ou intenções do usuário. Isso funciona como uma estrutura if-else ou switch-case, permitindo que um único agente lide com múltiplas tarefas de forma organizada, em vez de ter um prompt monolítico gigante.

• Conhecimento (Knowledge): Aqui você especifica quais fontes de dados o agente pode consultar. Você pode permitir que ele pesquise em todo o seu ambiente Atlassian ou restringi-lo a um projeto Jira e um espaço Confluence específicos. Isso é fundamental para garantir que o agente use apenas informações relevantes e autorizadas.

• Habilidades (Skills/Actions): São as ferramentas que o agente pode usar. Como vimos, elas podem ser nativas, de apps do Marketplace ou, o mais importante para nós, customizadas com Forge.

4. Na Prática: Criando um Agente com Forge

Agora, vamos ao que interessa. Para o seu projeto, você usará Forge para definir seu agente em código. A configuração principal é feita no arquivo manifest.yml.

A Atlassian fornece um tutorial "hello world" que é perfeito para nosso primeiro passo prático. Ele o guiará pela criação de um agente simples que pode registrar uma mensagem nos logs do Forge.

Para complementar o tutorial escrito, o vídeo a seguir mostra o mesmo processo de forma visual. É útil para ver os comandos em ação e o resultado na interface do Jira/Confluence.

Analisando um Exemplo Mais Avançado

O agente "hello world" é simples. Para ver como as instruções e o escopo se parecem em um caso de uso mais realista, vamos analisar o manifest.yml de um agente projetado para analisar issues do Jira.

Este exemplo mais complexo demonstra claramente:

• Instruções personalizadas: O prompt é muito mais detalhado, definindo a persona ("analista de dados experiente"), os trabalhos que pode executar e as regras para formatar a saída.
• Escopo definido: A action get-issues dá ao agente a habilidade de buscar dados no Jira, e o escopo de permissão read:jira-work garante que ele só possa fazer isso se o administrador e o usuário tiverem concedido essa permissão, garantindo a segurança.

Conclusão

Parabéns! Você passou da teoria para a prática, entendendo não apenas os componentes de um Agente Rovo, mas também como criá-lo e configurá-lo usando a abordagem Forge, que será a base para o seu projeto.

Principais Pontos:

• Um Agente Rovo é definido por sua identidade, instruções, conhecimento e habilidades.
• As instruções são o "programa" do agente, definidas por meio de um prompt detalhado que estabelece seu papel, objetivos e comportamento.
• O escopo é definido pelo conhecimento (fontes de dados acessíveis) e pelas habilidades/ações (ferramentas que ele pode usar).
• A criação de agentes via Forge é feita principalmente no arquivo manifest.yml, onde você define o prompt e as actions do agente.
• O ciclo de desenvolvimento forge create -> forge deploy -> forge install é o fluxo de trabalho padrão para colocar seu agente em funcionamento.

Na Próxima Lição:

Agora que você criou um agente básico, o próximo passo é ensiná-lo a encontrar as informações de que precisa para trabalhar. Na próxima lição, "Configurar fontes de conhecimento Rovo para indexar conteúdo de fontes externas e internas", vamos mergulhar no pilar "Find" do Rovo. Você aprenderá como conectar seu ambiente Atlassian ao Google Drive e aos seus repositórios Git, construindo a base de conhecimento que seu agente usará para entender as regras de negócio e de arquitetura.