> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Agent CRUD, runs, schedules, version history, stats, and connection checks.

An **agent** is a configured AI worker: a briefing (system prompt), a mandate, a role in the hierarchy (worker / supervisor / ceo), tools, skills, schedule and delivery channels. Agent visibility follows the app rules — owner, department, or tenant scope.

The 15 agent tools cover **reads** (see an agent + its version history and stats), **writes** (create / patch), **running** (human-gated trigger), **schedules**, **runs** (list / read / search), and **integration connection checks**.

***

## Reads

### `agent_list`

List the agents this user can see.

| Name    | Type   | Required | Description                    |
| ------- | ------ | -------- | ------------------------------ |
| `limit` | number | no       | Max rows (default 50, max 200) |

**Returns:** `{ agents: [...], count }`. Each row carries `id, agent_name, display_name, department, department_id, role, model, phase, is_active, schedule, execution_type, mode, scope, owner_user_id, reports_to, created_at`. `schedule` is the **effective** schedule — the `schedule` column if set, else the enabled `trigger_config.schedule` cron (tagged `source:"trigger_config"`), else `null`.

**Permissions:** read; owner/department/tenant visibility.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_list", "arguments": { "limit": 20 } } }
```

### `agent_get`

Full configuration of one agent: briefing/prompt, model, trigger config, schedule, delivery, tools, skills and per-view data preferences (pinned columns, default filters, row cap).

| Name | Type   | Required | Description |
| ---- | ------ | -------- | ----------- |
| `id` | string | yes      | Agent uuid  |

**Returns:** `{ agent, mcp_servers, view_prefs }`. `agent` is the full detail record (all list columns plus `system_prompt, mandate, model_settings, trigger_config, delivery_channels, tools_access, knowledge_access, memory_filter, budget_limit, decision_bounds, delivery_webhooks, api_actions, alive_mode/alive_state/alive_heartbeat_at, avatar_*, billing_policy, max_credits_per_run, human_minutes_per_run, hourly_rate_usd`) with `schedule` resolved to the effective value. `mcp_servers` resolves each `mcp:<uuid>` grant to `{ref, label, enabled, read_only_tools}` (or a `status` marker `DEAD`/`UNVERIFIED` for refs whose server is gone or unreadable). `view_prefs` is the per-view pinned-column/filter/row-cap config. Missing or not-visible → `{ error: "Agent not found" }`.

**Permissions:** read; visibility-gated.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_get", "arguments": { "id": "<uuid>" } } }
```

### `agent_versions_list`

The agent's config-version history (before-edit snapshots): version number, kind (edit/promote/scope\_change), actor, timestamp and identifying snapshot fields. Restore stays UI-only.

| Name    | Type   | Required | Description                       |
| ------- | ------ | -------- | --------------------------------- |
| `id`    | string | yes      | Agent uuid                        |
| `limit` | number | no       | Max versions (default 20, max 50) |

**Returns:** `{ versions: [{version, kind, actor, created_at, name, model, role}], note }` — newest first. `name/model/role` are pulled from the before-snapshot as identifying fields; the full snapshot body is dropped here (use `agent_version_get` for it).

**Permissions:** read; visible only if you can see the agent.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_versions_list", "arguments": { "id": "<uuid>" } } }
```

### `agent_version_get`

One config version **with its full before-snapshot** — the read for the actual config behind a version row. Use it to answer "what changed between versions" or to inspect a config before restoring in the UI.

| Name      | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| `id`      | string | yes      | Agent uuid                                |
| `version` | number | yes      | Version number from `agent_versions_list` |

**Returns:** `{ version, kind, actor, created_at, snapshot, note }`. `snapshot` is the complete before-state config object for that version (empty object if the row stored none).

**Permissions:** read; visibility-gated.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_version_get", "arguments": { "id": "<uuid>", "version": 4 } } }
```

### `agent_stats_get`

Lifetime run stats for one agent over a day window: total runs, success rate, average duration, total cost USD — same aggregation as the app's Runs & Cost tab.

