Defining Rovo Tools and Actions

1. O Que São "Ações" ou "Skills"?

Um agente de IA opera em um ciclo de perceber-planejar-agir. A parte de "agir" é executada através do uso de ferramentas (tools). Uma ferramenta é uma capacidade específica e bem definida que o agente pode invocar para realizar uma tarefa. Pode ser algo simples como calcularSoma(a, b) ou algo complexo como criarPullRequest(repositorio, branchOrigem, branchDestino, titulo).

No ecossistema da Atlassian, essas ferramentas são chamadas de actions ou, mais recentemente, skills. Pense nelas como os verbos do seu agente; as ações que ele pode executar.

Para começar, vamos assistir a uma breve introdução aos componentes de um agente e ao conceito de skills.

É importante notar que a Atlassian tem atualizado a terminologia. O que antes era amplamente chamado de "action" agora é referido como "skill". Para todos os efeitos práticos, os termos são intercambiáveis neste contexto.

Para o seu projeto, você criará skills customizadas usando o Atlassian Forge, a plataforma de desenvolvimento serverless da Atlassian. Isso lhe dará total controle para implementar a lógica de que você precisa, como fazer chamadas de API para o GitHub.

2. Definindo uma Ação no Forge manifest.yml

A definição de uma ação customizada é feita no arquivo manifest.yml do seu aplicativo Forge. Este arquivo YAML declara todos os módulos e configurações do seu app, incluindo os agentes Rovo e suas ações.

A declaração de uma ação informa ao Rovo que uma nova ferramenta está disponível, como se chama, o que faz e quais informações (inputs) ela precisa para funcionar. Essa declaração é análoga a como você definiria um endpoint em uma API REST, especificando a rota, o método HTTP e os parâmetros esperados.

Para entender a estrutura, vamos usar o tutorial "Hello World" da Atlassian como nosso guia.

Agora, vamos detalhar cada propriedade da definição da ação, usando a documentação oficial como referência.

Com base nesses recursos, aqui está um resumo das propriedades mais importantes que você definirá para cada ação:

• key: Um identificador único para a ação dentro do seu manifest.yml. Ex: criar-branch-github.
• name: O nome legível por humanos que pode aparecer na interface. Ex: Criar Branch no GitHub.
• description: Esta é a propriedade mais crucial. O Rovo (que usa um LLM) lê esta descrição para decidir quando usar sua ação. Uma descrição clara, precisa e detalhada é fundamental para que o agente invoque a ferramenta corretamente. Por exemplo: "Use esta ação para criar um novo branch em um repositório GitHub a partir do branch padrão. Requer o nome do repositório e o nome do novo branch como entrada."
• function: Referência à função (definida em outra parte do manifest.yml) que aponta para o seu código de implementação (por exemplo, uma função em seu arquivo index.js).
• actionVerb: O tipo de operação que a ação realiza (GET, CREATE, UPDATE, DELETE, TRIGGER). Ajuda o Rovo a entender a natureza da ação. Para criar um branch, você usaria CREATE.
• inputs: Um objeto que define os parâmetros que sua ação precisa. Para cada input, você especifica:
  • title: O nome do parâmetro (ex: repositoryName).
  • type: O tipo de dado (string, integer, boolean).
  • required: Se o parâmetro é obrigatório.
  • description: Uma descrição do que é este parâmetro, para ajudar o LLM a extrair o valor correto da conversa com o usuário.

3. Conectando a Definição à Implementação

A definição no manifest.yml é apenas o "contrato" da sua ação. A lógica real reside em uma função JavaScript (ou TypeScript) em seu projeto Forge. A propriedade function no manifesto cria essa ponte.

Vamos ver como isso funciona no exemplo "Hello World".

A sua função de handler receberá dois argumentos principais: payload e context.

• payload: Este objeto contém os inputs que você definiu no manifesto. Os valores para esses inputs são extraídos pelo LLM da conversa do usuário.
• context: Este objeto contém informações de execução fornecidas de forma determinística pelo Forge, como o accountId do usuário que invocou a ação e informações sobre o local onde a ação foi chamada (por exemplo, detalhes de uma issue do Jira ou de uma página do Confluence).

É uma prática recomendada usar os dados do context para verificações críticas (como autorização), pois os dados no payload dependem da extração do LLM e podem, em teoria, ser "alucinados" ou incorretos.

No exemplo do messageLogger, a função recebe um payload que se parece com { "message": "alguma mensagem do usuário" } e simplesmente o imprime no console. Em seu projeto, a função criarPullRequest receberia um payload como { "repository": "meu-repo", "title": "Nova Funcionalidade" } e usaria bibliotecas como o octokit para fazer a chamada de API correspondente ao GitHub.

Conclusão

Nesta lição, estabelecemos o alicerce para dar ao nosso agente a capacidade de executar tarefas no mundo real. Aprendemos que as "ações" ou "skills" são as ferramentas que um agente Rovo usa para interagir com outros sistemas.

Principais Pontos:

• Ações (Skills) são as "mãos" do agente: Elas permitem que ele vá além da recuperação de informações e execute tarefas concretas.
• Definição no manifest.yml: Uma ação é declarada no arquivo manifest.yml do Forge, especificando suas propriedades, como key, description e inputs.
• A description é para o LLM: A propriedade description é a instrução que o Rovo usa para entender o que a ação faz e quando deve ser usada. Sua clareza é fundamental.
• Conexão com o Código: A propriedade function liga a declaração da ação a uma função JavaScript/TypeScript que contém a lógica de negócios real (por exemplo, fazer uma chamada de API).
• Payload vs. Context: A sua função de handler recebe dados extraídos pelo LLM (payload) e dados de contexto confiáveis (context), e você deve saber quando usar cada um.

Agora que entendemos como definir uma ação para interagir com uma API como a do GitHub, o próximo passo lógico é garantir que nosso agente tenha as permissões necessárias para fazer isso de forma segura.

Na Próxima Lição:

Vamos abordar a segurança e a autenticação. A próxima lição, "Configurar autenticação segura para interações automatizadas com a API do GitHub", mostrará como usar um GitHub App ou Personal Access Token para que nosso agente possa se autenticar e executar as ações que definimos.