Inicio / Artículos

Cinco patrones de ingeniería de agentes que vale la pena tomar prestados de Harness de DeepSeek

Registro de eventos como fuente de verdad, advertencias por bucles con niveles de gravedad, truncación explícita, modo de código con verificación de permisos y transferencias de agente actualizadas: cinco patrones para crear sistemas de agentes susceptibles a depuración.

Editor: REACTAPP.TOP9 min de lectura1995 palabras

Fuentes: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness

Los agentes siguen mejorando en la escritura de código, el uso de herramientas, la búsqueda de archivos y la realización de tareas prolongadas. Debajo de todo esto se esconde un problema más sutil: ¿qué impide que un agente se vuelva caótico, impredecible y casi imposible de depurar? Al analizar las decisiones técnicas del framework de agentes de código abierto de DeepSeek, se identifican cinco ideas que vale la pena adoptar incluso si nunca se utiliza dicho framework. No se trata tanto de trucos específicos de DeepSeek como de patrones válidos para los sistemas de agentes en general.

1. Hacer que el registro de eventos sea la fuente de verdad

La mayoría de los sistemas de agentes almacenan la conversación en una lista que se pasa al modelo:

messages = [...]

En otro lugar, un guardabosques registra lo que sucedió:

logger.info({
    "messages": messages,
    "tool_calls": tool_calls,
    "tokens": tokens
})

Eso parece razonable, pero genera dos versiones de los mismos eventos, y ese es el aspecto arriesgado. Supongamos que la aplicación edita la lista de mensajes antes de enviarla, por ejemplo, añadiendo una instrucción adicional:

messages.append({
    "role": "system",
    "content": "Remember to be concise."
})

Si el registro de eventos nunca registró esa edición, el modelo detectó algo sobre lo cual sus registros no saben nada. Seis horas después, el agente hace algo extraño, y usted abre los registros preguntándose por qué. La explicación podría ser un mensaje del sistema que no aparece en ningún lugar de la historia registrada.

El enfoque mejor

Haga que el registro de eventos sea la única fuente autorizada. Él contiene los hechos, como la solicitud del usuario, cada llamada a una herramienta, cada resultado y las respuestas del asistente:

events = [
    UserMessage("Fix the authentication bug"),
    ToolCall("grep", {"query": "auth"}),
    ToolResult("Found 12 matches"),
    AssistantMessage("I'll inspect the middleware")
]

El contexto del modelo se deriva entonces de esos eventos y no se mantiene como una lista separada:

def build_context(events):
    return [
        event.to_message()
        for event in events
        if event.visible_to_model
    ]

El punto es que no existe un array de mensajes privados y ocultos. Se calcula cada vez. Compare las dos estructuras: la preferida va desde el registro, pasando por un constructor de contexto, hasta la solicitud:

Event Log
    ↓
Context Builder
    ↓
LLM Request

Aquel que debe evitarse es el que divide el registro, con una rama que alimenta los registros y otra que alimenta los mensajes que van al modelo:

Event Log ─────────→ Logs
       \
        → Messages ─→ LLM

Ese pequeño cambio estructural hace que la depuración sea mucho más sencilla.

Vaya un paso más allá y verifíquelo

Durante el desarrollo puede agregar una comprobación que reconstruya el contexto esperado a partir del registro y lo compare con lo que realmente se va a enviar:

expected = build_context(event_log)
actual = request.messages
if actual != expected:
    raise RuntimeError(
        "log-reconstruction desync"
    )

Con eso en su lugar, la deriva en el contexto se convierte en una prueba fallida y ya no en un error de producción desconcertante. También hay una ventaja adicional: la observabilidad se vuelve mucho más útil. Si una vista de trayectoria muestra las llamadas al modelo, las llamadas a las herramientas, los resultados de estas, el uso de tokens y el tiempo transcurrido, nadie necesita armar una historia separada de lo que sucedió, porque la información ya está presente: el agente la necesita para reconstruir su propio contexto. Una única fuente de verdad acaba realizando dos funciones.

2. No bloquee de inmediato los bucles del agente

Cada desarrollador de agentes se enfrenta a esto tarde o temprano. El modelo ejecuta la misma búsqueda una y otra vez:

grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...

