Ingeniería de contexto de Agent

Agent 上下文工程(Agent Context Engineering) es una práctica técnica para diseñar y optimizar sistemáticamente la información de contexto que se transmite a un Agent de IA. Su objetivo es que el Agent obtenga la información más eficaz dentro de la ventana de contexto limitada, mejorando así la precisión, la eficiencia y la fiabilidad de la ejecución de tareas.

Un Agent de IA no tiene una lógica de ejecución fija como los programas tradicionales; su comportamiento depende completamente del contexto que recibe, incluyendo las instrucciones del sistema, las descripciones de las herramientas, el historial de conversaciones y la información recuperada externamente.

El núcleo de la ingeniería de contexto consiste en responder a una pregunta:¿Qué es lo que más necesita saber el Agent en esta ronda de llamadas?

La ingeniería de contexto no consiste en redactar prompts de una sola vez, sino que es un proceso de optimización continua que abarca todo el ciclo de vida del desarrollo, las pruebas y el mantenimiento del sistema Agent.

Elementos clave

El contexto del Agent se compone de las siguientes capas:

NivelContenidoCaracterísticas
Instrucciones del sistema (System Prompt)Definición del rol, reglas de comportamiento, requisitos de formato de salidaSe incluye en cada llamada, es relativamente estable
Definiciones de herramientas (Tool Definitions)Nombre, parámetros y descripción de la funcionalidad de las herramientas disponiblesConsume una gran cantidad de tokens, requiere simplificación
Historial (History)Registro de conversaciones y llamadas a herramientas de la sesión actualCrece continuamente, necesita estrategias de truncamiento o resumen
Contexto recuperado (Retrieved Context)Contenido recuperado de una base de conocimientos o un repositorio de código externoSe inyecta bajo demanda, requiere ordenación por relevancia
Entrada del usuario (User Input)Instrucción o pregunta actual del usuarioNo es controlable, pero se puede optimizar mediante aclaraciones

Prácticas clave

Gestión del presupuesto de contexto

Tratar la ventana de contexto como un «presupuesto» limitado y asignarlo razonablemente a los diferentes tipos de contexto.

No toda la información merece ocupar espacio en el contexto; cada elemento de contexto debería tener un ROI claro.

上下文预算分配建议(以 200K token 窗口为例):

系统提示  ██████████ 10% (20K token)
工具定义  ████████████████ 20% (40K token)
检索上下文 ████████████████████ 25% (50K token)
历史记录  ████████████████████████ 30% (60K token)
用户输入  ████████ 5%~10% (10-20K token)
预留缓冲  ████ 5% (10K token)

Las proporciones reales deben ajustarse dinámicamente según el tipo de tarea específica del Agent.

Si el Agent se dedica principalmente a la generación de código, se puede aumentar la proporción del contexto recuperado.

Si el Agent es un asistente de conversación multipaso, se debe priorizar el presupuesto del historial.

Ingeniería de las instrucciones del sistema

Las instrucciones del sistema son la base del comportamiento del Agent y deben seguir principios de redacción estructurada.

Principios de redacción:

PrincipioDescripciónEjemplo
Organización jerárquicaDividir las instrucciones en bloques por rol, reglas, flujo y formatoUsar títulos de Markdown para separar
Formulación positivaDecir al Agent qué debe hacer, no qué no debe hacer«Mantén las respuestas concisas» es mejor que «no seas prolijo»
Proporcionar ejemplosUsar ejemplos few-shot en lugar de descripciones extensasUn ejemplo de formato de salida es más eficaz que una descripción textual
Prioridades clarasQué regla debe seguir el Agent cuando hay conflictos entre reglas«Las reglas de seguridad tienen prioridad sobre los requisitos de eficiencia»
Eliminar redundanciasEliminar reglas que nunca se activan y descripciones repetidasRevisar y simplificar periódicamente las instrucciones del sistema

A continuación se muestra un esqueleto de ejemplo de instrucciones del sistema estructuradas:

## 角色
你是一名 Python 代码审查助手。

## 核心规则
- 每个问题附上修复建议
- 按严重程度排序输出
- 不确定时标注「待确认」

## 工作流程
1. 分析代码变更
2. 按严重程度分类问题
3. 逐一输出问题与建议

## 输出格式
**问题**:[问题描述]
**严重程度**:[高/中/低]
**建议**:[修复建议]

Optimización de las descripciones de herramientas

Las descripciones de herramientas suelen ocupar la mayor parte del contexto, pero muchas herramientas nunca se invocan realmente.

Las estrategias de optimización incluyen:

EstrategiaMétodoEfecto
Simplificación de herramientasEliminar las definiciones de herramientas que no están relacionadas con la tarea actualReducir del 30 % al 50 % el contexto de herramientas
Descripción concisaExplicar el propósito y los parámetros de cada herramienta en una sola fraseMejorar la precisión del modelo para entender las herramientas
Restricciones de parámetrosEspecificar los escenarios de uso y las limitaciones de los parámetros en la descripciónReducir errores de parámetros en las llamadas a herramientas
Registro por gruposRegistrar dinámicamente diferentes conjuntos de herramientas según la fase de la tareaEvitar la «dificultad de elección» causada por un exceso de herramientas

Toda definición de herramienta que no sea cero es una carga. Cada herramienta conservada requiere un equilibrio entre la calidad de la descripción y el coste de tokens.

Estrategias de compresión del historial

En las conversaciones multipaso, el historial crece rápidamente y ocupa contexto.

Es necesario elegir una estrategia de compresión adecuada para equilibrar la integridad del contexto y las limitaciones de la ventana.

常见历史压缩策略对比:

