Devolver resultados al modelo
Formatee las salidas de las herramientas como mensajes con rol tool para que el modelo pueda leerlas y continuar la conversación.
Devolver resultados al modelo es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.
El mensaje de resultado de la herramienta
Después de ejecutar una herramienta, informe al modelo del resultado mediante un mensaje de herramienta:
messages.append({
'role': 'tool',
'tool_call_id': tool_call.id, # MUST match the assistant's tool_call.id
'content': json.dumps(result)
})El contenido debe ser una cadena
OpenAI espera que content sea una cadena. Serialice los objetos con 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 de Anthropic
Anthropic usa un bloque de contenido dentro de un mensaje de usuario:
messages.append({
'role': 'user',
'content': [{
'type': 'tool_result',
'tool_use_id': 'toolu_abc',
'content': json.dumps(result)
}]
})Devolver errores
Si la herramienta falla, devuelva el error; no finja que se ha ejecutado correctamente. El modelo puede recuperarse:
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})Patrón de múltiples resultados
Para llamadas paralelas a herramientas, añada cada resultado con su ID correspondiente:
for tc in message.tool_calls:
result = dispatch(tc)
messages.append({
'role': 'tool',
'tool_call_id': tc.id,
'content': json.dumps(result)
})Salidas grandes: resumir
Si una herramienta devuelve 100 KB de HTML, enviarlo todo al modelo desperdicia tokens y dispersa su atención. Resuma o trunque el contenido primero:
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 siempre igual
Aunque los resultados varíen (éxito / error / no encontrado), mantenga estable el esquema de salida. El modelo es más fiable cuando las estructuras son coherentes:
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'))Incluir indicios de metadatos
Ayude al modelo a interpretar los resultados incluyendo indicios en el contenido:
content = json.dumps({
'data': rows,
'note': 'Returned 50 rows (most recent first). There may be more matches.'
})Datos binarios
No incluya blobs grandes codificados en base64 en los mensajes de herramientas. En su lugar, guárdelos en un sistema de almacenamiento y devuelva una URL o un 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}")
Volver a llamar al modelo
Después de añadir todos los resultados de las herramientas, vuelva a llamar al modelo; producirá una respuesta final o llamará a más herramientas:
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)
Auditar las salidas de las herramientas
Registre cada (tool_call_id, args, result) para depurar. Cuando un agente haga algo extraño, el registro de resultados de las herramientas es el primer lugar que debe consultar.
Formato del resultado de la herramienta
¿A qué hace referencia el tool_call_id de un mensaje de herramienta?
Repaso
Ahora controla todo el ciclo completo de llamadas a herramientas. Siguiente curso: la memoria, el tercer pilar de los agentes.
Preguntas frecuentes
¿La lección «Devolver resultados al modelo» es gratis?
Sí — el texto completo de «Devolver resultados al modelo» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.
¿Qué aprenderé en «Devolver resultados al modelo»?
Formatee las salidas de las herramientas como mensajes con rol tool para que el modelo pueda leerlas y continuar la conversación. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar AI Agents?
No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Devolver resultados al modelo»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de AI Agents?
Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Cómo funciona la llamada a funciones
- Definir esquemas de herramientas (JSON Schema)
- Elegir herramientas en tiempo de ejecución
- Devolver resultados al modelo