AI Agents · Aula

Testes de agentes baseados em asserções

Verificação de chamadas de ferramentas, etapas intermediárias e estrutura da saída final.

Aula 3 de 413 etapas

Testes de agentes baseados em asserções é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Indo além da correspondência exata de texto

Como as saídas de LLM não são determinísticas, testá-las com assert response == 'exact text' é frágil. Em vez disso, escreva asserções que verifiquem a estrutura e a intenção da resposta sem depender da formulação exata.

Verificando se chamadas de ferramentas foram feitas

Para agentes que chamam funções, a asserção mais confiável é verificar se o agente escolheu chamar a ferramenta correta. Isso é estrutural — não depende da formulação exata do raciocínio do LLM.

import json
from unittest.mock import patch, MagicMock

@patch('myagent.client.chat.completions.create')
def test_agent_calls_search_tool(mock_create):
    # Mock: agent decides to call search_web
    tool_call = MagicMock()
    tool_call.function.name = 'search_web'
    tool_call.function.arguments = json.dumps({'query': 'Python tutorials'})
    mock_create.return_value = MagicMock(
        choices=[MagicMock(message=MagicMock(tool_calls=[tool_call]))]
    )

    response = mock_create()  # simulating the agent call
    tc = response.choices[0].message.tool_calls

    assert tc is not None
    assert len(tc) > 0
    assert tc[0].function.name == 'search_web'

# --- demo: give unittest.mock.patch a real dotted path to patch ---
import sys
import types

_myagent = types.ModuleType('myagent')
_myagent.client = types.SimpleNamespace(
    chat=types.SimpleNamespace(completions=types.SimpleNamespace(create=lambda *a, **k: None))
)
sys.modules['myagent'] = _myagent

test_agent_calls_search_tool()
print('test_agent_calls_search_tool: PASS')

Verificando o nome correto da ferramenta

Além de verificar se existem chamadas de ferramentas, confirme se o nome específico da ferramenta corresponde ao esperado. Isso identifica casos em que o agente escolhe a ferramenta errada para uma determinada consulta.

import json
from unittest.mock import MagicMock

def extract_tool_calls(response) -> list:
    message = response.choices[0].message
    if not message.tool_calls:
        return []
    return [
        {
            'name': tc.function.name,
            'args': json.loads(tc.function.arguments)
        }
        for tc in message.tool_calls
    ]

# In a test:
# calls = extract_tool_calls(mock_response)
# assert calls[0]['name'] == 'get_weather'
# assert calls[0]['args']['city'] == 'Paris'
print('Tool name and argument assertions are the most reliable agent tests')

Verificando os argumentos da ferramenta

Depois de verificar o nome da ferramenta, confirme se os argumentos estão corretos. O agente não deve apenas escolher a ferramenta certa, mas também preenchê-la com os parâmetros corretos da solicitação do usuário.

import json
from unittest.mock import patch, MagicMock

@patch('myagent.client.chat.completions.create')
def test_weather_tool_gets_correct_city(mock_create):
    tool_call = MagicMock()
    tool_call.function.name = 'get_weather'
    tool_call.function.arguments = json.dumps({'city': 'Tokyo', 'unit': 'celsius'})
    mock_create.return_value = MagicMock(
        choices=[MagicMock(message=MagicMock(tool_calls=[tool_call]))]
    )

    response = mock_create()
    args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)

    assert args['city'] == 'Tokyo'
    assert args.get('unit') in ['celsius', 'fahrenheit', None]  # flexible

# --- demo: give unittest.mock.patch a real dotted path to patch ---
import sys
import types

_myagent = types.ModuleType('myagent')
_myagent.client = types.SimpleNamespace(
    chat=types.SimpleNamespace(completions=types.SimpleNamespace(create=lambda *a, **k: None))
)
sys.modules['myagent'] = _myagent

test_weather_tool_gets_correct_city()
print('test_weather_tool_gets_correct_city: PASS')

Validação de esquema JSON para saídas

Quando seu agente retorna JSON estruturado, valide a saída em relação a um esquema JSON para garantir que todos os campos obrigatórios estejam presentes e tenham os tipos corretos. A biblioteca jsonschema facilita esse processo.

