El proceso del agente
Cómo analiza el motor un problema, desde el disparador y el contexto que arma hasta la llamada al proveedor, la respuesta revisada, la alerta que libera y el prompt, con lo que se guarda en caché, lo que se limita y lo que solo agrega Sypnia Cloud.
En esta página
- Todo el proceso
- Disparadores y control de repeticiones
- Paso 1: recolectar
- Paso 2: depurar, y luego ajustar
- Paso 3: preguntar
- La abstracción del proveedor
- La respuesta que debe devolver
- Paso 4: revisar
- Paso 5: escribir, y liberar la alerta
- Límites de costo y qué se guarda en caché
- El prompt
- Pull requests
- Sugerencias semanales
- Qué cambió frente al sistema del que sale
- Sigue
El agente es la parte del motor que lee un problema y escribe una frase sobre él. Esta página explica cómo está construido. Qué lee y qué escribe, desde el lado de quien lo usa, está en Cómo funciona el análisis.
Dos hechos enmarcan todo lo de aquí. El agente está apagado por defecto en el motor: con ai.provider en none no hace ninguna llamada ni envía nada a ninguna parte. Y casi no es un modelo: de los cinco pasos, cuatro son reglas fijas escritas en Rust, y uno es una sola llamada a un modelo que no tiene herramientas.
Todo el proceso
Disparadores y control de repeticiones
Una tarea es una fila. La vía rápida la inserta en la misma transacción que anota la transición, así un problema no puede nacer sin su tarea, y un reintento no puede crear dos.
| Disparador | La inserta | Cuándo |
|---|---|---|
| El problema es nuevo | La vía rápida | La transición Born |
| El problema volvió | La vía rápida | La transición CameBack |
| El problema crece | La vía rápida | Llega al doble de las personas que tenía en su último análisis; o se ve por primera vez en una versión más nueva |
| Tú lo pides | La API | POST /v1/problems/{problem}/analyze, máximo 10 por minuto por token |
| Se saltó ayer | La primera pasada del día | Problemas abiertos con estado limit_reached, primero los que afectaron a más personas |
Antes de que corra una tarea hay cuatro puertas, en este orden. Cada una que se cierra escribe su razón en el problema, así la falta de una frase nunca es silenciosa.
| Puerta | Si se cierra | analysis.status |
|---|---|---|
| Hay un proveedor configurado y el proyecto tiene el agente encendido | No corre nada, no se envía nada | off |
| El problema no está ignorado | La tarea se descarta | sin cambio |
El problema tiene menos de 3 análisis hoy (ai.max_analyses_per_problem_per_day) | La tarea se descarta | sin cambio; queda el último análisis |
El proyecto tiene menos de 100 análisis hoy (ai.max_analyses_per_day) | La tarea se guarda para mañana | limit_reached |
Control de repeticiones. Un problema que estalla puede crecer tres veces en un minuto. Tres reglas dejan eso en una sola llamada:
- Una tarea por problema. La tabla de tareas tiene un índice único sobre el problema para las tareas sin terminar. Un segundo disparador mientras una espera o corre no inserta; pone una marca en la tarea existente.
- Correr de nuevo máximo una vez. Cuando una tarea termina y tiene la marca, corre una vez más, con los conteos más nuevos, si los límites todavía lo permiten.
- Sin llamada para la misma entrada. Al contexto depurado se le hace hash. Si el hash es igual al guardado con el último análisis, se conserva el análisis guardado y no se llama. Por eso «Analizar de nuevo» es gratis cuando nada cambió.
Paso 1: recolectar
El agente estudia una ocurrencia: la más reciente que tenga traza y sesión. Con ella el motor arma exactamente lo que devuelve GET /v1/problems/{problem}/context.
| Parte | Se lee de | Tamaño fijo |
|---|---|---|
| La falla agrupada | problems: tipo, título, la ocurrencia de ejemplo | — |
| La pila con líneas de código | sample.stack_original; las líneas de código salen del sourcesContent del propio source map | 8 marcos de tu código, 5 líneas a cada lado |
| Migas | El archivo de la sesión en el Bucket, los eventos anteriores a la falla | 30 |
| La traza | El segmento que nombra traces.segment, las líneas de ese id de traza | 40 spans, primero los que fallaron y sus padres |
| La versión y lo que cambió | releases: cuándo se vio por primera vez, commits, archivos cambiados, diffs si los enviaste | 10 archivos, 20.000 caracteres de diff |
| El impacto | problems, problem_hits, problem_occurrences | — |
La traducción con source maps corre aquí, antes que todo, porque la pila en tus propios archivos es la parte más útil del contexto. Agrupación de problemas la describe.
Si una parte no se puede armar, queda en null y missing dice por qué: source_maps_not_uploaded, no_session, no_trace, release_unknown. El agente trabaja con lo que hay.
Paso 2: depurar, y luego ajustar
Depurar es una función que va del contexto completo a uno más pequeño. Se aplica antes del presupuesto de tamaño, así nada que no debe salir puede sobrevivir por ser «importante».
| Se quita o se reemplaza | Por |
|---|---|
| Ids, nombres y correos de personas; ids y nombres de cuentas | «person 1», «person 2», en orden de primera aparición |
| Ids de sesión, de traza, de span y de dispositivo | Etiquetas locales cortas («session A»); el motor devuelve los ids reales al resultado |
| Etiquetas de filas de lista, celdas de tabla y texto libre con clic | Su tipo: «a row», «a cell» |
| Cosas que parecen secretos en mensajes y rutas: tokens largos, llaves, correos, números largos | Un marcador de su tipo |
| El nombre y el slug del proyecto | Nada |
Con ai.send_source en false: líneas de código y diffs | Nada. Quedan nombres de archivo, líneas y nombres de función |
Hay tres cosas que no se pueden depurar porque nunca están ahí: lo que una persona escribió, lo que hay dentro de un elemento enmascarado y el contenido de las grabaciones. El SDK no recopila las dos primeras, y el agente nunca abre un fragmento de grabación.
Después el contexto se ajusta a unos 24.000 caracteres.
Fíjate en el extracto en que redact devuelve un tipo distinto del que recibe. El código que llama a un proveedor solo puede recibir un contexto Redacted, así que enviar uno sin depurar no compila.
pub async fn build_context(engine: &Engine, problem: &Problem) -> Result<AgentInput, AgentError> {
// La ocurrencia más reciente que tenga traza y sesión; si no, la más reciente.
let occurrence = occurrences::pick(engine, problem).await?;
// Lo que devuelve GET /v1/problems/{problem}/context: pila, migas, traza, versión, impacto.
let mut full = ProblemContext::load(engine, problem, &occurrence).await?;
if full.stack.as_ref().is_some_and(|s| !s.symbolicated) {
symbolicate::apply(engine, &mut full).await.ok(); // nunca hace fallar el análisis
}
// Las personas pasan a «person 1»; se van ids, nombres y correos; se cortan los secretos del texto.
let mut redacted: Redacted<ProblemContext> = redact(full, &engine.config.ai);
// Se corta por el extremo menos útil hasta que quepa. Cada corte queda anotado para el modelo.
let mut cuts = Vec::new();
while redacted.chars() > MAX_CONTEXT_CHARS {
let Some(cut) = redacted.drop_least_useful() else { break };
cuts.push(cut);
}
redacted.note_cuts(&cuts);
let json = serde_json::to_string(&redacted)?;
Ok(AgentInput {
input_hash: sha256_hex(json.as_bytes()), // la misma entrada dos veces es una sola llamada
restore: redacted.restore_map(), // «session A» → el id real, para el resultado
facts: Facts::from(&redacted), // contra qué se revisará la respuesta
json,
})
}Paso 3: preguntar
Una solicitud. Las instrucciones son un texto fijo que viene con el motor; el contexto va como JSON en el mensaje del usuario; la respuesta debe ser JSON con una forma fija. El modelo no tiene herramientas: no puede navegar, ejecutar código ni pedir más.
La abstracción del proveedor
El motor conoce un modelo solo a través de un trait. Fíjate en lo pequeño que es: texto que entra, texto que sale, y los conteos de tokens para los contadores de uso. Todo lo que sabe de problemas queda del lado del motor.
/// Lo único que el motor necesita de un modelo. Se implementa una vez por formato de comunicación.
#[async_trait]
pub trait AiProvider: Send + Sync {
/// Como está configurado: "openrouter", "openai", "anthropic", "google", "openai-compatible".
fn name(&self) -> &str;
async fn complete(&self, request: &CompletionRequest) -> Result<Completion, AiError>;
}
pub struct CompletionRequest {
pub instructions: &'static str, // texto fijo, viene con el motor
pub input: String, // el contexto ya depurado, como JSON
pub schema: &'static JsonSchema, // se envía a los proveedores que pueden exigir una forma JSON
pub max_output_tokens: u32, // `ai.max_output_tokens`, 2.000 por defecto
pub timeout: Duration, // `ai.timeout_seconds`, o menos cuando una alerta ya debe salir
}
pub struct Completion {
pub text: String,
pub model: String, // como lo nombra el proveedor; se guarda con el análisis
pub tokens_in: u32,
pub tokens_out: u32,
}
/// Se arma una vez al arrancar. `None` es el valor por defecto: el agente está apagado y nunca se envía nada.
pub fn from_config(ai: &AiConfig) -> Result<Option<Arc<dyn AiProvider>>, ConfigError> {
Ok(match ai.provider {
Provider::None => None,
Provider::Anthropic => Some(Arc::new(AnthropicMessages::new(ai)?)),
// OpenRouter, la API de OpenAI, el endpoint compatible con OpenAI de Google y cualquier otro
// endpoint que hable chat completions comparten una implementación y difieren en la URL base.
Provider::OpenRouter | Provider::OpenAi | Provider::Google | Provider::OpenAiCompatible => {
Some(Arc::new(ChatCompletions::new(ai)?))
}
})
}ai.provider | Implementación | URL base por defecto |
|---|---|---|
none | — | — |
openrouter | ChatCompletions | https://openrouter.ai/api/v1 |
openai | ChatCompletions | https://api.openai.com/v1 |
google | ChatCompletions | https://generativelanguage.googleapis.com/v1beta/openai |
openai-compatible | ChatCompletions | Ninguna: ai.base_url es obligatoria |
anthropic | AnthropicMessages | https://api.anthropic.com |
Cinco maneras de conectarse, dos implementaciones. Agregar un proveedor con un tercer formato de comunicación es un archivo que implementa el trait. Los ajustes y cómo comprobar cada uno están en Modelos y qué se envía.
| Motor de SypniaCódigo abierto, en tu propia infraestructura | Sypnia CloudServicio pago, con un plan gratis | |
|---|---|---|
| Qué modelo | El que nombres en ai.model. El motor no tiene modelo por defecto, a propósito. | Lo elige Sypnia, se usa a través de OpenRouter y cambia cuando aparece uno mejor. |
| De quién es la llave | Tuya. Hasta que pongas una, el agente está apagado. | De Sypnia. No hay nada que configurar. |
| A dónde va el contexto | De tu motor a tu proveedor. Nada va a Sypnia. | De Sypnia Cloud al proveedor. |
La respuesta que debe devolver
{
"sentence": "{people} tried to pay {when} and could not. The Pay button does nothing since {release_when}.",
"who": "{people}. Two of them tried again and gave up.",
"doing": "Paying for an order, at the last step of checkout.",
"since": "{release_when}. It worked before.",
"cause": {
"text": "The release renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
"blames": "src/checkout/checkout.tsx:142",
"evidence": [
{ "kind": "release_change", "ref": "release:src/cart/cart.ts", "text": "The release renames `total` to `totalCents` in the Cart type." },
{ "kind": "stack_frame", "ref": "src/checkout/checkout.tsx:142", "text": "confirmPayment() still passes `cart.total` to createPayment()." },
{ "kind": "trace", "ref": "trace A", "text": "POST /api/checkout answered 400 with the code `amount_required`." }
]
},
"what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected."
}Tres cosas de esta forma son deliberadas.
- Sin números propios. El modelo escribe
{people},{sessions},{occurrences},{when}y{release_when}; el motor los llena con sus conteos. «3 personas» nunca es aritmética de un modelo. - Sin confianza. Al modelo no se le pregunta qué tan seguro está. La confianza se fija por regla en el paso siguiente.
causepuede sernull. Las instrucciones dicen que no nombrar una causa es una respuesta correcta cuando los hechos no la sostienen.
Paso 4: revisar
La respuesta se lee de forma estricta y luego se revisa contra los Facts guardados en el paso 2. Fíjate en que la función de abajo nunca repara una respuesta. La acepta, o dice exactamente qué está mal.
pub fn check(answer: &ModelAnswer, facts: &Facts) -> Result<Checked, Vec<Rejection>> {
let mut rejections = Vec::new();
if let Some(cause) = &answer.cause {
// El lugar que señala debe ser un marco de la pila o un archivo que cambió la versión.
if !facts.has_frame(&cause.blames) && !facts.release_changed(&cause.blames) {
rejections.push(Rejection::BlamesUnknownPlace(cause.blames.clone()));
}
// De una a seis evidencias, cada una apuntando a algo que está en el contexto.
if !(1..=6).contains(&cause.evidence.len()) {
rejections.push(Rejection::EvidenceCount(cause.evidence.len()));
}
for item in &cause.evidence {
if !facts.has_ref(item.kind, &item.reference) {
rejections.push(Rejection::EvidenceNotInContext(item.reference.clone()));
}
}
}
// Un conteo escrito con dígitos en vez de un marcador es un conteo que el motor no puede respaldar.
for field in [&answer.sentence, &answer.who, &answer.since] {
if states_a_count(field) {
rejections.push(Rejection::LiteralCount);
}
}
if !rejections.is_empty() {
return Err(rejections);
}
Ok(Checked {
confidence: answer.cause.as_ref().map(|cause| confidence_by_rule(cause, facts)),
answer: answer.clone(),
})
}| Resultado | Qué hace el motor | analysis.status |
|---|---|---|
| La respuesta pasa | Llena los marcadores, devuelve los ids reales, fija la confianza | ready |
La respuesta pasa y cause es null | Conserva la frase, quién, qué hacía y desde cuándo; lista lo que faltó | not_enough_evidence |
| La respuesta falla una revisión | Pregunta una vez más, con los rechazos agregados a la solicitud | — |
| Falla otra vez | Quita la causa, conserva lo que pasó | not_enough_evidence |
| La llamada falla o se agota el tiempo | Intenta de nuevo, dos veces más, con una espera corta | — |
| Tres llamadas fallidas | Se detiene. Se intenta de nuevo cuando el problema crece | failed |
Una causa equivocada dicha con seguridad cuesta más que no tener causa. Por eso los caminos malos terminan en «no hay suficiente evidencia» y nunca en una suposición.
La confianza, por regla:
| Nivel | Regla |
|---|---|
high | Al menos dos tipos de evidencia coinciden, y uno de ellos es un cambio de la versión que toca el código donde falla |
medium | La causa se apoya solo en la pila o en la traza, con líneas de código |
low | La causa encaja con los hechos y nada la confirma: una pila minificada, o sin información de la versión |
Paso 5: escribir, y liberar la alerta
Una transacción:
problems.analysisrecibe el análisis como lo devuelve la API, con el proveedor, el modelo, la hora y el número de corrida.- En el primer análisis, el problema recibe su slug legible, hecho a partir de la frase. El slug viejo sigue funcionando.
analysesrecibe una fila: el hash de la entrada, los conteos de tokens, el resultado. No el contexto ni la respuesta.usage_daily.analysessube en uno.
Después salen dos cosas del motor: el webhook problem.analyzed y la alerta.
La entrega de la alerta. La alerta la escribió la vía rápida con released_at vacío y release_by puesto a 100 segundos después de que la falla llegó a la ingesta. La libera quien llegue primero:
| Quién | Cuándo | El título de la alerta |
|---|---|---|
| El agente | El análisis queda en ready o not_enough_evidence antes de release_by | La frase |
| El agente | El modelo no ha respondido al llegar release_by: el agente deja de esperar, libera, y la llamada sigue corriendo | El título técnico |
| La vía rápida | El agente está apagado, o se cerró una puerta | El título técnico, de inmediato |
| La pasada | Red de seguridad: cualquier alerta que pasó release_by sin que nadie la liberara | El título técnico |
Liberar es un solo UPDATE … WHERE released_at IS NULL, así que si dos compiten, se libera una vez.
Límites de costo y qué se guarda en caché
| Qué | Regla |
|---|---|
| Llamadas al día, por proyecto | 100 por defecto (ai.max_analyses_per_day); 0 es sin límite. Una alerta usage.limit al 80 % y al 100 % |
| Llamadas al día, por problema | 3 (ai.max_analyses_per_problem_per_day) |
| Entrada | Unos 24.000 caracteres, unos miles de tokens |
| Salida | 2.000 tokens (ai.max_output_tokens) |
| Llamadas por análisis | 1 normalmente; 2 cuando la primera respuesta no pasa la revisión; nunca más de 3 contando las fallidas |
| Misma entrada | Sin llamada: el input_hash coincide con el del último análisis |
| Source maps | Los mapas ya leídos se guardan en memoria: 50 mapas o 200 MB |
| El contexto | No se guarda. Se rearma cuando se pide, desde el Bucket y Postgres |
El motor registra tokens, no dinero: no conoce los precios de tu proveedor. La aritmética es tuya: un análisis son unos miles de tokens de entrada y máximo dos mil de salida, y un proyecto hace máximo 100 al día. Pon también un límite de gasto a la llave en tu proveedor; el límite del motor cuenta llamadas, no lo que cuestan.
El prompt
El prompt para un agente de código no lo escribe un modelo. Es una plantilla fija que se llena con el análisis y el contexto; por eso siempre tiene la misma forma y existe aunque el agente esté apagado.
| Parte | Líneas | Se llena con |
|---|---|---|
| El resumen | What happens, Where, Why, Do, Check | El análisis y los conteos del motor. Sin análisis, Why y Do se omiten y habla la evidencia |
| Evidencia | Stack, Before the failure, Trace, Release | El mismo contexto que tuvo el agente, antes de depurar: son tus datos, y van a tu propio agente |
| Reglas | Una lista corta | Texto fijo: el cambio más pequeño, agregar una prueba, no mezclar, cómo marcar el problema como resuelto |
Se arma cuando se pide, con GET /v1/problems/{problem}/prompt y con la herramienta MCP problem_prompt; nunca se guarda, y se corta a 12.000 caracteres con el mismo orden del contexto. La plantilla completa está en El prompt.
Pull requests Nube
El motor llega hasta el prompt. No tiene código que lea un repositorio ni que escriba en uno.
En Sypnia Cloud, la parte privada escucha el mismo evento problem.analyzed que recibe tu webhook. Cuando un proyecto tiene instalada la GitHub App de Sypnia y alguien pide un arreglo, o el proyecto pidió uno para cada problema con confianza high o medium, un worker aparte:
- lee los archivos que señala el análisis, a través de la GitHub App, con los permisos listados en La GitHub App;
- escribe el cambio y una prueba en una rama
sypnia/<problem slug>; - abre un pull request que lleva la frase, la causa y su evidencia;
- se detiene. Una persona revisa y mezcla.
Su estado es el objeto pull_request del problema: queued, writing, open, merged, closed o failed. En un motor propio ese campo siempre es null, y el camino al arreglo es el prompt o el servidor MCP con tu propio agente de código.
Sugerencias semanales
El mismo proveedor y el mismo patrón sirven para un trabajo más: los lunes a las 07:00 UTC, reglas fijas sobre los números de la semana encuentran páginas y rutas que vale la pena mejorar, y una llamada al modelo por página con hallazgos los pone en palabras simples. Envía conteos, rutas, selectores y etiquetas estables, nunca personas ni sesiones. Sin proveedor, las reglas corren igual. Con ai.weekly_suggestions en false quedan las reglas y no se hace ninguna llamada.
Qué cambió frente al sistema del que sale
| Allá | Aquí | Por qué |
|---|---|---|
| Una tarea semanal que analizaba módulos y escribía hallazgos | La misma idea queda como sugerencias semanales; y un análisis nuevo por problema dentro de los 2 minutos | La promesa del producto es una frase sobre un problema, cuando ocurre |
| Un proveedor, escrito dentro de la tarea | Un trait, cinco maneras de conectarse, apagado por defecto | Brief §5b: el proveedor de IA es una pieza que tú eliges |
| Un tope de costo por corrida, en dinero | Límites en llamadas por día y caracteres por llamada | El motor no puede conocer los precios de cada proveedor |
| Hallazgos en un solo idioma fijo | El idioma del proyecto (ai.language) | Cualquier equipo |
Sigue
- El mismo proceso, para quien lee el resultado.
- Cada manera de conectar un modelo, y exactamente qué sale.
- Dónde corre el agente en AWS y en un solo proceso.