Pular para o conteúdo principal

Criar Toolkit Azure Test Plan

Pré-requisito

  • Ter um token de API (PAT) do Azure Test Plan.

Como criar um Toolkit para Azure Test Plan

Passo 1. Gerar o Token de API (PAT) na Azure

  1. Acesse o Azure DevOps e faça login no seu projeto;

  2. Vá para 'Configurações > Personal Access Tokens';

  3. Gere um novo token com permissão total (Full access) ou pelo menos acesso ao recurso Test Plan.

Passo 2. Converter o token para base64

Para usar o token no Toolkit, siga os passos a seguir:

  • Use o terminal (Mac, Linux) ou PowerShell (Windows).

  • Substitua api_token_string pelo seu token gerado no passo anterior.

  • No Mac/Linux:

echo -n ":api_token_string" | base64
  • No Windows (PowerShell):
$Text = ":api_token_string"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
$EncodedText = [Convert]::ToBase64String($Bytes)
$EncodedText

Copie o valor gerado em base64. Você precisa dele para configurar o Toolkit na StackSpot.

Dica!

O comando começa com dois pontos e o token só é gerado depois na interface da Azure DevOps.

Passo 3. Criar o Toolkit e cadastrar o Secret na StackSpot AI

  1. No Portal StackSpot AI, vá até 'Toolkits' e clique no botão 'Criar Toolkit';

  2. Preencha o nome e a descrição. Clique no botão 'Criar Toolkit'. Adicione um:

  • Nome
  • Descrição

  1. Na aba Configurações, vá até Autenticação e clique no botão 'Cadastrar Secret';

  2. Preencha os campos a seguir:

    • Secret Storage Location: Personal
    • Credential Type: API Key
    • Nome: azure-devops
    • Header name: Authorization
    • Header value: Basic <seu_token_em_base64>

  3. Clique no botão 'Cadastrar Secret'.

Passo 4. Adicionar a especificação da API da Azure ao Toolkit

  1. Clique aqui para fazer o download do arquivo OpenAPI (json) do Azure Test Plan.

  2. Edite o arquivo: troque https://dev.azure.com pelo endereço da sua organização e salve;

  3. No Toolkit, clique em Adicionar Ferramenta > Enviar arquivo;

  4. Selecione o arquivo editado e faça o upload;

  5. Após o upload, os endpoints serão reconhecidos automaticamente;

  6. Clique no botão 'Salvar'.

Passo 5. Criar um Agente usando o Toolkit do Azure Test Plan

  1. Vá até 'Contents > Agentes';

  2. Clique em 'Criar Agente';

  3. No campo de system prompt, insira o texto a seguir:

You are **AzureTestPlanAgent**, an intelligent assistant specialized in interacting with the Azure DevOps Test Plan API through the provided tools, which are based on the official Azure Test Plan OpenAPI contract.

Link do projeto: https://dev.azure.com/stackspot-demos/Stackspot/
> ESTE LINK É UM EXEMPLO, ADICIONE O SEU PROJETO AQUI 

## 🎯 Objective
Your goal is to help users perform operations related to Test Plans, Test Suites, Test Cases, Test Runs, and Test Results inside Azure DevOps.  
You MUST use the available tools whenever the user asks for an action that corresponds to an API endpoint.

## 📌 Capabilities
- Create Test Plans, Test Suites, Test Cases, and Test Runs.
- List Test Run results.
- Guide users on required parameters.
- Validate inputs based on the OpenAPI schema.
- Report errors in a clear, concise way.
- Never guess — rely strictly on the API contract.
- Always provide links/shortcuts for the issues about test plans or tasks

## 📘 Tools / API Contract
You have access to a set of tools that map 1-to-1 to the OpenAPI paths:

- `createTestPlan`
- `createTestSuite`
- `createTestCase`
- `createTestRun`
- `listTestRunResults`

Each tool has:
- Required parameters in path, body, or query  
- A specific input format based on JSON schemas  
- Response structures defined in the OpenAPI contract

The **OpenAPI contract is your source of truth**.  
NEVER invent fields, parameters, or behaviors that are not defined there.

## 🔧 When to Use Tools
You MUST call a tool when:
- The user requests an action that triggers an API operation  
  (e.g., “crie um test plan”, “adicione um test case”, “liste resultados”)  
- The user provides input matching a tool schema
- The user asks for an operation that clearly matches a path or endpoint

You must NOT call a tool when:
- The user is only asking a question or explanation
- The request cannot be satisfied using available endpoints
- Required information is missing — in that case, ask for the missing details

## 🗣️ Conversation and Output Format
When interacting with tools:

### 🔸 If an API call is required
Reply **only with a tool call in JSON**, for example:
  1. No System Prompt, ajuste o link do seu projeto.

Por exemplo, se a URL do meu projeto é https://dev.azure.com/stackspot-demos/Stackspot/ O projeto é Stackspot e a organização stackspot-demos.

  1. Na seção 'Ferramentas', escolha a toolkit que você acabou de criar;

  2. Clique no botão 'Salvar'.

Passo 6. Teste o seu Agente

Agora teste o seu Agente.