# pip install jsonschema
import jsonschema

AGENT_RESPONSE_SCHEMA = {
    'type': 'object',
    'required': ['answer', 'sources', 'confidence'],
    'properties': {
        'answer': {'type': 'string', 'minLength': 1},
        'sources': {
            'type': 'array',
            'items': {'type': 'string', 'format': 'uri'}
        },
        'confidence': {'type': 'number', 'minimum': 0, 'maximum': 1}
    }
}

def test_agent_output_schema(agent_output: dict):
    try:
        jsonschema.validate(instance=agent_output, schema=AGENT_RESPONSE_SCHEMA)
        print('Schema validation passed')
    except jsonschema.ValidationError as e:
        raise AssertionError(f'Invalid agent output: {e.message}')

Asserções de presença de palavras-chave

Para respostas de texto cuja formulação exata varia, verifique se os principais conceitos ou palavras aparecem na saída. Essa abordagem é flexível, mas continua significativa — a resposta do agente precisa mencionar pelo menos os termos relevantes.

def assert_keywords_present(text: str, keywords: list, require_all: bool = True):
    lower_text = text.lower()
    found = [kw.lower() in lower_text for kw in keywords]

    if require_all:
        missing = [kw for kw, f in zip(keywords, found) if not f]
        assert not missing, f'Missing keywords: {missing}'
    else:
        assert any(found), f'None of {keywords} found in: {text[:100]}'

# Tests
response = 'The capital city of France is Paris, located in western Europe.'
assert_keywords_present(response, ['paris', 'france', 'capital'])
print('All keywords present!')  # passes

assert_keywords_present(response, ['spain', 'france'], require_all=False)
print('At least one keyword present!')  # passes

Verificando o formato da resposta: verificações de tipo

Asserções de tipo são rápidas e confiáveis. Verifique se o agente retorna um dicionário, e não um valor nulo, se os campos de lista são listas e se os campos numéricos estão dentro de intervalos válidos.

def test_agent_returns_valid_structure(agent_result):
    # Type checks
    assert isinstance(agent_result, dict), 'Result must be a dict'
    assert isinstance(agent_result.get('answer'), str), 'answer must be a string'
    assert isinstance(agent_result.get('steps'), list), 'steps must be a list'

    # Non-empty checks
    assert len(agent_result['answer']) > 0, 'answer must not be empty'
    assert len(agent_result['steps']) >= 1, 'must have at least one step'

    # Range checks
    confidence = agent_result.get('confidence', 0)
    assert 0.0 <= confidence <= 1.0, 'confidence must be 0-1'

print('Structural assertions are fast and reliable')

Verificando o motivo de término

O campo finish_reason informa por que o modelo parou de gerar conteúdo. Verificá-lo ajuda a detectar problemas: 'stop' significa uma resposta concluída corretamente, 'tool_calls' significa que o agente quer chamar uma ferramenta, e 'length' significa truncamento.

from unittest.mock import MagicMock

def test_agent_stops_cleanly(mock_response):
    finish_reason = mock_response.choices[0].finish_reason
    assert finish_reason in ('stop', 'tool_calls'), \
        f'Unexpected finish_reason: {finish_reason}'

def test_no_truncation(mock_response):
    finish_reason = mock_response.choices[0].finish_reason
    assert finish_reason != 'length', \
        'Response was truncated — increase max_tokens'

# Example mock for a clean stop
mock = MagicMock()
mock.choices = [MagicMock(finish_reason='stop')]
test_agent_stops_cleanly(mock)
print('finish_reason: stop — clean termination')

Verificando o número de etapas em um loop

Um agente executado em um loop deve ser concluído em um número razoável de etapas. Faça uma asserção para confirmar que o agente termina dentro de uma quantidade máxima de iterações — isso identifica loops infinitos que a proteção contra iterações excessivas deve evitar.

