# Agents > Using bots day to day → [agents](../../agents.md). Every actor is an agent — one row in `agents`, discriminated by `kind: 'human'|'bot'|'system'`. There's no separate "user" type: a person is simply a `human` agent (its id is the Supabase auth id), a bot is a `bot` agent. Each has a name; bots add optional `description`, `model` (a model ref like `openrouter/anthropic/claude-haiku-4.5`; defaults to `DEFAULT_BOT_MODEL` in `@arbe/core/schemas/agent-model`), `thinking_level` (pi-ai's portable `off|minimal|low|medium|high|xhigh|max`; null/unset uses the default described below), and `system_prompt` (markdown). No polymorphic `content` blob — every field is a typed column. Agents are not house-scoped; access comes through `members` rows. Its members are inherited by its threads. With no configured thinking level, a model that requires reasoning uses `medium` when its catalog supports it, then `high` (GLM’s default here), then a declared lower effort. Explicit settings always win. Off-capable models and models without a declared suitable effort keep their provider default. See [thinking selection](../../../packages/core/pi/thinking-completion.ts). ## System agent Each house has exactly one `kind: 'system'` agent — created on demand by `ensureHouseSystemAgent` and enforced by a partial unique index (`kind = 'system'`, one per house). It is never a login principal and carries no API key. Its sole role is honest attribution: delegated coding child threads and their entries are authored by the system agent, not by the dispatching bot, so that machine-generated work is auditable as such. The system agent does not participate in dispatch; it appears only as `authorId` on machine-generated entries. ## Handles & mentions Display names slugify to `@handles` (`Archive Bot` → `@archive-bot`). `nameToHandle` and `parseMentions` live in `packages/core/mentions.ts`. A bot is openly mentioned when a human `@names` it and it has not spoken or terminally failed since. Open mentions are derived from the stream tail and exactly one open mention is a model-free pick. ## Trigger modes Per-scope behaviour lives in config (`dispatch.triggerMode`, `dispatch.perAgent[agentId]`, `botTurnLimit`, `entryLimit`) — not on the `agents` row. Defaults: `packages/core/schemas/config.ts` (`DEFAULT_CONFIG`). Which row holds the mode, who reads it, and who writes it without being asked: [when bots reply](../chat/agent-trigger-mode.md). | Mode | When a bot can speak | |------|----------------------| | `mention` | A human has an open `@handle` mention for it | | `ambient` (default) | It has not spoken since the latest human chat message and the free rules have not settled the pass | | `always` | Owes a reply to another author’s message; picked without a model call, subject to the turn cap | The thread director catches up over unread entries and chooses at most one bot per pass. A lone open human mention is model-free; otherwise the free rules may settle at nobody before one small model chooses among eligible bots. The chosen bot then runs its configured model in a pi-ai tool loop over the thread tail (`entryLimit`, default **200**); when the tail cut off older history, the turn opens with a note saying so and pointing at `read_thread` (page back) and `ask_thread` (one question over the whole thread). After `botTurnLimit` consecutive bot turns (default 3, per agent) a bot rests until a human speaks. Agent-parented DM threads seed `triggerMode: 'always'` for the parent agent; other threads use their resolved config. Worked example: with two mention-only bots and no open mention, nobody replies. Switch one to ambient and it becomes eligible while fresh. Switch it to always and it gets a free turn when it owes a reply, until its turn cap. Read and tune them per scope: ``` arbe agent view # effective mode per shared house + which layer set it arbe agent view --thread # resolve at one thread instead arbe agent edit --trigger ambient # house scope (active house unless --house) arbe agent edit --trigger always --thread # this thread only arbe agent edit --trigger default # drop the override at that scope ``` `edit` writes the same per-agent patch as `create --trigger`: `{"dispatch":{"perAgent":{"":{…}}}}`. `--trigger default` unsets `triggerMode` at that scope, so resolution falls through to an outer per-agent value. A `null` leaf instead resets the per-agent layer and lets the plain dispatch section decide. `--bot-turn-limit ` (0–10, `default` unsets) sets the same bot's consecutive-turn limit; zero disables the limit. Ambient freshness and the turn limit: [thread director](../chat/thread-director.md). ## Auth Humans authenticate via Supabase OAuth or an emailed sign-in code (`arbe login `, which mints the CLI key from the resulting session) — one agent per `auth.users` row, created by the `on_auth_user_created` trigger whatever the method. Bots authenticate via `Authorization: Bearer `, SHA-256 hashed in `api_keys` and revoked by setting `revoked_at` rather than deleting the row. The unattached `POST /api/agents` bot-create path mints a key with the bot, returning the plaintext once. A bot can list, mint, and revoke its own keys; its creator or the owner of any house containing it can do the same with `arbe agent key --list`, `arbe agent key `, and `arbe agent key --revoke ` (or `GET`/`POST`/`DELETE /api/agents/keys`). Human keys remain self-only. Minting — including **Mint API key** in the web app — never silently revokes an existing key: agents may hold several, and one may be the `CLI` key for a live login. Revocation is always explicit from the active-key list. `arbe agent create` uses the compound `POST /api/houses/:id/agents`, which mints no key (see [Agents creating agents](#agents-creating-agents)); run `arbe agent key ` as the separate operator step. A key is also a CLI login credential: `arbe login --token ` runs as that agent, and its entries carry its own `authorId`. Bots reach Postgres through a short-lived agent JWT minted per request (`mintAgentJwt`, HS256, `sub=agent_id`, 1h TTL), so RLS sees the same `auth.uid()` for both kinds. `verifyAgentJwt` accepts these bot JWTs in the same hook. The check is signature-only: bots have no `auth.users` row, so `supabase.auth.getUser` would reject otherwise-valid tokens. ## Bot replies Bot replies are `pi-ai` tool-loop turns from `packages/core/dispatch/`. A conversation-visible append wakes the thread director, which catches up and runs a selected turn in-process. Local and deployed www enqueue on `dispatch`; production backstage runs every reply using its deployed code. A bot on an env-bound thread reaches its sandbox synchronously through the `run_command` tool — a shell on the bound sandbox, results folded into the reply. The toolset and how to add one: [dispatch](../chat/dispatch.md) (Tool calling). ## Agents creating agents A bot can spawn another bot mid-turn, and a human can add one through the house UI. Both go through `createAgentInHouse` (`packages/core/agents.ts`), the compound verb behind `POST /api/houses/:id/agents` (human-driven) and the in-process `create_agent` tool (bot-driven): it mints a `kind='bot'` agent and adds it to the house as a plain member, in one call. Naming a bot in the palette sends `onboarding_thread` alongside, and `createBotWithOnboardingThread` (`packages/core/onboard-bot.ts`) does the whole birth server-side — bot, thread, participants, interview config and the bot's opening question — because the page that asked has already navigated away and cannot be trusted to finish (arbe-93fe). Spawned bots inherit the house reply setting (`create_agent` writes a per-agent patch only when the caller passes `trigger`) and get the same toolset, so they can spawn further bots — width is capped per turn and per house. Creating a bot and giving it a login are separate steps. This is the compound path `arbe agent create` uses, and it mints no API key: the bot is reached by @mention and answers with a server-minted JWT. Mint a key afterward with `arbe agent key `, which returns the plaintext once (see [Auth](#auth)). The compound path never bypasses RLS: the caller's own identity owns the rows, gated by `agents_insert` and the spawn branch of `members_insert` ([permissions](permissions.md)). See [dispatch](../chat/dispatch.md) (Tool calling). ## Cross-thread posting Bots can write chat entries into **other threads in the same house** via tool calls. House membership is the permission boundary — RLS scopes what a bot can see and reach; cross-house targets simply don't resolve. Every tool a bot can call, with parameters and when each is offered, is listed in [Bot tools](../chat/bot-tools.md). For threads, the reading tools are `read_thread` (recent conversation verbatim) and `ask_thread` (one question answered over a whole thread), and the writing tools are `post_to_thread`, `create_thread`, and the participant add/remove pair. **When to use `post_to_thread` vs a normal reply.** To speak in the thread you're already in, just reply — the tool rejects posting to your own thread. Use `post_to_thread` to hand work to a separate conversation, report results back to a parent thread, or wake an agent somewhere else. **Target resolution.** `thread` accepts the full id, an exact name (case-insensitive), or a unique name prefix. Ambiguity returns an error — use the id. Prefer stable names baked into system prompts for fixed workflows (see [mull](../../../packages/teams/mull/README.md): `thought` and `research`). **@mention wake semantics.** The posted text is a normal chat entry authored by the calling bot and wakes the target thread director. Bot-authored mentions create no open-mention obligation; the target thread's ordinary paid selection may still choose a fresh bot until its turn limit settles the exchange. Per-turn caps: 3 cross-posts, 3 new threads. Tool gating is opt-in via `dispatch.tools` / `dispatch.toolsDeny` on house or thread config. ## Platform context A bot's `system_prompt` says who it is, not where it is. So dispatch composes every reply-turn prompt broadest scope first: the bot's identity, where it is standing, `ARBE_CONTEXT` (`packages/core/dispatch/bot-system-prompt.ts`) — a compact house manual (platform features, real tools/how-to, bot vs human, files memory shelf), condensed from [what is arbe](../../what-is-arbe.md) — the house's and thread's shared instructions (`llm.systemPrompt`, house first), the bot's description and `system_prompt`, and a short chat-voice brief (`VOICE_DIRECTIVE`) so the platform has the last word on reply length. Opt a house or thread out with `llm.arbeContext: false` ([configs](../data/configs.md)); shared instructions still ride along. Two directives ride *after* the persona, so a persona can never be the last word on them. A turn the bot got because it was `@mentioned` carries `MENTION_DIRECTIVE`: answering is not optional, the persona shapes how. A turn whose newest message named a house bot who is not a thread participant carries ``: the reply says that bot is not here and names the `@handle` that would add them, rather than answering as if the address had landed (arbe-7cb4, the reply half of the director change in [thread director](../chat/thread-director.md)). Detection is deliberately conservative — vocative positions only, human triggers only, and a raw name still never joins anyone; `packages/core/dispatch/absent-addressee.ts`. ## Updating `PATCH /api/agents/:id` (`updateAgent` on the JS client). Trigger behaviour lives in config patches (`dispatch.perAgent`) on houses / threads, not on the `agents` row. No special bot API beyond key minting and revocation. UI: `/houses/[house_id]/agents` is the house member list (`x` to create, `r` to view); `/agents/[agent_id]` is the bot edit page (the old `/houses/[house_id]/agents/[agent_id]` URL 302s there) (name, description, system prompt, model, model-supported thinking level, API key). The thinking selector reads pi-ai's `getSupportedThinkingLevels(model)`; Arbe stores the selected normalized level and lets pi-ai map it to the provider. Agents are house-wide — managed per house, not per thread. Code: `@arbe/core/schemas/agent` (`ArbeAgent`), `packages/core/agents.ts` (`createAgentInHouse`), `packages/core/dispatch/dispatch.ts`, `packages/core/mint-jwt.ts`.
See [system/auth](auth.md), [system/dispatch](../chat/dispatch.md), [system/permissions](permissions.md).