To let an assistant use these tools, grant AI agents on the consent screen, or just
Agents under its Fine-tune. The scope is agents.
Read tools work with Read only or Read & write access; write tools only with
Read & write.
Your assistant doesn't see these tools straight away. It finds them with search_tools or
describe_tools, and runs one with use_tool, passing its name and
arguments. Most assistants do this for you: just ask for what you want.
What your assistant is told about this group
Your AI agents and their versions. A version can't be changed once it's created. To change an agent, build a new version with create_agent_version (its model, persona (name, face and voice: left out, it carries over from the latest version), instructions, and what it uses: context blocks, journeys, library groups, conduct rules and policies), then promote it with promote_agent_version. Promoting changes what live customers talk to straight away, and so does revert_agent_version, which puts an older version live again: confirm with the user first.
The descriptions below are the ones your assistant reads, so they're written for it. When a connection covers more than one
organisation, the assistant passes org (the organisation's slug, from list_orgs) to say which one.
list_agents
Read List agents
The org's AI agents with their draft and production versions. archived: true lists the archived ones instead.
Arguments
| Field | Type | Description |
|---|---|---|
| archived | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_agent
Read Get an agent
One agent with its full version history, and what uses it: usage.live is what blocks archiving it, usage.history what keeps it from being deleted for good.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_agents_overview
Read Agents overview
Counts across the agent estate: agents, context blocks, conduct rules, tools, library items, channel deployments and contacts.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_agent_version
Read Get an agent version
One agent version in full: its instructions, model, persona, and everything it uses (context blocks, journeys, library groups, conduct rules, policies).
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| version_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_agent
Write Create an agent
Create an agent shell. industry/agent_type/custom_industry are creation-time only (read-only afterwards); configure behaviour by creating a version next.
Arguments
| Field | Type | Description |
|---|---|---|
| name required | string | |
| industry | string | e.g. insurance, financial |
| agent_type | string | Registry key, e.g. insurance_support (see the type registry); personal_assistant suits any industry, or none |
| custom_industry | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_agent
Write Rename an agent
Rename an agent (its classification can't be changed after it's created).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| name required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
archive_agent
Write Archive agent
Archive the agent: it leaves lists and pickers and can't be newly chosen, while everything that already used it keeps working. Refused while anything live still uses it (the error says what, so switch those first). Undo with restore_agent.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
restore_agent
Write Restore agent
Restore an archived agent to lists and pickers.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_agent
Write Delete agent
Delete an ARCHIVED agent for good. Only possible when nothing, live or historical, has ever used it; otherwise it stays archived. Irreversible: confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_agent_version
Write Create an agent version
Build a new draft version of an agent: its model, persona, instructions and what it uses. Each context block is added as it is now; journeys must belong to the organisation's products; conduct rules are added by id or by template key. The version becomes the agent's draft. Promote it separately with promote_agent_version.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| ai_model_id | string | Optional: new versions run on Claude Haiku unless you name another model. |
| persona_role | string | The agent's job title as customers see it. This and the other persona fields carry over from the agent's latest version when left out (the name is the agent's own: rename it with update_agent). |
| persona_team | string | |
| personality | string | Its character and how it speaks. |
| response_length | string |
One of: "short", "medium", "long"
|
| topics | array of string | What it talks about, deciding the objections it knows. Empty follows from the agent's industry. |
| persistence | string |
How it takes "I'm not interested": gentle accepts the first no, curious asks once why, persistent makes up to two tries. For agents that nurture: one that sells (a sales journey or flow, or a Purchase agent) is always gentle. The persistence_limit policy rule caps it (one try unless a policy says otherwise).
One of: "gentle", "curious", "persistent"
|
| avatar_preset | string |
Its face. Left out, it keeps the latest version's.
One of: "person_blue", "person_green", "person_orange", "person_purple", "person_red", "person_teal", "person_pink", "person_indigo", "person_amber", "person_cyan", "person_yellow", "person_emerald", "flat/man_1", "flat/man_2", "flat/man_3", "flat/man_4", "flat/man_5", "flat/man_6", "flat/woman_1", "flat/woman_2", "flat/woman_3", "flat/woman_4", "flat/woman_5", "flat/woman_6", "shape_circle_blue", "shape_triangle_green", "shape_diamond_orange", "shape_hexagon_purple", "shape_cross_red", "shape_star_teal", "shape_pentagon_pink", "shape_octagon_indigo", "shape_squares_amber", "shape_dots_cyan", "shape_bolt_yellow", "shape_heart_emerald", "pattern_stripes_blue", "pattern_dots_green", "pattern_diagonal_orange", "pattern_checker_purple", "pattern_zigzag_red", "pattern_waves_teal", "pattern_grid_pink", "pattern_diamonds_indigo", "pattern_rings_amber", "pattern_triangles_cyan", "pattern_crosses_yellow", "pattern_herringbone_emerald", "emoji_happy", "emoji_cool", "emoji_wink", "emoji_laugh", "emoji_love", "emoji_think", "emoji_shock", "emoji_angry", "emoji_sad", "emoji_star", "emoji_sleepy", "emoji_nerd", "ella"
|
| intro_text | string | |
| escalation_text | string | |
| closing_text | string | |
| type_instructions | string | |
| quote_form_greeting | string | What the agent says when a chat is opened from a quote form (the website gets intro_text). Blank keeps the AI-written opener about the product. {{first_name}} and other known values fill in; a line naming one that isn't known is left out. |
| quote_form_starters | array of string | Tappable prompts under the quote form greeting (the website shows the site's own). |
| creativity | string |
One of: "creativity_none", "creativity_minimal", "creativity_limited", "creativity_some", "creativity_moderate", "creativity_high", "creativity_maximum"
|
| media_frequency | string |
One of: "media_never", "media_once", "media_moderate", "media_always"
|
| suggested_answers | boolean | On webchat, let the agent offer a few tappable replies under a message. Off by default. |
| context_block_ids | array of string | Ordered |
| insurance_journey_ids | array of string | Ordered |
| sales_flows | array of object | The sales flow the version sells a product on, per channel: one of the product's attached sales flows (get_product_sales_flow's all_attached). A product and channel left out sell on the product's default. |
| sales_flows[].product_id required | string | |
| sales_flows[].channel required | string |
One of: "web", "voice", "sms", "whatsapp", "email", "webmcp", "chatgpt", "claude"
|
| sales_flows[].sales_flow_id required | string | |
| library_group_ids | array of string | |
| conduct_rule_ids | array of string | |
| conduct_rule_template_keys | array of string | |
| agent_policy_ids | array of string | Ordered |
| calendar_booking_enabled | boolean | Let it check availability and book, move and cancel appointments. Off unless set. |
| booking_calendars | array of object | The connected calendars (list_integration_connections) it books into, each with or without a Google Meet link. None: the organisation's internal diary only. |
| booking_calendars[].connection_id required | string | |
| booking_calendars[].google_meet | boolean | |
| calendar_instructions | string | Added to its instructions, e.g. which diary to use when. |
| calendar_phone_required | boolean | Whether booking needs the person's phone number (it always needs their name). On unless set false, e.g. for meetings arranged by email. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
promote_agent_version
Write Promote an agent version
Recompile and promote a version to production: it immediately serves live customer conversations on every channel the agent is deployed to, with the compliance rules as they stand now frozen into it (later rule changes wait for its next promote). Confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| version_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
revert_agent_version
Write Revert to an agent version
Clone an older version's full configuration into a new version and promote it: the rollback path. Goes live immediately; confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| version_id required | string | The version to restore |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
promote_compliance_updates
Write Put an agent's compliance updates live
Copy the agent's live version into a new one that pins each policy's newest version and runs the rule settings as they stand now, everything else unchanged, and promote it. For the compliance updates its page shows waiting. Goes live immediately; confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
start_test_conversation
Write Start a test conversation
Open an internal test chat against an agent version (draft by default, or a specific version_id): nothing reaches customers. Then use send_test_message.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| version_id | string | Defaults to the draft (or production) version |
| channel | string |
web (the default), or sms, whatsapp or email: each reply then goes through that channel's send checks (Reply STOP, the AI disclosure and the rest) without being sent
One of: "web", "sms", "whatsapp", "email"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
send_test_message
Write Send a test message
Chat with the agent in an internal test conversation and get its real reply (a live LLM call). Refused on customer conversations.
Arguments
| Field | Type | Description |
|---|---|---|
| conversation_id required | string | |
| content required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |