# Concepts Bento routes incoming events to AI agents and manages their execution. This page defines the core concepts. ## Agents An **agent** is a persona defined in `agents//PERSONA.md`: voice, judgment, and standards for a class of tasks. ## Skills A **skill** is a procedure defined in `skills//SKILL.md`: steps, output format, and task-specific instructions. Bento uses the same skill definition as [Claude Code](https://code.claude.com/docs/en/skills) and the [Anthropic platform](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) — any skill that works there works here. Agents and skills are composable: one agent can run multiple skills, and one skill can run under multiple agents. Concrete example: a `reviewer` agent has a single persona — reads code critically, cites specifics, does not hedge. That same persona runs two different skills: * `review` — read the checked-out repo, assess merge readiness, post a GitHub review with inline comments. * `pr-comment-review` — evaluate a single reviewer comment against `HEAD`, form a position, emit a structured reply. The skill differentiates whole-PR review from comment reply. ## Tools Tools are callable functions available to an agent during a run. The orchestrator has built-in tools for generic task dispatch and bounded parallel dispatch. ## Capabilities A **capability** is a typed specialist operation selected by the orchestrator. It binds an input schema and output schema to an agent, optional skill, timeout, and `observer` or `actor` access tier. A pipeline registers the capabilities available for one invocation. The orchestrator composes capability calls from the request and intermediate results. It can route to one specialist, call specialists sequentially, dispatch independent calls in parallel, aggregate results, or repeat a generator/evaluator loop within the configured call and time limits. These execution patterns are not declared as a workflow graph. Capabilities differ from skills and companions: * Use a skill when one agent needs procedural instructions. * Use a companion when that same execution needs additional reference material. * Use a capability when an operation needs independent selection, schemas, authorization, execution, or tracing. Actor capabilities require actor access and an exact grant supplied by the trigger adapter. The orchestrator cannot create a grant. ## Pipelines A **pipeline** is a binding: when a trigger fires, run this agent with this skill, render this prompt, send output here. Each pipeline lives in its own file under `.bento/pipelines/`. Each pipeline has: * A **trigger** — what event fires it (a GitHub event, a Linear event, a cron schedule). * An **agent** — which persona runs. * A **skill** (optional) — which procedure the agent follows. * An **`instructions` directive** — the task text, with `{{event.*}}` substitutions filled in from the trigger payload. * An **output sink** — where the result goes (`github: comment`, `github: review`, `slack: "#channel"`, etc.). ```yaml # .bento/pipelines/pr-review.yaml trigger: github: - pull_request.opened - pull_request.synchronize agent: reviewer skill: agentic-review instructions: | Review PR #{{event.pull_request.number}} ("{{event.pull_request.title}}") on {{event.repository.full_name}} for merge readiness. ``` ```yaml # .bento/pipelines/deploy-notify.yaml trigger: github: - deployment_status filter: when: deployment_status.state: success agent: notifier instructions: | Announce deployment of {{event.deployment.ref}} to {{event.deployment.environment}}. output: slack: "#deploys" ``` ```yaml # .bento/pipelines/morning-standup.yaml trigger: schedule: "0 9 * * 1-5" # 09:00, Monday–Friday agent: notifier instructions: | Post a short summary of yesterday's merged PRs and open review requests. output: slack: "#standup" ``` Multiple pipelines can share the same agent or skill. A `filter:` block narrows which events a pipeline matches — useful for routing `@-mentioned` events to an editor agent while non-mentioned events go to the reviewer. ### Triggers A **trigger** is a signal that causes a pipeline to fire — a webhook payload, a cron tick, or an MCP tool call. A trigger matches exactly one pipeline and produces exactly one workload. See [Triggers](/triggers) for the full reference. ## The sandbox Every agent runs inside a container (podman or Docker). The daemon clones the target repo into the container, mounts credentials for git and GitHub auth, and spawns the agent CLI (`claude`, `codex`) inside. The agent never executes on the host. Agents run inside the container and can only affect what they have been explicitly given access to. If no sandbox is configured, the daemon refuses to spawn agents. Pipelines that need to commit, push, or post as the bot declare explicit credential mounts in `sandbox.mounts`: ```yaml sandbox: mounts: - host: ~/.config/gh container: /home/node/.config/gh - host: ~/.gitconfig container: /home/node/.gitconfig ``` Pipelines without those credential mounts cannot push commits or post as the bot — the agent runs but lacks the auth tokens to take those actions. To enforce read-only file access in the sandbox, set `guardrails.read_only: true` instead. ## Workspaces When a trigger names a repo-bearing target — a PR, a branch, a Linear issue with a linked repo — the daemon creates a persistent **workspace** directory for that target. The workspace accumulates state across triggers on the same target: * `checkout/` — the shared Git object cache and the per-run clones that borrow from it. * `notes.jsonl` — notes the agent wrote during prior runs. * `runs//meta.json` — trigger metadata and an optional one-line run result. * `runs//output.md` — the completed final reply. Multiple triggers on the same target share one workspace. A PR that receives three pushes gets three invocations in the same workspace. Subsequent prompts include notes and a compact index of prior runs. Each index row contains the run ID, age, trigger, and recorded result when present. Runs finalized before result persistence remain in the index without a result; Bento does not backfill them. Final replies remain daemon-side and are not injected into later prompts. Triggers that name no repo-bearing target (a cron job with no `repo:` declared, a knowledge-only MCP call) produce no workspace. ## The knowledge base At startup, the daemon indexes three directories from your project directory: * `wiki/` — reference material, runbooks, team context. * `blueprints/` — design patterns and architectural guidance. * `recipes/` — reusable how-to procedures. Each file carries YAML frontmatter with title, description, and tags used during indexing. The indexed content is served as MCP resources and queried via `bento ask` (the CLI search command). During the retrieve phase, relevant entries are pulled from the knowledge base and injected into the agent's context.