El problema es evidente, y la solución obvia también lo es: rechazar las llamadas repetidas.

if previous_call == current_call:
    raise LoopError()

El problema es que la repetición a veces es legítima. Una solicitud de red puede fallar, un archivo podría haber cambiado y realmente podría ser necesario intentarlo de nuevo. En lugar de bloquear al modelo, adviérsele.

Imagínese un sistema de presión que aumenta con la cantidad de repeticiones:

3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder

El primer nivel podría indicar que se está repitiendo la misma llamada de herramienta y sugerir volver a leer el último resultado:

if repeat_count >= 3:
    inject(
        "You are repeating the same tool call. "
        "Re-read the last result and consider another approach."
    )

El segundo nivel es más estricto y le indica al agente que se detenga y reevalúe:

if repeat_count >= 5:
    inject(
        "You have repeated this exact operation several times. "
        "Stop and reassess the approach."
    )

En el tercer punto, el mensaje indica que parece tratarse de un bucle y que es necesario cambiar el enfoque, o bien finalizar el trabajo:

if repeat_count >= 8:
    inject(
        "This appears to be a loop. "
        "Change your approach or wrap up."
    )

Fíjese en lo que el arnés no hace. Nunca devuelve un rechazo directo como este:

return False

El control permanece en manos del modelo. El arnés solo proporciona más información y permite que el modelo tome la decisión, lo cual es una distinción importante.

Cuentar repeticiones reales

Un buen detector no puede ser engañado por llamadas no relacionadas insertadas entre ellas. Esta secuencia debe seguir contándose como repetición:

grep foo
todo update
grep foo

De lo contrario, el modelo podría reiniciar su propio contador realizando trabajos inútiles entre llamadas idénticas. Los argumentos también deben normalizarse, de modo que estas dos se consideren la misma operación:

{"query": "foo", "path": "src"}

y:

{"path": "src", "query": "foo"}

El orden de las claves en un diccionario no debería importar. Las llamadas denegadas también deben contarse. Si el modelo sigue intentando algo así:

run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied

Es exactamente en ese momento cuando debe darse cuenta de que quizás sea sensato dejar de intentarlo.

El patrón general

El enfoque débil es una reacción brusca ante un mal comportamiento:

Bad behavior → hard block

Uno más robusto detecta el comportamiento, aumenta la retroalimentación y permite que el modelo se recupere:

Bad behavior
     ↓
Detect
     ↓
Increase feedback
     ↓
Let model recover

Es una idea aparentemente sencilla, y se adapta a casi cualquier marco de agentes que exponga llamadas a herramientas.

3. Indicar al modelo lo que no vio

Parece obvio, pero muchas herramientas lo hacen mal. Supongamos que un repositorio contiene esto:

4,000 files

Y una herramienta de búsqueda devuelve solo esto:

100 files

Si la respuesta son simplemente esos cien archivos, el modelo podría concluir que exactamente cien archivos coinciden. De hecho, la herramienta decía “aquí hay cien porque dejé de buscar”, y los dos significados son completamente diferentes.

Hacer explícita la truncación

Una respuesta mejor indica qué sucedió y dónde se encuentran el resto:

Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt

El modelo ahora sabe tres cosas: existen más resultados, lo que tiene es un subconjunto, y la lista completa está al alcance si es necesario. Esa es una posición mucho más segura.

El muestreo puede ser mejor que tomar los primeros N

Supongamos que hay 4,000 archivos y espacio para 100. La forma ingenua es un simple recorte:

results[:100]

Los resultados ordenados pueden ser peligrosos, ya que es posible obtener cientos de archivos de un mismo directorio o con un mismo patrón de nomenclatura. Distribuir las muestras por toda la lista proporciona más información:

def sample_results(results, limit=100):
    step = len(results) / limit
return [
        results[int(i * step)]
        for i in range(limit)
    ]

El algoritmo exacto importa menos que el principio: nunca permitir que el modelo confunda lo que existe con lo que mostró la herramienta.

Los errores merecen la misma atención

También los errores de las herramientas pueden engañar a un agente. Supongamos que una orden es bloqueada por una política de seguridad. Un mensaje tan simple como este es insuficiente:

Permission denied

porque el modelo podría decidir que su sintaxis es incorrecta y luego intentarlo una y otra vez. Un mensaje mucho mejor es uno explícito:

Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.

