The agent's pipeline
How the engine analyses a problem, from the trigger and the context it builds to the provider call, the checked answer, the alert it releases and the prompt, with what is cached, what is limited and what only Sypnia Cloud adds.
On this page
- The whole pipeline
- Triggers and debouncing
- Step 1: collect
- Step 2: redact, then fit
- Step 3: ask
- The provider abstraction
- The answer it must return
- Step 4: check
- Step 5: write, and release the alert
- Cost limits and what is cached
- The prompt
- Pull requests
- Weekly suggestions
- What changed from the system this comes from
- Next
The agent is the part of the engine that reads a problem and writes one sentence about it. This page is how it is built. What it reads and writes, from the reader’s side, is in How the analysis works.
Two facts frame everything here. The agent is off by default in the engine: with ai.provider set to none it makes no call and sends nothing anywhere. And it is mostly not a model: of the five steps, four are fixed rules written in Rust, and one is a single call to a model that has no tools.
The whole pipeline
Triggers and debouncing
A job is a row. The fast path inserts it in the same transaction that records the transition, so a problem cannot be born without its job, and a retry cannot create two.
| Trigger | Inserted by | When |
|---|---|---|
| The problem is new | The fast path | The Born transition |
| The problem came back | The fast path | The CameBack transition |
| The problem grows | The fast path | It reaches twice the people it had at its last analysis; or it is first seen in a newer release |
| You ask | The API | POST /v1/problems/{problem}/analyze, at most 10 a minute per token |
| Skipped yesterday | The first pass of the day | Open problems whose status is limit_reached, those that hit the most people first |
Before a job runs, four gates, in this order. Each one that closes writes its reason on the problem, so the absence of a sentence is never silent.
| Gate | If closed | analysis.status |
|---|---|---|
| A provider is configured and the project has the agent on | Nothing runs, nothing is sent | off |
| The problem is not ignored | The job is dropped | unchanged |
The problem has fewer than 3 analyses today (ai.max_analyses_per_problem_per_day) | The job is dropped | unchanged; the last analysis stays |
The project has fewer than 100 analyses today (ai.max_analyses_per_day) | The job is kept for tomorrow | limit_reached |
Debouncing. A problem that explodes can grow three times in a minute. Three rules keep that to one call:
- One job per problem. The jobs table has a unique index on the problem for jobs that are not finished. A second trigger while one is waiting or running does not insert; it sets a flag on the existing job.
- Run again at most once. When a job finishes and its flag is set, it runs once more, with the newest counts, if the limits still allow.
- No call for the same input. The redacted context is hashed. If the hash equals the one stored with the last analysis, the stored analysis is kept and no call is made. This is what makes «Analyse again» free when nothing changed.
Step 1: collect
The agent studies one occurrence: the latest one that has both a trace and a session. From it the engine builds exactly what GET /v1/problems/{problem}/context returns.
| Part | Read from | Fixed size |
|---|---|---|
| The grouped failure | problems: kind, title, the sample occurrence | — |
| The stack with source lines | sample.stack_original; the source lines come from the source map’s own sourcesContent | 8 frames of your code, 5 lines on each side |
| Breadcrumbs | The session file in the Bucket, events before the failure | 30 |
| The trace | The segment named by traces.segment, the lines of that trace id | 40 spans, the failing ones and their parents first |
| The release and what changed | releases: when it was first seen, commits, changed files, diffs if you sent them | 10 files, 20,000 characters of diff |
| The impact | problems, problem_hits, problem_occurrences | — |
Symbolication runs here, before anything else, because the stack in your own files is the most useful part of the context. Problem grouping describes it.
If a part cannot be built, it is null and missing says why: source_maps_not_uploaded, no_session, no_trace, release_unknown. The agent works with what there is.
Step 2: redact, then fit
Redaction is a function from the full context to a smaller one. It is applied before the size budget, so nothing that must not leave can survive by being «important».
| Removed or replaced | By |
|---|---|
| Person ids, names, e-mails, account ids and names | «person 1», «person 2», in order of first appearance |
| Session ids, trace ids, span ids, device ids | Short local labels («session A»); the engine puts the real ids back into the result |
| Labels of clicked list rows, table cells and free text | Their kind: «a row», «a cell» |
| Things that look like secrets in messages and paths: long tokens, keys, e-mail addresses, long numbers | A marker of their kind |
| The project’s name and slug | Nothing |
With ai.send_source set to false: source lines and diffs | Nothing. File names, lines and function names stay |
Three things cannot be redacted because they are never there: what a person typed, anything inside a masked element, and replay content. The SDK does not collect the first two, and the agent never opens a replay chunk.
Then the context is fitted to about 24,000 characters.
Notice in the excerpt that redact returns a different type from the one it receives. Code that calls a provider can only be given a Redacted context, so sending an unredacted one does not compile.
pub async fn build_context(engine: &Engine, problem: &Problem) -> Result<AgentInput, AgentError> {
// The latest occurrence that has both a trace and a session; else the latest.
let occurrence = occurrences::pick(engine, problem).await?;
// What GET /v1/problems/{problem}/context returns: stack, breadcrumbs, trace, release, impact.
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(); // never fails the analysis
}
// People become «person 1»; ids, names and e-mails go; secrets in text are cut.
let mut redacted: Redacted<ProblemContext> = redact(full, &engine.config.ai);
// Cut from the least useful end until it fits. Each cut is written down for the model.
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()), // the same input twice is one call
restore: redacted.restore_map(), // «session A» → the real id, for the result
facts: Facts::from(&redacted), // what the answer will be checked against
json,
})
}Step 3: ask
One request. The instructions are fixed text that ships with the engine; the context goes as JSON in the user message; the answer must be JSON of a fixed shape. The model has no tools: it cannot browse, run code or ask for more.
The provider abstraction
The engine knows a model only through one trait. Notice how small it is: text in, text out, and the token counts for the usage counters. Everything that knows about problems is on the engine’s side of it.
/// The one thing the engine needs from a model. Implemented once per wire format.
#[async_trait]
pub trait AiProvider: Send + Sync {
/// As configured: "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, // fixed text, shipped with the engine
pub input: String, // the redacted context, as JSON
pub schema: &'static JsonSchema, // sent to providers that can enforce a JSON shape
pub max_output_tokens: u32, // `ai.max_output_tokens`, 2,000 by default
pub timeout: Duration, // `ai.timeout_seconds`, or less when an alert is due
}
pub struct Completion {
pub text: String,
pub model: String, // as the provider names it; stored with the analysis
pub tokens_in: u32,
pub tokens_out: u32,
}
/// Built once at start. `None` is the default: the agent is off and nothing is ever sent.
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, the OpenAI API, Google's OpenAI-compatible endpoint and any other
// endpoint that speaks chat completions share one implementation and differ by base URL.
Provider::OpenRouter | Provider::OpenAi | Provider::Google | Provider::OpenAiCompatible => {
Some(Arc::new(ChatCompletions::new(ai)?))
}
})
}ai.provider | Implementation | Default base URL |
|---|---|---|
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 | None: ai.base_url is required |
anthropic | AnthropicMessages | https://api.anthropic.com |
Five ways to connect, two implementations. Adding a provider with a third wire format is one file that implements the trait. The settings and how to check each one are on Models and what is sent.
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Which model | The one you name in ai.model. The engine has no default model, on purpose. | Chosen by Sypnia, reached through OpenRouter, and changed when a better one appears. |
| Whose key | Yours. Until you set one, the agent is off. | Sypnia's. Nothing to configure. |
| Where the context goes | From your engine to your provider. Nothing goes to Sypnia. | From Sypnia Cloud to the provider. |
The answer it must return
{
"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."
}Three things about this shape are deliberate.
- No numbers of its own. The model writes
{people},{sessions},{occurrences},{when}and{release_when}; the engine fills them from its counts. «3 people» is never a model’s arithmetic. - No confidence. The model is not asked how sure it is. Confidence is set by rule in the next step.
causemay benull. The instructions say that naming no cause is a correct answer when the facts do not support one.
Step 4: check
The answer is parsed strictly, then checked against the Facts kept in step 2. Notice that the function below never repairs an answer. It accepts it, or says exactly what is wrong.
pub fn check(answer: &ModelAnswer, facts: &Facts) -> Result<Checked, Vec<Rejection>> {
let mut rejections = Vec::new();
if let Some(cause) = &answer.cause {
// The place it blames must be a frame of the stack or a file the release changed.
if !facts.has_frame(&cause.blames) && !facts.release_changed(&cause.blames) {
rejections.push(Rejection::BlamesUnknownPlace(cause.blames.clone()));
}
// One to six pieces of evidence, each pointing at something that is in the context.
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()));
}
}
}
// A count written as a digit instead of a placeholder is a count the engine cannot vouch for.
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(),
})
}| Outcome | What the engine does | analysis.status |
|---|---|---|
| The answer passes | Fills the placeholders, puts the real ids back, sets the confidence | ready |
The answer passes and cause is null | Keeps the sentence, who, doing and since; lists what was missing | not_enough_evidence |
| The answer fails a check | Asks once more, with the rejections added to the request | — |
| It fails again | Drops the cause, keeps what passed | not_enough_evidence |
| The call fails or times out | Tries again, twice more, with a short wait | — |
| Three failed calls | Stops. It is tried again when the problem grows | failed |
A wrong cause stated with confidence costs more than no cause. That is why the unhappy paths end in «not enough evidence» and never in a guess.
Confidence by rule:
| Level | Rule |
|---|---|
high | At least two kinds of evidence agree, and one of them is a change in the release that touches the code where it fails |
medium | The cause rests on the stack or the trace alone, with source lines |
low | The cause fits the facts and nothing confirms it: a minified stack, or no release information |
Step 5: write, and release the alert
One transaction:
problems.analysisgets the analysis as the API returns it, with the provider, the model, the time and the run number.- On the first analysis, the problem gets its readable slug, made from the sentence. The old slug keeps working.
analysesgets one row: the input hash, the token counts, the outcome. Not the context and not the answer.usage_daily.analysesgoes up by one.
Then two things leave the engine: the problem.analyzed webhook, and the alert.
The alert hand-off. The alert was written by the fast path with released_at empty and release_by set to 100 seconds after the failure reached ingest. Whoever gets there first releases it:
| Who | When | The alert’s title |
|---|---|---|
| The agent | The analysis is ready or not_enough_evidence before release_by | The sentence |
| The agent | The model has not answered at release_by: the agent stops waiting, releases, and keeps the call running | The technical title |
| The fast path | The agent is off, or a gate closed | The technical title, at once |
| The pass | Safety net: any alert past release_by that nobody released | The technical title |
Releasing is one UPDATE … WHERE released_at IS NULL, so two of them racing release it once.
Cost limits and what is cached
| What | Rule |
|---|---|
| Calls a day, per project | 100 by default (ai.max_analyses_per_day); 0 is no limit. An usage.limit alert at 80 % and at 100 % |
| Calls a day, per problem | 3 (ai.max_analyses_per_problem_per_day) |
| Input | About 24,000 characters, a few thousand tokens |
| Output | 2,000 tokens (ai.max_output_tokens) |
| Calls per analysis | 1 normally; 2 when the first answer fails the check; never more than 3 including failed calls |
| Same input | No call: the input_hash matches the last analysis |
| Source maps | Parsed maps are cached in memory: 50 maps or 200 MB |
| The context | Not stored. It is rebuilt when asked for, from the Bucket and Postgres |
The engine records tokens, not money: it does not know your provider’s prices. The arithmetic is yours: one analysis is a few thousand tokens in and at most two thousand out, and a project makes at most 100 a day. Set a spending limit on the key at your provider as well; the engine’s limit counts calls, not what they cost.
The prompt
The prompt for a coding agent is not written by a model. It is a fixed template filled from the analysis and the context, which is why it always has the same shape and exists even when the agent is off.
| Part | Lines | Filled from |
|---|---|---|
| The brief | What happens, Where, Why, Do, Check | The analysis and the engine’s counts. Without an analysis, Why and Do are left out and the evidence speaks |
| Evidence | Stack, Before the failure, Trace, Release | The same context the agent had, before redaction: it is your data, going to your own agent |
| Rules | A short list | Fixed text: smallest change, add a test, do not merge, how to mark the problem resolved |
It is built when it is asked for, by GET /v1/problems/{problem}/prompt and by the MCP tool problem_prompt, never stored, and cut to 12,000 characters with the same order as the context. The full template is on The prompt.
Pull requests Cloud
The engine stops at the prompt. It has no code that reads a repository, and none that writes to one.
On Sypnia Cloud, the private part listens for the same problem.analyzed event your webhook gets. When a project has the Sypnia GitHub App installed and someone asks for a fix, or the project asked for one on every problem with high or medium confidence, a separate worker:
- reads the files the analysis blames, through the GitHub App, with the permissions listed on The GitHub App;
- writes the change and a test on a branch
sypnia/<problem slug>; - opens a pull request that carries the sentence, the cause and its evidence;
- stops. A person reviews and merges.
Its state is the pull_request object on the problem: queued, writing, open, merged, closed or failed. On a self-hosted engine that field is always null, and the way to a fix is the prompt or the MCP server with your own coding agent.
Weekly suggestions
The same provider and the same pattern serve one more job: on Monday at 07:00 UTC, fixed rules over the week’s numbers find pages and routes worth improving, and one model call per page with findings puts them into plain words. It sends counts, routes, selectors and stable labels, never people or sessions. With no provider, the rules still run. ai.weekly_suggestions set to false keeps the rules and makes no call.
What changed from the system this comes from
| There | Here | Why |
|---|---|---|
| A weekly job that analysed modules and wrote findings | The same idea kept as weekly suggestions; and a new per-problem analysis within the 2 minutes | The product’s promise is a sentence about a problem, when it happens |
| One provider, written into the job | A trait, five ways to connect, off by default | Brief §5b: the AI provider is a piece you choose |
| A cost cap per run in money | Limits in calls per day and characters per call | The engine cannot know every provider’s prices |
| Findings in one fixed language | The language of the project (ai.language) | Any team |
Next
- The same pipeline, for someone who reads the result.
- Each way to connect a model, and exactly what leaves.
- Where the agent runs on AWS and in one process.