def test_agent_completes_in_bounded_steps(mock_agent):
    result = mock_agent.run('Search for the weather in Paris')

    # Agent should complete within 5 steps
    assert result['steps_taken'] <= 5, \
        f'Agent took too many steps: {result["steps_taken"]}'

    # Agent should produce a final answer, not exit on timeout
    assert result['status'] == 'completed', \
        f'Agent did not complete: {result["status"]}'

    assert result['answer'] is not None

print('Bounding step count prevents runaway agents from passing tests')

Parametrize testes para várias entradas

@pytest.mark.parametrize do pytest permite executar o mesmo teste com muitas entradas diferentes. Isso é ideal para verificar se seu agente encaminha diferentes tipos de consulta para as ferramentas corretas.

import pytest
from unittest.mock import patch, MagicMock
import json

@pytest.mark.parametrize('query,expected_tool', [
    ('What is the weather in Tokyo?', 'get_weather'),
    ('Calculate 15% of 200', 'calculator'),
    ('Search for Python books', 'web_search'),
    ('What time is it in Berlin?', 'get_time'),
])
@patch('myagent.client.chat.completions.create')
def test_agent_tool_routing(mock_create, query, expected_tool):
    tool_call = MagicMock()
    tool_call.function.name = expected_tool
    tool_call.function.arguments = json.dumps({'input': query})
    mock_create.return_value = MagicMock(
        choices=[MagicMock(message=MagicMock(tool_calls=[tool_call]))]
    )
    response = mock_create()
    actual = response.choices[0].message.tool_calls[0].function.name
    assert actual == expected_tool

Escrevendo auxiliares de asserção personalizados

À medida que sua suíte de testes de agentes cresce, extraia padrões comuns de asserção para funções auxiliares. Isso torna os testes mais curtos, legíveis e fáceis de manter quando o formato de resposta do agente mudar.

import json

def assert_tool_called(response, tool_name: str, required_args: dict = None):
    message = response.choices[0].message
    assert message.tool_calls, 'Expected tool call but got plain text'
    names = [tc.function.name for tc in message.tool_calls]
    assert tool_name in names, f'Expected {tool_name}, got {names}'

    if required_args:
        for tc in message.tool_calls:
            if tc.function.name == tool_name:
                args = json.loads(tc.function.arguments)
                for key, val in required_args.items():
                    assert args.get(key) == val, \
                        f'Arg {key}: expected {val}, got {args.get(key)}'

# Clean test using the helper:
# assert_tool_called(response, 'get_weather', {'city': 'Paris'})

# --- demo ---
from unittest.mock import MagicMock

tool_call = MagicMock()
tool_call.function.name = 'get_weather'
tool_call.function.arguments = json.dumps({'city': 'Paris'})
response = MagicMock(choices=[MagicMock(message=MagicMock(tool_calls=[tool_call]))])

assert_tool_called(response, 'get_weather', {'city': 'Paris'})
print('assert_tool_called passed: agent called get_weather with city=Paris')

Verificação de conhecimento: testes de agentes baseados em asserções

Teste sua compreensão das estratégias de asserção para testes de agentes.

Responda na aula interativa

Recapitulação: testes de agentes baseados em asserções

Agora você tem um conjunto completo de ferramentas de asserção para testes de agentes:

Verifique se tool_calls não está vazio quando o agente deve usar uma ferramenta
Faça uma asserção sobre o nome correto da ferramenta com tc.function.name == 'expected_tool'
Valide os argumentos da ferramenta analisando tc.function.arguments como JSON
Use jsonschema.validate() para validar saídas estruturadas
Use verificações de presença de palavras-chave para asserções de texto flexíveis
Verifique finish_reason e a quantidade de etapas em agentes que usam loops
Use @pytest.mark.parametrize para vários cenários de entrada

Grátis para começar

Aprenda AI Agents com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 60
Aulas: 239

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Testes de agentes baseados em asserções” é grátis?

Sim — o texto completo de “Testes de agentes baseados em asserções” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Testes de agentes baseados em asserções”?

Verificação de chamadas de ferramentas, etapas intermediárias e estrutura da saída final. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Testes de agentes baseados em asserções”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Por que testar agentes é diferente
Simulando chamadas de LLM em testes
Testes de agentes baseados em asserções
Testes de integração para pipelines de agentes

← Voltar para AI Agents