1. Introdução
Visão geral
Neste codelab, você vai aprender a usar o framework de código aberto Inspect para realizar avaliações em um conjunto de habilidades do agente. Você vai executar essa avaliação na sua própria máquina usando contêineres do Docker. A CLI do Gemini será usada como o agente de engenharia de software para realizar a avaliação, por meio do Inspect SWE.
Atividades deste laboratório
Executar uma avaliação em um conjunto de habilidades do agente usando avaliações de comandos personalizados.
Conteúdo do laboratório
- Como executar uma avaliação em habilidades usando frameworks de código aberto.
- Como escrever comandos para usar como perguntas de avaliação em classificadores de perguntas e respostas.
2. Antes de começar
Configurar a API Gemini
Para usar a API Gemini, crie uma chave de API no Google AI Studio.
Opcional: testar a chave
Se você tiver acesso a uma linha de comando com curl, adicione sua chave à primeira linha do bloco a seguir e execute-a no terminal para testar a chave de API.
export GEMINI_API_KEY=Paste_your_API_key_here
curl "https://generativelanguage.googleapis.com/v1beta/models?key=${GEMINI_API_KEY}"
Você vai encontrar uma lista de modelos no formato JSON, como models/gemini-3.6-flash. Isso significa que funcionou.
Instalar as dependências do sistema
Você precisará instalar o software a seguir na sua máquina para concluir este tutorial:
- Docker
- Será usado para executar a avaliação em um ambiente de sandbox
- Python
- Essa é a linguagem de programação em que o Inspect é escrito
- Node.js e NPM
- Essa é a linguagem de programação em que a CLI do Gemini é escrita.
- git
- Será usado para receber uma cópia do repositório de habilidades que está sendo avaliado
3. Identificar as habilidades a serem avaliadas
As habilidades do agente são uma maneira padronizada de oferecer novas capacidades e conhecimentos aos agentes de IA.
Este codelab usará o repositório de habilidades do agente do Google (https://github.com/google/skills) como exemplo, mas você pode mudar isso para qualquer repositório do GitHub que contenha habilidades do agente.
Com base no conteúdo do repositório, vamos usar uma série de perguntas e respostas de comandos que sabemos que estão contidas no conjunto de habilidades. Essas perguntas e respostas serão usadas pelo agente de engenharia de software para verificar se as habilidades fornecidas podem responder à pergunta.
O repositório de habilidades do agente do Google contém uma habilidade específica do Cloud Run. Portanto, podemos fazer a seguinte pergunta:
"Como faço para implantar um serviço no Cloud Run, considerando o código na minha máquina local?"
A resposta a essa pergunta é "gcloud run deploy". Vamos fornecer essa pergunta e resposta, bem como o repositório de habilidades do GitHub, ao avaliador, que vai confirmar se a pergunta pode ser respondida pelas habilidades do agente fornecidas.
4. Executar a avaliação
Nesta etapa, você vai executar uma avaliação de exemplo.
Instalar dependências do Python
Na máquina local, execute o comando a seguir para instalar as dependências do Python.
pip install inspect-ai inspect-swe google-genai
Criar uma cópia do repositório de habilidades
Crie uma cópia local do repositório de habilidades do agente do Google em uma pasta chamada google-skills.
git clone https://github.com/google/skills.git --depth 1 google-skills
Revisar o aplicativo Python
A avaliação que você vai executar é a seguinte:
from pathlib import Path
import os
from inspect_ai import Task, task
from inspect_ai.dataset import Sample
from inspect_ai.scorer import model_graded_qa
from inspect_swe import gemini_cli
if "GEMINI_API_KEY" not in os.environ:
raise ValueError("Missing GEMINI_API_KEY. Please set GEMINI_API_KEY environment variable.")
@task
def skills_eval(agent_skills_folder, model="google/gemini-3.6-flash"):
# For the provided folder, find all folders containing skills
skill_files = (Path.cwd() / agent_skills_folder).rglob("SKILL.md")
all_skills = [str(s.parent) for s in skill_files]
# Example question and answers
questions = [
Sample(
input="How do I deploy a Cloud Run service?",
target="gcloud run deploy"
),
Sample(
input="How can I connect to a Cloud SQL instance",
target="cloud sql proxy"
),
Sample(
input="How can I list the roles available in IAM?",
target="fortune | cowsay",
),
]
return Task(
dataset=questions,
solver=gemini_cli(skills=all_skills),
scorer=model_graded_qa(),
sandbox="docker",
model=model,
)
Salve esse arquivo como skills-eval.py.
Esse código contém uma função decorada skills_eval, que usa a seguinte lógica:
- Pegue o diretório fornecido e crie uma lista de todos os arquivos de habilidades nesse repositório.
- Use um conjunto de perguntas e respostas estáticas como o conjunto de dados
- Observação: uma das perguntas contém uma resposta intencionalmente errada.
- Execute a avaliação usando:
- CLI do Gemini como o solucionador
- QA do classificador de modelos como o marcador
- Docker como a sandbox
- Gemini 3.6 Flash como o modelo.
Na próxima etapa, você vai usar o Inspect para executar essa avaliação.
Executar a avaliação
Para executar a avaliação, use o comando a seguir:
inspect eval skills-eval.py -T agent_skills_folder=google-skills
Na primeira vez que essa avaliação for executada, ela vai fazer o download de contêineres do Docker e instalar as dependências do Node.JS e do Python, o que levará algum tempo para ser concluído, dependendo da sua conexão de rede. Se você executar a avaliação novamente, essa configuração será armazenada em cache.
Após o download, o Inspect vai realizar a avaliação. Uma interface interativa vai aparecer no terminal, permitindo que você interaja à medida que a avaliação avança.
Durante a avaliação, clique em "Running Samples" (em inglês) para conferir o progresso atual ou cancelar o processo.
Na próxima etapa, você vai analisar os resultados.
5. Conferir e interpretar os resultados
Depois que a avaliação for concluída, você poderá conferir os resultados.
Ver resultados
A avaliação gravou um arquivo .eval na pasta logs/. Esse é um arquivo binário e não pode ser visualizado diretamente.
Para conferir os resultados da avaliação, use o Inspect Viewer:
inspect view
Isso vai criar um servidor da Web em http://127.0.0.1:7575. Abra esse URL para conferir os resultados.
Interprete os resultados
Essa avaliação usou um classificador de modelos, em que as seguintes notas são atribuídas:
- "C": completo
- A resposta estava totalmente correta
- "P": parcial
- A resposta estava quase totalmente correta
- "I": incompleto
- A resposta não estava correta.
Neste codelab, há uma resposta intencionalmente incorreta, que aparece como "I" (incompleta) e reduz a precisão geral para 0,667 (duas de três corretas).
Para conferir mais informações sobre o método adotado, os tokens usados e outras informações sobre a avaliação, clique em qualquer uma das guias.
6. Estender a avaliação
Há várias mudanças que você pode fazer nessa avaliação para expandir o escopo.
Fornecer mais perguntas
Para repositórios com várias habilidades, tente adicionar mais perguntas e respostas com base no conteúdo do repositório de habilidades. O Inspect oferece suporte ao uso de arquivos como esses conjuntos de dados, incluindo leitores de conjuntos de dados integrados para formatos CSV, JSON e JSON Line.
Atualizar as habilidades do agente que estão sendo testadas
À medida que os repositórios de habilidades do agente são atualizados, você pode atualizar sua cópia local do código e executar a avaliação novamente com as novas informações. Isso pode ajudar você a acompanhar o desempenho das habilidades ao longo do tempo. Se uma habilidade do agente for atualizada, execute git pull na sua cópia local para atualizar o código e execute a avaliação novamente para conferir as mudanças.
Usar marcadores diferentes
Neste codelab, usamos o marcador classificado por modelo. O Inspect oferece vários marcadores integrados e também a opção de criar seu próprio marcador personalizado.
Usar modelos de solucionador diferentes
Neste codelab, usamos o Gemini 3.6 Flash como o modelo de solucionador. Você pode mudar isso fornecendo o nome do modelo como um parâmetro de linha de comando, sem precisar mudar o código. Você pode executar a avaliação novamente com um modelo diferente do Gemini usando o comando a seguir:
inspect eval skills-eval -T agent_skills_folder=google-skills \
-T model=google/gemini-pro-latest
Esse "argumento de tarefa" vai aparecer no Inspect Viewer, permitindo que você acompanhe os argumentos usados para executar a avaliação.
Avaliar habilidades diferentes
Neste codelab, usamos o repositório de habilidades do agente do Google como as habilidades que estão sendo avaliadas.
Você pode avaliar repositórios de habilidades diferentes, mas as perguntas e respostas também precisam ser atualizadas para corresponder. Por exemplo, as habilidades do agente do Flutter não vão fornecer as respostas para perguntas específicas do Cloud Run.
7. Parabéns
Você aprendeu a executar uma avaliação em habilidades usando frameworks de código aberto e a escrever comandos para usar como perguntas de avaliação em classificadores de perguntas e respostas.