| Name   | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `id`   | string | yes      | Agent uuid                            |
| `days` | number | no       | Look-back window (default 30, max 90) |

**Returns:** `{ total, success_rate, avg_duration_sec, total_cost_usd, days }` — counts only completed (non-running) runs in the window; `success_rate` is a whole-number percent, `total_cost_usd` is rounded to 4 decimals.

**Permissions:** read; visibility-gated.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_stats_get", "arguments": { "id": "<uuid>", "days": 30 } } }
```

## Writes

### `agent_create`

Create a **complete** agent — briefing, mandate, hierarchy, skills, tools, schedule, delivery. Server-enforced rules: `agent_name` is `NN_lowercase_words` (e.g. `30_market_scanner`); `system_prompt` is a real briefing (min 80 chars); non-ceo agents report to the CEO by default; model defaults to the tenant's master setting.

| Name                           | Type      | Required | Description                                                                                                                                                                                                                |
| ------------------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_name`                   | string    | yes      | `NN_lowercase_words`, e.g. `30_market_scanner`                                                                                                                                                                             |
| `display_name`                 | string    | yes      | Display name                                                                                                                                                                                                               |
| `system_prompt`                | string    | yes      | The full briefing — role, flow, rules (min 80 chars)                                                                                                                                                                       |
| `mandate`                      | string    | yes      | What this agent owns                                                                                                                                                                                                       |
| `role`                         | string    | yes      | `worker` \| `supervisor` \| `ceo`                                                                                                                                                                                          |
| `reports_to`                   | string    | no       | Agent uuid; default = tenant CEO                                                                                                                                                                                           |
| `department_id` / `department` | string    | no       | Department by id or name                                                                                                                                                                                                   |
| `skills`                       | string\[] | no       | Skill slugs or uuids to preload (use `skill_list` first)                                                                                                                                                                   |
| `tools`                        | string\[] | no       | Capability grants, e.g. `mcp:<server-id>`, `composio:GMAIL_SEND_EMAIL` (validate with `grantable_list`)                                                                                                                    |
| `model`                        | string    | no       | Optional override; omit to use the tenant default                                                                                                                                                                          |
| `trigger_config`               | object    | no       | `{schedule:{enabled,cron,timezone?}, telegram:{enabled} (ceo only)}`                                                                                                                                                       |
| `delivery_channels`            | any       | no       | Delivery config (telegram/inbox), passed through                                                                                                                                                                           |
| `scope`                        | string    | no       | `private` \| `department`                                                                                                                                                                                                  |
| `is_active`                    | boolean   | no       | Active flag                                                                                                                                                                                                                |
| `digest`                       | object    | no       | Living-document config: `{enabled, key_var: user_id\|department_id\|channel_id\|custom, key_prefix, title_template?}` — deduplicates the agent's knowledge writes onto one document per key                                |
| `data_sources`                 | array     | no       | `[{view_slug, select_fields?, default_filters?, max_limit?}]` — grants `query_<table>` and sets the per-view column/filter/row-cap preferences in one call. Unknown columns are dropped and reported as `rejected_columns` |

