# Agents — tool reference

Generated from the OpenAPI document (`https://maison-labs.com/api/v1/openapi.json`). Field types are JSON Schema types; GET/DELETE inputs travel as path or query, other methods as a JSON body.

## `create_agent` — Create ledger agent

Create a ledger agent for a hotel. It is saved disabled unless `enabled: true` (dry-run it with `test_agent`, then `enable_agent`); the runtime sees it as soon as it is enabled. Webhook outputs must be https. Returns the stored agent with its `version`; the change is recorded in the client activity feed.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/agent`
- MCP tool / A2A skill: `create_agent`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `templateId` | body | string | yes | Template id, e.g. 'sales_lead' or 'custom' |
| `name` | body | string | yes | Display name |
| `enabled` | body | boolean | no | Whether the agent evaluates live turns (default false: test it, then enable_agent); default false |
| `channels` | body | array of string | yes | Channels the agent listens on: lowercase channel ids ('*', 'web', 'gmail', 'outlook', 'instagram', 'messenger', 'whatsapp', 'chatgpt', 'webhook'); ['*'] alone means every channel |
| `criteria` | body | string | yes | What to look for in the conversation |
| `action` | body | string | yes | What to do when criteria are met |
| `outputs` | body | array of object \| object \| object \| object \| object \| object \| object \| object \| object | yes | Output actions to execute on match |
| `threshold` | body | number | no | Minimum confidence (0–1); default 0.7 |
| `repeat` | body | object \| object \| object | no | Repeat policy; default {"mode":"once_per_session"} |
| `scope` | body | object | no | Guest identity and hotel-local schedule criteria |
| `resources` | body | object | no | Allowed knowledge, translations, configuration and integration tools |

## `delete_agent` — Delete ledger agent

Soft-delete a ledger agent.

- REST: `DELETE https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}`
- MCP tool / A2A skill: `delete_agent`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |

## `disable_agent` — Disable ledger agent

Disable a ledger agent so it no longer evaluates live turns.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}/disable`
- MCP tool / A2A skill: `disable_agent`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |

## `enable_agent` — Enable ledger agent

Enable a ledger agent so it evaluates live turns.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}/enable`
- MCP tool / A2A skill: `enable_agent`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |

## `get_agent` — Get ledger agent

Fetch one ledger agent by id, with `attention` — true when it had a failed or errored run in the last 24 hours (the console rail's flag) — and the attention details. 404 when the agent does not exist.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}`
- MCP tool / A2A skill: `get_agent`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |

## `get_agent_execution_history` — Explain one agent execution

Fetch the durable source-message, trigger and action evidence for one execution, including output message references. Preserves the configuration used at execution time even if the agent was renamed or deleted.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agents/history/{executionId}`
- MCP tool / A2A skill: `get_agent_execution_history`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `executionId` | path | string | yes |  |

## `get_guest_agent_settings` — Get Guest agent resources

Read resource permissions and current settings version for the built-in, always-on Guest agent.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agent/guest/settings`
- MCP tool / A2A skill: `get_guest_agent_settings`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `list_agent_execution_history` — Explain agent activity

List indexed action-history metadata: source-message identity, agent configuration version, status, confidence, threshold and timing. Use get_agent_execution_history to load one execution's immutable decision and output evidence. Lists triggered runs by default; set executionsOnly=false to investigate nonmatches, below-threshold and dedupe decisions as well.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agents/history`
- MCP tool / A2A skill: `list_agent_execution_history`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | query | string | no | Configured agent id; format uuid |
| `sessionId` | query | string | no |  |
| `status` | query | string | no |  |
| `from` | query | string | yes | Inclusive ISO start; range cannot exceed 366 days; format date-time |
| `to` | query | string | yes | Exclusive ISO end; format date-time |
| `limit` | query | integer | no | default 50 |
| `offset` | query | integer | no | default 0 |
| `executionsOnly` | query | boolean | no | Triggered runs only (default true for sessions and executions): runs whose criteria matched (acted, partial, failed, pending, waiting for details, skipped by instruction) plus runs whose evaluation failed. Set false for the diagnostic view of every decision, including no_match, below_threshold and skipped_dedupe. |

## `list_agent_sessions` — Find agent sessions and analytics

