# 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.

Applies to: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/architecture/agent-pipeline/

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](https://docs.sypnia.com/agent/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.

> **Note: About the code and the numbers**
>
> The Rust here is a design excerpt; the repository opens at launch. Sizes and limits are the ones on [Limits](https://docs.sypnia.com/agent/limits). Times are budgets. No model is named, on purpose: the engine works with any model that follows instructions and answers in JSON.

## The whole pipeline

**Figure (diagram not drawn yet)**: One analysis. The model is one message of eleven; everything around it is the engine following fixed rules.

It will show: SEQUENCE DIAGRAM with six vertical lifelines, left to right: «Fast path», «Postgres», «The agent», «Bucket», «AI provider» (drawn with a dashed outline and the tag «yours: off until you set a key»), «Alerts». A seconds ruler runs down the left edge marked 0 s, 5 s, 60 s, 100 s. Messages top to bottom, numbered: 1. Fast path → Postgres: «problem born · alert problem.new held, release_by = +100 s · job queued» (one transaction; draw a small bracket «one transaction»). 2. Fast path → The agent: «wake» (dashed). 3. The agent → Postgres: «claim the job; read the problem, counts, release». 4. The agent → Bucket: «source maps of 4f2a91c; the session file; the trace's segment». 5. The agent self-note box: «Collect → symbolicate → Redact → fit to 24,000 characters» with the tag «no model yet». 6. The agent → AI provider: «one request: instructions + context as JSON» ; this arrow is the lit element. 7. AI provider → The agent: «JSON answer». 8. The agent self-note box: «Check against the context · fill the numbers · set confidence by rule». 9. The agent → Postgres: «analysis = ready · slug = pay-button-does-nothing · usage +1». 10. The agent → Alerts: «release the alert, with the sentence». 11. Alerts → (off the right edge) labelled «record + signed webhook». Below message 11 a dashed alternative lane labelled «If the model is slow»: at the 100 s mark an arrow Postgres → Alerts labelled «release_by reached: release with the technical title», and a later arrow The agent → Postgres labelled «the sentence arrives on the problem; webhook problem.analyzed». A bracket on the right spanning messages 3 to 10 labelled «budget: 60 s, or what is left of the 100». Numbered callouts are the message numbers.

## 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](https://docs.sypnia.com/architecture/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.

**Figure (diagram not drawn yet)**: When the context is too long, it loses its least useful end first. The failure, its impact and the stack are never cut.

It will show: STACKED HORIZONTAL BAR DIAGRAM titled «The context budget: about 24,000 characters». One long bar divided into six segments, left to right, in the order they are KEPT, with these exact labels inside or under each segment: 1 «Failure and impact · always whole»; 2 «Stack: 8 frames × 11 lines»; 3 «Trace: up to 40 spans»; 4 «Release: commits and changed file names»; 5 «Breadcrumbs: up to 30»; 6 «Diffs: up to 10 files». Segment widths roughly 6 %, 22 %, 12 %, 8 %, 12 %, 40 %. Above the bar, an arrow pointing LEFT from the right end, labelled «cut from this end first», covering segments 6, then 5, then 3; this arrow is the lit element. Under segment 6 a note: «diffs of files that are not in the stack go first». Under segment 5: «oldest breadcrumbs go first». Under segment 3: «spans that did not fail and are not parents of one that did go first». Under segments 1 and 2 a bracket labelled «never cut». At the far right, outside the bar, a small tag «what was cut is listed in the context, so the model knows». Numbered callouts (1) to (6) on the segments.

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.

`crates/sypnia-agent/src/context.rs`

```rust
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.

`crates/sypnia-agent/src/provider.rs`

```rust
/// 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](https://docs.sypnia.com/agent/models-and-what-is-sent).

|                        | Sypnia engine (open source, self-hosted)                                   | Sypnia Cloud (paid 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

`what the model must return`

```json
{
  "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.
- **`cause` may be `null`.** 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.

`crates/sypnia-agent/src/check.rs`

```rust
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:

1. `problems.analysis` gets the analysis as the API returns it, with the provider, the model, the time and the run number.
2. On the first analysis, the problem gets its readable slug, made from the sentence. The old slug keeps working.
3. `analyses` gets one row: the input hash, the token counts, the outcome. Not the context and not the answer.
4. `usage_daily.analyses` goes 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](https://docs.sypnia.com/agent/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:

1. reads the files the analysis blames, through the GitHub App, with the permissions listed on [The GitHub App](https://docs.sypnia.com/cloud/github-app);
2. writes the change and a test on a branch `sypnia/<problem slug>`;
3. opens a pull request that carries the sentence, the cause and its evidence;
4. 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
