0Pricing
AI Agents · Aula

Retornando resultados ao modelo

Formate as saídas das ferramentas como mensagens com o papel de ferramenta para que o modelo possa lê-las e continuar a conversa.

Retornando resultados ao modelo é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 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.

A mensagem de resultado da ferramenta

Depois de executar uma ferramenta, informe o resultado ao modelo com uma mensagem de ferramenta:

messages.append({
    'role': 'tool',
    'tool_call_id': tool_call.id,    # MUST match the assistant's tool_call.id
    'content': json.dumps(result)
})

O conteúdo deve ser uma string

A OpenAI espera que content seja uma string. Serialize objetos com json.dumps:

# Bad — will error
messages.append({'role': 'tool', 'tool_call_id': id, 'content': {'temp': 18}})

# Good
messages.append({'role': 'tool', 'tool_call_id': id, 'content': '{"temp": 18}'})

Formato da Anthropic

A Anthropic usa um bloco de conteúdo dentro de uma mensagem do usuário:

messages.append({
    'role': 'user',
    'content': [{
        'type': 'tool_result',
        'tool_use_id': 'toolu_abc',
        'content': json.dumps(result)
    }]
})

Retorno de erros

Se a ferramenta falhar, retorne o erro — não finja que a operação foi bem-sucedida. O modelo pode se recuperar:

try:
    result = run_tool(...)
    content = json.dumps({'ok': True, 'data': result})
except Exception as e:
    content = json.dumps({'ok': False, 'error': str(e)})

messages.append({'role': 'tool', 'tool_call_id': id, 'content': content})

Padrão de múltiplos resultados

Para chamadas de ferramentas em paralelo, adicione cada resultado com o ID correspondente:

for tc in message.tool_calls:
    result = dispatch(tc)
    messages.append({
        'role': 'tool',
        'tool_call_id': tc.id,
        'content': json.dumps(result)
    })

Saídas grandes: faça um resumo

Se uma ferramenta retornar 100 KB de HTML, enviar tudo ao modelo desperdiçará tokens e dispersará sua atenção. Faça um resumo ou trunque o conteúdo primeiro:

def truncate(text, max_chars=4000):
    if len(text) <= max_chars:
        return text
    return text[:max_chars] + f'\n...[truncated, {len(text)-max_chars} more chars]'

sample = "x" * 4500
result = truncate(sample, max_chars=50)
print(result)

Esquema sempre igual

Mesmo quando os resultados variarem, como sucesso, erro ou não encontrado, mantenha estável o esquema da saída. O modelo é mais confiável com estruturas consistentes:

from typing import TypedDict, Literal, Optional, Any

class ToolResult(TypedDict):
    status: Literal['ok', 'not_found', 'error']
    data: Optional[Any]
    error: Optional[str]

def make_result(status, data=None, error=None) -> ToolResult:
    return {'status': status, 'data': data, 'error': error}

print(make_result('ok', data={'temp': 72}))
print(make_result('not_found', error='city not found'))

Inclua indicações de metadados

Ajude o modelo a interpretar os resultados incluindo indicações no conteúdo:

content = json.dumps({
    'data': rows,
    'note': 'Returned 50 rows (most recent first). There may be more matches.'
})

Dados binários

Não codifique grandes blocos de dados em base64 nas mensagens de ferramentas. Em vez disso, salve-os no armazenamento e retorne uma URL ou um ID:

result = {
    'image_path': '/tmp/chart-abc.png',
    'thumbnail_url': 'https://...',
    'caption': 'Sales by quarter, 2024'
}
for k, v in result.items():
    print(f"{k}: {v}")

Chame o modelo novamente em um laço

Depois de adicionar todos os resultados das ferramentas, chame o modelo novamente — ele produzirá uma resposta final ou chamará mais ferramentas:

class Msg:
    def __init__(self, tool_calls=None, content=None):
        self.tool_calls = tool_calls or []
        self.content = content

class ToolCall:
    def __init__(self, name, args):
        self.name = name
        self.args = args

def call_model(messages, tools):
    if len(messages) < 4:
        return Msg(tool_calls=[ToolCall('get_weather', {'city': 'Paris'})])
    return Msg(content='It is sunny in Paris.')

messages = [{'role': 'user', 'content': 'Weather in Paris?'}]
tools = ['get_weather']
message = call_model(messages, tools)

while message.tool_calls:
    for tc in message.tool_calls:
        result = f'Result of {tc.name}({tc.args})'
        messages.append({'role': 'tool', 'name': tc.name, 'content': result})
        print('Tool call:', tc.name, '->', result)
    message = call_model(messages, tools)

print('Final answer:', message.content)

Auditoria das saídas das ferramentas

Registre cada (tool_call_id, args, result) para fins de depuração. Quando um agente fizer algo estranho, o registro do resultado da ferramenta será o primeiro lugar a consultar.

Formato do resultado da ferramenta

A que se refere o tool_call_id em uma mensagem de ferramenta?

Recapitulação

Agora você domina o ciclo completo de uma chamada de ferramenta. Próximo curso: memória — o terceiro pilar dos agentes.

Perguntas Frequentes

A aula “Retornando resultados ao modelo” é grátis?

Sim — o texto completo de “Retornando resultados ao modelo” é 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 “Retornando resultados ao modelo”?

Formate as saídas das ferramentas como mensagens com o papel de ferramenta para que o modelo possa lê-las e continuar a conversa. 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 4 de 4.

Quanto tempo leva a aula “Retornando resultados ao modelo”?

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

  1. Como funciona a chamada de funções
  2. Definindo esquemas de ferramentas (JSON Schema)
  3. Escolhendo ferramentas em tempo de execução
  4. Retornando resultados ao modelo
← Voltar para AI Agents