**Returns:** `{ agent, skills_linked, data_sources_configured?, warnings?, note }`. `agent` is the inserted row projected to `id, agent_name, display_name, role, reports_to, department, is_active, trigger_config, model_settings`; `skills_linked` is the count of preload skills wired; `data_sources_configured` appears only when view-prefs were set; `warnings` collects non-fatal self-checks (e.g. unknown tool ref, `digest.enabled` without a knowledge-write tool). Validation problems return `{ error }` naming the exact field.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_create", "arguments": {
  "agent_name": "42_lead_qualifier",
  "display_name": "Lead Qualifier",
  "system_prompt": "You qualify inbound leads. For each new lead, check ... (full briefing)",
  "mandate": "Owns first-pass qualification of all inbound leads.",
  "role": "worker",
  "skills": ["lead-scoring"],
  "data_sources": [{ "view_slug": "linkedin_leads", "max_limit": 25 }]
} } }
```

### `agent_update`

Merge-patch an existing agent. Only supplied fields change. Supports `dry_run:true` for a field-level `from → to` preview without writing (no version snapshot, no skill relink).

| Name                                                   | Type            | Required | Description                                                                                                                                                                                                                              |
| ------------------------------------------------------ | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                   | string          | yes      | Agent uuid                                                                                                                                                                                                                               |
| `dry_run`                                              | boolean         | no       | Preview changes without committing                                                                                                                                                                                                       |
| `display_name`, `system_prompt`, `mandate`             | string          | no       | Core fields                                                                                                                                                                                                                              |
| `role`                                                 | string          | no       | `worker` \| `supervisor` \| `ceo`                                                                                                                                                                                                        |
| `reports_to`                                           | string          | no       | Supervisor agent uuid                                                                                                                                                                                                                    |
| `model_settings`                                       | object          | no       | Model settings object                                                                                                                                                                                                                    |
| `trigger_config`                                       | object          | no       | Schedule/telegram triggers (telegram only for the CEO)                                                                                                                                                                                   |
| `tools_access`                                         | string\[]       | no       | Capability grant list (mcp ids validated)                                                                                                                                                                                                |
| `view_prefs`                                           | array           | no       | `[{view_slug, select_fields?, default_filters?, max_limit?}]` — **replaces** the per-view data prefs for the listed views (whole-row replace per view; other views untouched). Requires the agent to already have `query_<slug>` granted |
| `memory_filter`                                        | object          | no       | `{scope: private\|department\|global, categories?, tags?}` — read scope + narrowing for memory/knowledge reads. `scope:'global'` is Company-Admin-only and audited (pass `scope_note`)                                                   |
| `scope_note`                                           | string          | no       | Audit reason when setting `memory_filter.scope='global'`                                                                                                                                                                                 |
| `skills`                                               | string\[]       | no       | **Replaces** the preload skill set (for one additive link use `skill_link`)                                                                                                                                                              |
| `is_active`                                            | boolean         | no       | Active flag                                                                                                                                                                                                                              |
| `scope`                                                | string          | no       | `private` \| `department`                                                                                                                                                                                                                |
| `department_id` / `department`                         | string          | no       | Department                                                                                                                                                                                                                               |
| `execution_type`                                       | string          | no       | `autonomous` \| `workflow`                                                                                                                                                                                                               |
| `delivery_channels`                                    | any             | no       | Delivery config                                                                                                                                                                                                                          |
| `digest`                                               | object          | no       | Living-document config (merged into model settings without clobbering other keys)                                                                                                                                                        |
| `phase`                                                | string          | no       | `active` \| `draft`                                                                                                                                                                                                                      |
| `knowledge_access`                                     | string          | no       | Coarse knowledge reach flag                                                                                                                                                                                                              |
| `budget_limit`                                         | number          | no       | Per-agent USD budget                                                                                                                                                                                                                     |
| `human_minutes_per_run`, `hourly_rate_usd`             | number          | no       | Savings baseline (human time a run replaces)                                                                                                                                                                                             |
| `decision_bounds`                                      | object          | no       | `{money_threshold_usd?, require_approval_money?, require_approval_irreversible?}`                                                                                                                                                        |
| `api_actions`                                          | array           | no       | Custom typed API tools: `[{name, method, url, credential_label?, body_template?}]`                                                                                                                                                       |
| `delivery_webhooks`                                    | array           | no       | Outbound delivery webhooks: `[{url, events[], headers?}]`                                                                                                                                                                                |
| `alive_mode`                                           | boolean         | no       | Always-on / continuous mode                                                                                                                                                                                                              |
| `avatar_face_slug`, `avatar_icon_slug`, `avatar_theme` | string          | no       | Avatar                                                                                                                                                                                                                                   |
| `billing_policy`, `max_credits_per_run`                | string / number | no       | **Superadmin only** (platform pricing)                                                                                                                                                                                                   |

Credential assignments (`allowed_credentials`) are deliberately **not** writable over MCP — manage credentials in the app.

**Returns:** live apply → `{ ok:true, updated: [changed keys], skills_replaced?, view_prefs_replaced?, warnings? }` (`updated` is the list of patched column names; `skills_replaced`/`view_prefs_replaced` are counts, present only when those were replaced). Dry-run → `{ dry_run:true, valid:true, would: { action:"update_agent", target_id, changes: {<field>:{from,to}}, skills_replaced?, view_prefs? }, warnings?, note }` — no write, no version snapshot, no skill relink.

**Permissions:** write; **Company-Admin only** (Superadmin for the pricing fields).

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_update", "arguments": {
  "id": "<uuid>", "dry_run": true, "mandate": "Now also owns re-engagement of cold leads."
} } }
```

