# Best practices ## Start simple Begin with a single agent and omit the `orchestrator` field. Add explicit auto orchestration only once the work needs model-selected chaining or parallelization. ## Inspect before tuning Before you run a pipeline, inspect the input that the agent receives: ```bash bento trigger inspect --prompt # the user prompt bento trigger inspect --system-prompt # the assembled system prompt bento trigger inspect --size # token breakdown ``` Most output quality problems are prompt problems, visible before the agent runs. Once a trigger exists in the store, re-run it at any time without waiting for a real event: ```bash bento trigger replay ``` When a pipeline produces poor output, read the trace: ```bash bento trace ``` The trace shows each phase — trigger, invocation, spawn — with timing and status. Bento extracts the agent messages from the run log. ## Invest in the knowledge base before skills Before you add a skill, verify that `wiki/`, `blueprints/`, or `recipes/` contain the domain context that the agent needs. See [Knowledge Base](/knowledge-base). ## One skill per procedure A skill that does one specific thing is easier to tune, review, and reuse than one that branches across multiple cases. If a pipeline needs to do two different things depending on the trigger, write two pipelines — each with its own narrow skill. See [Context Engineering](/context-engineering). ## Start read-only, then enable write-back Before enabling a pipeline to post comments, push commits, or open PRs, run it without write credentials and review the output via `bento trace`. Add the credential mounts once you trust what the agent produces. ```yaml # start here — agent runs but cannot write back sandbox: mounts: [] # add mounts once output is verified sandbox: mounts: - host: ~/.config/gh container: /home/node/.config/gh ``` ## Always set a timeout An unbounded agent run consumes resources and blocks a queue slot. Declare a timeout in every pipeline: ```yaml guardrails: timeout: 300 # seconds ``` 300 seconds is a reasonable starting point. ## Scope credentials to the minimum Mount only what the pipeline actually needs. A review pipeline that posts comments does not need push access. A read-only analysis pipeline does not need any external credentials. See [Identity](/identity). ## Be intentional about workspace notes An agent calls the MCP `submit_note` tool during a run to pass durable state to the next invocation on the same target. Bento stores each structured note in the database, and a later run can retrieve a prior run's full record with MCP `get_run` or `bento invocation get-run `. This accumulates — stale notes from a prior run will influence future runs on the same workspace. Prune notes when a target's context has changed significantly (a PR was rebased, a ticket was reprioritized). Stale notes are worse than no notes. ## Review before you automate Run a new pipeline manually a few times via `bento trigger replay` and review each trace before letting it run unattended on real events. Verify: * The prompt contains the context you expect. * The agent's output is in scope. * Write-back (if any) produces the right artifact.