策略     方法            适用场景
─────────────────────────────────────────────────
滑动窗口   保留最近 N 轮完整记录    短对话、实时交互
阶梯摘要   每轮做一次增量摘要     长对话、客服场景
分层摘要   近期保留完整、远期做摘要  文档生成、复杂任务
关键轮标记  标记重要轮次,其余丢弃   调试、分步执行任务

El resumen jerárquico es la estrategia más utilizada: las últimas 3-5 rondas se mantienen completas y las conversaciones anteriores se sustituyen por resúmenes estructurados.

El resumen estructurado debe incluir la información clave de la conversación original: cuál era el objetivo del usuario, qué hizo el Agent, qué salida se produjo y qué errores se encontraron.

Control de calidad del contexto recuperado

Cuando el Agent depende de una base de conocimientos externa, la calidad del contexto recuperado determina directamente la calidad de la salida.

Puntos clave para mejorar la calidad del contexto recuperado:

EtapaProblemas comunesMétodo de mejora
Reformulación de consultasLa entrada del usuario no es lo suficientemente precisaHacer que el Agent reformule la consulta antes de recuperar
Filtrado por relevanciaLos resultados de la recuperación contienen contenido irrelevanteEstablecer un umbral de relevancia y avisar activamente cuando no se alcance
Indicación de la fuenteEl Agent no puede juzgar la credibilidad de la informaciónAdjuntar la ruta de la fuente y la fecha de actualización
Recorte de longitudLos resultados de la recuperación ocupan demasiado contextoRecortar por párrafos y conservar los fragmentos más relevantes

Patrones comunes

Divulgación progresiva

No introducir toda la información en el contexto de una sola vez, sino divulgarla progresivamente según la fase de ejecución.

El contexto inicial solo contiene las instrucciones del sistema y las herramientas necesarias para la fase actual; cuando el Agent completa la fase actual, se inyectan las herramientas y reglas de la siguiente fase.

Este patrón mantiene la «densidad» del contexto dentro de un rango razonable y evita que el Agent se vea interferido por información irrelevante.

Cadena de compresión de contexto

Cuando una tarea requiere procesar grandes cantidades de datos, se divide en varios pasos mediante llamadas en cadena, conservando solo los resultados intermedios clave en cada paso.

步骤1:读取全部日志文件 → 输出 { 错误数量,时间范围,错误类型列表 }

步骤2:基于步骤1的输出,分析 Top 3 错误 → 输出 { 根因分析,修复建议 }

步骤3:基于步骤2的输出,生成修复 PR → 输出 { PR 标题,描述,代码变更 }

La entrada de cada eslabón de la cadena es el resumen refinado del paso anterior, no los datos originales, de modo que el contexto se mantiene siempre en un tamaño controlable.

Marca de agua de contexto

Colocar marcadores «marca de agua» en posiciones clave del contexto para ayudar a monitorizar y diagnosticar el comportamiento del Agent.

上下文水印示例:

<system-reminder>
当前使用的上下文策略版本:v2.3
检索到的文档来源:docs/api-reference/ 共 3 个文件
已消耗上下文:85,000 / 200,000 tokens
</system-reminder>

Estas marcas de agua no afectan directamente al comportamiento del Agent, pero durante la depuración permiten localizar rápidamente si la inyección de contexto se ha ejecutado según lo previsto.


Evaluación e iteración

La eficacia de la ingeniería de contexto debe verificarse mediante evaluaciones; no se puede juzgar solo por intuición.

Dimensiones de evaluación habituales:

DimensiónMétodo de evaluaciónIndicadores clave
Tasa de finalización de tareasEjecutar el Agent sobre un conjunto de pruebas estándarTasa de éxito, distribución de causas de fallo
Eficiencia del contextoContabilizar el uso de contexto en cada llamadaConsumo medio de tokens, tasa de utilización del contexto
Calidad de las llamadas a herramientasAnalizar la tasa de precisión de las llamadas a herramientas y la tasa de corrección de parámetrosProporción de llamadas no válidas, número de reintentos
Consistencia de las respuestasProbar varias veces con la misma entradaEstabilidad de la salida, tasa de cumplimiento del formato

La ingeniería de contexto no es una configuración única, sino que requiere establecer un bucle iterativo de «prueba → análisis → optimización → nueva prueba».


Consideraciones

La ventana de contexto no es mejor cuanto más grande. Un exceso de contexto diluye la atención del modelo sobre la información clave y, en cambio, reduce la calidad de la salida.

Añadir reglas a ciegas puede hacer que las instrucciones del sistema se vuelvan voluminosas y contradictorias. Cada nueva regla requiere revisar si entra en conflicto con las reglas existentes.

Los cambios en las definiciones de herramientas pueden afectar al comportamiento de los Agent existentes; tras modificarlos, es necesario realizar pruebas de regresión en escenarios típicos.

La estrategia de compresión del historial debe seleccionarse según las características de las tareas del Agent; ninguna estrategia puede lograr el mejor rendimiento en todos los escenarios.

La información sensible en el contexto (claves API, rutas internas, etc.) se propaga en las llamadas a herramientas y en los registros, por lo que es necesario aplicar un tratamiento de enmascaramiento.


Conceptos relacionados

ConceptoDescripción
Prompt EngineeringCentrado en el diseño y la optimización de prompts para una única llamada
Context WindowLímite máximo de tokens que el modelo puede procesar de una sola vez
TokenUnidad semántica mínima que el modelo procesa del texto
RAG (generación aumentada por recuperación)Patrón de arquitectura que amplía el contexto mediante recuperación externa
Few-shot PromptingProporcionar ejemplos en el contexto para guiar la salida del modelo
Chain-of-ThoughtPermitir que el modelo muestre su proceso de razonamiento en el contexto
Otras extensiones