### `agent_run`

Trigger an agent run from outside — **always through the human-in-the-loop gate**, never silently. Creates an approval (Telegram buttons when connected, otherwise the in-app approvals inbox); on approve, the tenant CEO delegates the run. Track it with `agent_run_list`. The CEO agent itself is triggered by talking to it, not here.

| Name    | Type   | Required | Description                      |
| ------- | ------ | -------- | -------------------------------- |
| `agent` | string | yes      | Target `agent_name` slug or uuid |
| `input` | string | yes      | The task for the agent           |

**Returns:** `{ status:"pending_approval", approval_id, channel, note }`. `channel` is `"telegram"` when the user has a connected chat + bot, otherwise `"inbox"` (approve via the app or `approval_resolve`). On approve, the CEO delegates the run — track it with `agent_run_list`. Guard failures return `{ error }` (e.g. inactive agent, no CEO, CEO lacks `spawn_agent`, or targeting the CEO itself).

**Permissions:** write; execution proceeds only after a human approves.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_run", "arguments": {
  "agent": "42_lead_qualifier", "input": "Qualify the 12 leads imported this morning."
} } }
```

## Schedules

### `agent_schedule_manage`

Enable/disable or change an agent's recurring schedule (5-field cron, timezone-aware — defaults to the user's timezone). Verify the first run fires via `agent_run_list` or `agent_schedule_verify`.

| Name       | Type    | Required | Description                                                        |
| ---------- | ------- | -------- | ------------------------------------------------------------------ |
| `id`       | string  | yes      | Agent uuid                                                         |
| `enabled`  | boolean | yes      | Turn the schedule on/off                                           |
| `cron`     | string  | no       | e.g. `0 9 * * 1` (Mondays 09:00)                                   |
| `timezone` | string  | no       | IANA tz, e.g. `Europe/Zurich`                                      |
| `dry_run`  | boolean | no       | Validate + preview the schedule change (from → to) without writing |

**Returns:** live apply → `{ ok:true, agent, schedule: {enabled, cron, rrule, timezone}, note }` (`agent` is the agent\_name). Dry-run → `{ dry_run:true, valid:true, would: { action:"manage_schedule", target_id, changes: {<field>:{from,to}} }, note }` — only actually-changing fields appear under `changes`.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_schedule_manage", "arguments": {
  "id": "<uuid>", "enabled": true, "cron": "0 9 * * 1", "timezone": "Europe/Zurich"
} } }
```

### `agent_schedule_verify`

Verify an agent's schedule actually **fires** (a stored cron is not proof): compares the configured schedule against the last scheduled run and returns a verdict.

| Name    | Type   | Required | Description                |
| ------- | ------ | -------- | -------------------------- |
| `agent` | string | yes      | Agent uuid or `agent_name` |

**Returns:** `{ agent, is_active, schedule: {enabled, cron, timezone}, last_scheduled_run, verdict, note }`. `verdict` is one of `ok | stale | never_fired | pending_first_window | agent_inactive | disabled`; `last_scheduled_run` is the newest `trigger_type=schedule` run row (`id, status, started_at, finished_at`) or `null`; `note` explains the verdict.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_schedule_verify", "arguments": { "agent": "42_lead_qualifier" } } }
```

## Runs

### `agent_run_list`

Recent agent runs (only for agents you can see): status, trigger type, duration, summary, errors.

| Name           | Type   | Required | Description                        |
| -------------- | ------ | -------- | ---------------------------------- |
| `agent`        | string | no       | Filter by agent (slug/uuid)        |
| `status`       | string | no       | `running` \| `success` \| `failed` |
| `trigger_type` | string | no       | `schedule` \| `manual` \| …        |
| `limit`        | number | no       | Max rows                           |

**Returns:** `{ runs: [...], count }`. Each row: `id, agent_id, agent_name, status, trigger_type, triggered_by, started_at, finished_at, duration_sec, summary, error_msg, parent_run_id, spawn_depth`. Runs are pre-filtered to agents you can see; if you can see none, `{ runs: [], count: 0 }`.

**Permissions:** read; agent visibility applies.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_run_list", "arguments": { "agent": "42_lead_qualifier", "status": "failed" } } }
```

