1. Introdução
Visão geral
Neste codelab, você vai aprender a usar o framework de código aberto Inspect para fazer 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, usando o Inspect SWE.
Atividades deste laboratório
Execute uma avaliação em um conjunto de habilidades do agente usando avaliações de comandos personalizadas.
Conteúdo do laboratório
- Como executar uma avaliação em relação a habilidades usando frameworks de código aberto.
- Como escrever comandos para usar como perguntas de avaliação em avaliadores 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: teste sua chave
Se você tiver acesso a uma linha de comando com curl, adicione sua chave à primeira linha do bloco a seguir e execute 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 ver uma lista de modelos no formato JSON, como models/gemini-3.1-pro-preview. Isso significa que funcionou.
Instalar as dependências do sistema
Para concluir este tutorial, instale o seguinte software na sua máquina:
- Docker
- Isso será usado para executar a avaliação em um ambiente de sandbox
- Python
- É a linguagem de programação em que o Inspect foi escrito.
- Node.js e NPM
- É a linguagem de programação em que a CLI do Gemini foi escrita.
- git
- Isso será usado para receber uma cópia do repositório de habilidades que está sendo avaliado.
3. Identifique as habilidades a serem avaliadas
As habilidades do agente são uma maneira padronizada de dar aos agentes de IA novas capacidades e conhecimentos.
Este codelab vai usar o repositório de habilidades do Google Agent (https://github.com/google/skills) como exemplo, mas você pode mudar 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 que sabemos estar 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 feita.
O repositório de habilidades do Google Agent contém uma habilidade específica para o Cloud Run. Portanto, podemos fazer a seguinte pergunta:
"Como faço para implantar um serviço no Cloud Run com o código na minha máquina local?"
A resposta para 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 Google Agent Skills 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.1-pro-preview"):
# 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 este 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 habilidade nesse repositório.
- Usar 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:
- A CLI do Gemini como solucionador
- QA do Model Grader como avaliador
- Docker como sandbox
- Gemini Pro 3.1 como 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 seguinte comando:
inspect eval skills-eval.py -T agent_skills_folder=google-skills
Na primeira vez que essa avaliação for executada, ela vai baixar contêineres do Docker e instalar dependências do Node.JS e do Python. Isso pode levar algum tempo, dependendo da sua conexão de rede. Se você executar a avaliação novamente, essa configuração será armazenada em cache.
Depois do 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 "Executando amostras" para conferir o progresso atual ou cancelar o processo.
Na próxima etapa, você vai analisar os resultados.
5. Conferir e interpretar os resultados
Quando a avaliação for concluída, você poderá conferir os resultados.
Ver resultados
A avaliação gravou um arquivo .eval na pasta logs/. Este é um arquivo binário, e não pode ser visualizado diretamente.
Para conferir os resultados da avaliação, use o visualizador de inspeção:
inspect view
Isso vai criar um servidor da Web em http://127.0.0.1:7575. Abra este URL para conferir os resultados.
Interprete os resultados
Essa avaliação usou um Model Grader, em que as seguintes notas foram atribuídas:
- "C": Complete
- A resposta estava completamente correta
- "P": parcial
- A resposta estava quase toda correta
- "I": incompleto
- A resposta estava incorreta.
Neste codelab, há uma resposta intencionalmente incorreta, que aparece como "I" (Incompleta) e reduz a acurácia geral para 0,667 (duas de três corretas).
Clique em qualquer uma das guias para ver mais informações sobre o método usado, os tokens usados e outros dados sobre a avaliação.
6. Estender a avaliação
Há várias mudanças que podem ser feitas nessa avaliação para ampliar o escopo.
Fornecer mais perguntas
Para repositórios com várias habilidades, adicione mais perguntas e respostas com base no conteúdo do repositório de habilidades. O Inspect aceita o 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 novamente a avaliação com base nas 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 pontuadores diferentes
Neste codelab, usamos o avaliador Model Graded. O Inspect oferece vários pontuadores integrados e também a opção de criar seu próprio pontuador personalizado.
Usar modelos de programação diferentes
Neste codelab, usamos o Gemini 3.1 Pro como modelo de solução. Para mudar isso, forneça o nome do modelo como um parâmetro de linha de comando, sem precisar mudar o código. É possível executar a avaliação novamente com um modelo diferente do Gemini usando o seguinte comando:
inspect eval skills-eval -T agent_skills_folder=google-skills \
-T model=google/gemini-3.1-flash-live-preview
Esse "argumento de tarefa" vai aparecer no Inspect Viewer, permitindo que você acompanhe os argumentos usados para executar a avaliação.
Avaliar diferentes habilidades
Neste codelab, usamos o repositório Google Agent Skills como as habilidades avaliadas.
Você pode avaliar diferentes repositórios de habilidades, mas as perguntas e respostas também precisam ser atualizadas para corresponder. Por exemplo, Habilidades do agente do Flutter não vai responder a perguntas específicas do Cloud Run.
7. Parabéns
Você aprendeu a executar uma avaliação em relação a habilidades usando frameworks de código aberto e a escrever comandos para usar como perguntas de avaliação em classificadores de perguntas e respostas.