Find the sessions where an agent was triggered in a date range, with exact matched, delivered, failed and pending counts across the full result set, not just this page. Sessions where no agent matched are listed only with executionsOnly=false.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agents/sessions`
- MCP tool / A2A skill: `list_agent_sessions`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | query | string | no | Configured agent id; format uuid |
| `sessionId` | query | string | no |  |
| `status` | query | string | no |  |
| `from` | query | string | yes | Inclusive ISO start; range cannot exceed 366 days; format date-time |
| `to` | query | string | yes | Exclusive ISO end; format date-time |
| `limit` | query | integer | no | default 50 |
| `offset` | query | integer | no | default 0 |
| `executionsOnly` | query | boolean | no | Triggered runs only (default true for sessions and executions): runs whose criteria matched (acted, partial, failed, pending, waiting for details, skipped by instruction) plus runs whose evaluation failed. Set false for the diagnostic view of every decision, including no_match, below_threshold and skipped_dedupe. |

## `list_agent_templates` — List ledger templates

List predefined agent templates with suggested criteria, actions, and outputs.

- REST: `GET https://maison-labs.com/api/v1/agenttemplates`
- MCP tool / A2A skill: `list_agent_templates`
- Needs: agents READ (global)
- Read-only.

Inputs:

_No inputs._

## `list_agent_tools` — List tools an agent may use

List the hotel's integration tools an agent may be allowed to call — the ids `create_agent` / `update_agent` accept in `resources.tools` — with each tool's provider, description and whether it only reads. Only tools delivered to the guest audience are listed. 404 when the client does not exist.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agents/tools`
- MCP tool / A2A skill: `list_agent_tools`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `list_agents` — List ledger agents

List a hotel's configurable specialists, each with its live `counter` (matches and outcomes; null before its first run), plus `guest` — the built-in, always-on Guest agent's resources and settings version — and `templates`, the catalogue `create_agent` starts from. `builtInAgents` names the Guest agent's settings tool. 404 when the client does not exist.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/agents`
- MCP tool / A2A skill: `list_agents`
- Needs: agents READ (client); client plan must include `agents`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `test_agent` — Test ledger agent

Dry-run a ledger agent against a transcript. Returns verdicts without executing outputs or writing an execution record.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}/test`
- MCP tool / A2A skill: `test_agent`
- Needs: agents EXECUTE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |
| `channel` | body | string | no | Channel the transcript came from; default "web" |
| `guestIdentified` | body | boolean | no | Whether the guest is identified (for identity-scoped agents); default false |
| `transcript` | body | array of object | yes | Representative conversation transcript (1–100 turns) |

## `update_agent` — Update ledger agent

Partially update a ledger agent; the live runtime picks it up at once and the change is recorded in the client activity feed. Requires the current `version` for optimistic concurrency (409 when it moved). Webhook outputs must be https.

- REST: `PUT https://maison-labs.com/api/v1/client/{clientId}/agent/{agentId}`
- MCP tool / A2A skill: `update_agent`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `agentId` | path | string | yes | Ledger agent id; format uuid |
| `version` | body | integer | yes | Current version from a prior read |
| `name` | body | string | no |  |
| `enabled` | body | boolean | no |  |
| `channels` | body | array of string | no | Channels the agent listens on: lowercase channel ids ('*', 'web', 'gmail', 'outlook', 'instagram', 'messenger', 'whatsapp', 'chatgpt', 'webhook'); ['*'] alone means every channel |
| `criteria` | body | string | no |  |
| `action` | body | string | no |  |
| `outputs` | body | array of object \| object \| object \| object \| object \| object \| object \| object \| object | no |  |
| `threshold` | body | number | no |  |
| `repeat` | body | object \| object \| object | no |  |
| `scope` | body | object | no |  |
| `resources` | body | object | no |  |

## `update_guest_agent_settings` — Set Guest agent resources

Update resource permissions for the built-in Guest agent using its current settings version (0 for untouched defaults). The Guest agent cannot be disabled.

- REST: `PUT https://maison-labs.com/api/v1/client/{clientId}/agent/guest/settings`
- MCP tool / A2A skill: `update_guest_agent_settings`
- Needs: agents WRITE (client); client plan must include `agents`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `resources` | body | object | yes |  |
| `version` | body | integer | yes |  |