# Best practices

A focused list of recommendations distilled from real workflows running on Systalink Agent Builder. They are short on theory and long on what saves you time, money, and 2 a.m. pages.

## Start small, iterate

Build the smallest useful version first — a single Agent node that takes an input and returns text. Run it. Read the output. Only then add the next node.

Common trap: starting with five branches, two loops, and a RAG node. You will not know which one is broken when the output is wrong.

- Drop one node, wire input → output, run.
- Add the next node, run again.
- Commit (save) after each green run — versioning kicks in automatically.

## Test with the chat preview before publishing

Every workflow editor ships with a built-in chat panel on the right. Use it. It feeds your workflow a real `input`, runs the full graph, and renders the last output exactly the way a published surface would.

- Cheaper than re-deploying through the API.
- Streams tool calls — you see *which* tool fired and *what* it returned.
- No credentials, rate limits, or share tokens needed.

If it doesn't work in the preview, it will not work in production.

## Prefer structured output when chaining Agents

When an Agent feeds another node (another Agent, a Transform, an If/Else), set its **output type** to `JSON schema` and define the fields you actually consume downstream.

```json
{
  "type": "object",
  "properties": {
    "intent":     { "type": "string", "enum": ["refund", "shipping", "other"] },
    "urgency":    { "type": "integer", "minimum": 1, "maximum": 5 },
    "customer_id": { "type": "string" }
  },
  "required": ["intent", "urgency"]
}
```

Why: free-form text downstream means brittle string parsing, "the model forgot the JSON braces today", and silent failures. A schema is enforced server-side — the run errors loudly if the model misbehaves.

A second payoff: the schema feeds the editor's assistance. Classify pre-selects the field and pre-fills its categories from the enum, If/Else suggests typed operators and ready-made `field == 'value'` expressions, and the `{`-autocomplete offers `{outputs.<id>.parsed.<field>}` paths in every templated field.

## Let the autocomplete write your placeholders

Don't type template paths from memory. In any templated field (prompts, URLs, bodies, email fields…), **type `{`** and pick from the dropdown — it only lists variables that actually exist upstream of that node, so typos like `{outputs.agent1.parsed.emial}` never happen. The **`{}` icon** in the config panel shows the full "available input data" reference with copyable paths.

Every node exposes a structured output too — `{outputs.<id>.parsed.url}` for Generate file, `.parsed.safe` for Guardrails, `.parsed.branch` for If/Else, etc. See the per-node table in [Concepts](#/docs/concepts).

## Run Workflow Doctor before large edits

Before refactoring an older workflow, run **Workflow Doctor** from the editor. It checks compatibility without changing the graph, including node types that are marked as deprecated in the node registry.

- Deprecated nodes are reported as compatibility warnings.
- When a replacement is known, Workflow Doctor proposes a migration action.
- Use the replacement for new work instead of adding another deprecated node.

## Keep system prompts focused: 1 role, 1 task

A 4-paragraph system prompt that asks an Agent to "classify, summarize, translate, and call the right tool" will do all four badly. Split it into a Classify node followed by specialized Agents.

Rule of thumb: if you can't describe the agent's job in one sentence, it's doing too much.

## Validate triggers with "Fetch real event"

Every trigger (Webhook, Schedule, Gmail, Notion) has a **Fetch real event** button. Click it before publishing. It pulls a real recent payload — actual headers, actual JSON, actual field names — and pins it as the editor's test fixture.

This catches the classic *"I templated `{event.body.email}` but the field is actually `{event.body.from.email}`"* bug in 5 seconds instead of 50 minutes of production debugging.

## Use the credentials store — never paste secrets into placeholders

The credential store encrypts secrets at rest and only decrypts them at runtime, during execution. Pasting an API key into a node field as plaintext means the secret lives in your workflow JSON, your version history, your marketplace listing, and any logs that dump node config.

- Create the credential once → reference it by name in every node.
- Rotate it in one place.
- Marketplace listings never carry it.

## Sandbox-only for risky tools

The **Shell** and **Code Interpreter** tools execute model-generated code (an LLM is, for these purposes, untrusted). They always run inside an isolated sandbox enforced by the platform — there's nothing for you to configure.

- Every run is isolated: no host filesystem access, ephemeral environment.
- Network egress is restricted by default — keep it that way unless a step truly needs a specific host.
- Never paste secrets into a Shell/Code step — reference a credential instead.

## Set timeouts and max iterations on While loops

A While node with no exit condition is a billing incident. Always set:

- **Max iterations** (`maxIterations`) — hard ceiling, even if the condition stays true.
- **Per-iteration timeout** — bail the body if a single pass hangs.
- An explicit, model-readable exit condition (don't rely on "the agent will know when to stop").

The same applies at the workflow level — set **Execution timeout** in the agent's Production space → **Settings**. A run that exceeds it fails loudly instead of burning credits silently.

## Version your workflow — and use the history

Every save creates a version. You don't have to do anything. What you *should* do:

- **Label** important versions ("before refactor", "prod 2026-05", "demo for acme").
- **Preview** any older version's JSON before restoring — confirms it's what you remember.
- **Restore** creates a new version with the old graph; the current one is never lost.

Treat it like git: small, frequent saves with clear labels beat one big save per day.

## Reuse from the marketplace

Before building from scratch, search the marketplace. Common patterns — RAG-over-docs, lead qualifier, daily digest, CSV → email summary — are already there. Install creates an editable copy in your account. You re-wire credentials, tweak the prompts, ship.

If you build something generally useful, publish it back. Only the graph ships — credentials and deployment config stay private.

---

*Source: https://agentbuilder.systalink.sn/docs/best-practices — human documentation.*
*Other language: [/docs-md/fr/best-practices.md](/docs-md/fr/best-practices.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*