### `agent_run_get`

One agent run in detail, including input and step receipts (tool calls, durations, errors).

| Name | Type   | Required | Description |
| ---- | ------ | -------- | ----------- |
| `id` | string | yes      | Run uuid    |

**Returns:** `{ run, steps }`. `run` carries the list-row columns plus `input_text`; `steps` is the ordered step trail (up to 100) of `{step_id, step_type, ok, duration_ms, error_msg, created_at}`. Missing or not-visible → `{ error: "Run not found" }`.

**Permissions:** read; agent visibility applies.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_run_get", "arguments": { "id": "<uuid>" } } }
```

### `agent_search_runs`

Full-text search your own past runs by term — recall what an agent did before. Returns matched runs with a snippet + run id (fetch the full run with `agent_run_get`). Use for past-run recall; use `memory_search` for stored facts and `knowledge_search` for the knowledge base.

| Name     | Type   | Required | Description                                           |
| -------- | ------ | -------- | ----------------------------------------------------- |
| `search` | string | yes      | Free-text term over run summary, input and agent name |
| `agent`  | string | no       | Narrow to one agent (slug or uuid)                    |
| `status` | string | no       | `running` \| `success` \| `failed`                    |
| `limit`  | number | no       | Max rows (default 25, max 100)                        |

**Returns:** `{ runs: [{id, agent_id, agent_name, status, trigger_type, started_at, duration_sec, snippet}], count, fts }`. `snippet` is a \~240-char window around the first hit; `fts` is `true` when the Postgres full-text index served the query, `false` when it fell back to `ILIKE`.

**Permissions:** read; tenant + agent visibility.

```json theme={null}
{ "method": "tools/call", "params": { "name": "agent_search_runs", "arguments": { "search": "quarterly pricing review" } } }
```

## Integration connection checks

Third-party integrations (Gmail, Slack, …) are connected per user via OAuth **in the app UI only** — no connect tool exists by design (secrets and OAuth flows never travel the LLM channel). These reads let you verify a connection before granting `composio:*` tools to an agent.

### `composio_connection_list`

List the authenticated user's third-party integration connections: provider, status, account id and timestamps.

| Name       | Type   | Required | Description                                        |
| ---------- | ------ | -------- | -------------------------------------------------- |
| `provider` | string | no       | Lowercase toolkit slug, e.g. `gmail`, `slack`      |
| `status`   | string | no       | `active` \| `pending` \| `error` \| `disconnected` |
| `limit`    | number | no       | Max rows (default 50, max 200)                     |

**Returns:** `{ connections: [{id, provider, status, composio_account_id, created_at, connected_at, last_used_at}], count }`. Internal entity ids (composio\_user\_id) are never exposed.

**Permissions:** read; own connections only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "composio_connection_list", "arguments": { "provider": "gmail" } } }
```

### `composio_connection_check`

Check whether the user has an **active** connection for a specific provider. Returns `connected:true` only when the status is active and the OAuth handshake completed.

| Name       | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `provider` | string | yes      | Lowercase toolkit slug, e.g. `gmail` |

**Returns:** `{ provider, connected, status }` — `connected:true` only when the newest connection is `status:"active"` **and** the OAuth handshake completed (`composio_account_id` set). When no connection exists: `{ provider, connected:false, status:null, hint }`.

**Permissions:** read; own connections only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "composio_connection_check", "arguments": { "provider": "gmail" } } }
```