Eso es más que un mensaje amable. Es una guía para el agente. Sus herramientas hacen algo más que ejecutar operaciones, ya que comunican con otro sistema de razonamiento. La salida de la herramienta debe responder a una pregunta: ¿qué necesita saber el modelo para tomar su próxima decisión correctamente?

4. La ejecución de código no debe eludir los permisos

Otro patrón en los sistemas de agentes modernos es el modo de código. En lugar de permitir una sola llamada a herramienta por turno, se le proporciona al modelo un entorno de programación:

files = search("authentication")
for file in files:
    content = read_file(file)
    print(analyze(content))

Esto es poderoso. Mientras que el bucle habitual alterna entre llamadas al modelo y a la herramienta, ronda tras ronda:

LLM
 ↓
search
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read

El modo de código permite que el modelo ejecute un programa que realiza muchas llamadas y devuelve un resumen:

LLM
 ↓
run_code(...)
 ↓
50 tool calls
 ↓
summary

Eso puede reducir drásticamente los viajes de ida y vuelta y el uso de contexto, pero plantea una grave cuestión de seguridad.

¿Quién verifica las llamadas dentro del programa?

La arquitectura habitual envía cada acción del modelo a través de una capa de permisos antes de que llegue a una herramienta:

Model
 ↓
Permission Layer
 ↓
Tool

Si se añade la ejecución de código de forma descuidada, este puede acceder directamente a las herramientas:

Model
 ↓
Code
 ↓
Tool

Si ese es el caso, ha creado una puerta trasera alrededor de su sistema de permisos, lo cual es claramente negativo. Un diseño adecuado mantiene todas las llamadas del programa en el mismo camino de seguridad:

Model
 ↓
run_code
 ↓
Program
 ↓
Permission Layer
 ↓
Tool

Cada llamada a la herramienta sigue pasando por el mismo proceso. Conceptualmente, la función de lectura de archivos verifica primero los permisos antes de realizar cualquier acción:

def read_file(path):
    permission = check_permission(
        operation="read",
        path=path
    )
if not permission.allowed:
        raise PermissionError(
            "File access denied"
        )
    return actual_read(path)

El intérprete de código no recibe una versión especial de la función. Recibe la misma que utilizan todos los demás.

Convierta las denegaciones en errores normales del programa

Sigue un detalle más sutil. Si un programa intenta hacer algo que no le está permitido:

try:
    delete_file("/important/file")
except PermissionError as e:
    print(e)

Debería recibir un error normal que se pueda capturar. No debería quedar en estado indefinido:

hang forever

No debería obtener silenciosamente un resultado vacío:

return None

Y no debería comportarse como si nada hubiera pasado:

pretend nothing happened

El programa debe entender que la operación falló, lo cual es sumamente importante cuando el modelo escribe programas sobre la marcha. El modo de código es poderoso precisamente porque le brinda al modelo más control, y eso significa que los límites de permisos deben ser más estrictos y no menos.

5. A veces la mejor estrategia de contexto es no tener contexto

Esta es una idea que más desarrolladores de agentes deberían probar. Los agentes que funcionan durante mucho tiempo acumulan enormes cantidades de historial de conversaciones. Al principio eso ayuda, pero luego se convierte en una carga. Acabas con una cadena de interacciones que alimentan un contexto gigantesco:

Round 1
 ↓
Round 2
 ↓
Round 3
 ↓
Round 4
 ↓
Round 5
 ↓
Huge context

Ahora el modelo dedica su atención a releer su propio historial en lugar de resolver la tarea. La resumen es una solución, pero hay otra: terminar la conversación y conservar el espacio de trabajo.

Tomemos una tarea de programación que se ejecuta en cinco rondas. En la primera ronda, el primer agente inspecciona el repositorio, realiza cambios, guarda su trabajo y escribe una nota de transferencia:

Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff

La segunda ronda comienza con un agente completamente nuevo que lee el espacio de trabajo y la transferencia, y continúa con su tarea:

Agent B
→ read workspace
→ read handoff
→ continue

No existe una historia extensa, ni razonamientos obsoletos, ni ruido generado por herramientas acumuladas. Solo cuenta con el estado actual.

Leer más