Agents

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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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).

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "method": "tools/call", "params": { "name": "composio_connection_check", "arguments": { "provider": "gmail" } } }

AI Operating Guide

Vertical Intelligence

Getting Started

Governance

Resources

Sales & Commerce

Procurement

Marketing & Outreach

Reads

`agent_list`

`agent_get`

`agent_versions_list`

`agent_version_get`

`agent_stats_get`

Writes

`agent_create`

`agent_update`

`agent_run`

Schedules

`agent_schedule_manage`

`agent_schedule_verify`

Runs

`agent_run_list`

`agent_run_get`

`agent_search_runs`

Integration connection checks

`composio_connection_list`

`composio_connection_check`

​Reads

​agent_list

​agent_get

​agent_versions_list

​agent_version_get

​agent_stats_get

​Writes

​agent_create

​agent_update

​agent_run

​Schedules

​agent_schedule_manage

​agent_schedule_verify

​Runs

​agent_run_list

​agent_run_get

​agent_search_runs

​Integration connection checks

​composio_connection_list

​composio_connection_check

Reads

`agent_list`

`agent_get`

`agent_versions_list`

`agent_version_get`

`agent_stats_get`

Writes

`agent_create`

`agent_update`

`agent_run`

Schedules

`agent_schedule_manage`

`agent_schedule_verify`

Runs

`agent_run_list`

`agent_run_get`

`agent_search_runs`

Integration connection checks

`composio_connection_list`

`composio_connection_check`