Cloud Agents

Tools in the cloud_agents scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants cloud_agents.

add_cloud_agent_knowledge

Scope: cloud_agents:write

Attach knowledge to a cloud agent and index it (chunk + embed for RAG). Provide ONE of: content (raw text → a knowledge document is created), page_id (an existing space page), or asset_id (an existing document asset). Billable: indexing runs embeddings.

create_cloud_agent

Scope: cloud_agents:write

Create a cloud agent (starts as draft). After creating, use the other cloud-agent tools to add knowledge, channels, voice, video, capabilities and widget config, then update_cloud_agent status='active'. To keep it good after launch: save eval scenarios and re-run them after config changes (run_cloud_agent_test_scenarios), A/B different instructions in production (set_cloud_agent_variant), and roll back any bad change (restore_cloud_agent_version — every meaningful edit is auto-versioned).

create_snapshot

Scope: cloud_agents:write

Capture a cloud agent or Space App FROM THIS SPACE into the owner's portable snapshot library. Captures config/code only — channels, secrets, conversations and app data stay behind (they become install-time requirements). Returns the snapshot with its typed public_id (snap_agent_* / snap_app_*) — hand that id to any agent to install it elsewhere with install_snapshot.

get_cloud_agent

Scope: cloud_agents:read

Get a cloud agent including instructions and capability_context (per-category defaults + rules). Use list_cloud_agent_playbooks for playbooks.

get_cloud_agent_conversation

Scope: cloud_agents:read

Read one cloud-agent conversation's full transcript (role + content per message, chronological), plus call metadata when it was a call (duration, outcome, recording playback URL freshly signed for 1h). Use after list_cloud_agent_conversations to review what an agent said on a call or discussed with a lead.

get_cloud_agent_readiness

Scope: cloud_agents:read

Get a cloud agent's readiness report: structural lint issues (instructions needing a disabled capability, broken booking forms, playbook tool gaps...) plus the last AI deep-check audit (semantic contradictions between instructions, restrictions, forms, and playbooks — each finding has a suggested fix). Use this to see what to repair, apply fixes with update_cloud_agent / set_cloud_agent_capabilities / form tools, then re-check. The deep_check part may be stale — compare its checked_at against recent edits and use run_cloud_agent_deep_check to refresh.

get_cloud_agent_widget

Scope: cloud_agents:read

Get a cloud agent's chat-widget config plus the public embed token and a ready-to-paste embed <script> snippet (put it on a page or external site).

install_snapshot

Scope: cloud_agents:write

Install a snapshot (agent or app) into THIS space and get a readiness report. Missing models are auto-enabled and owned secrets matching by name are auto-assigned; the report's missing array lists what still needs you — resolve secrets with request_secret_input/assign_secret_to_space and connect integrations, then the install is ready. Snapshots never carry secret values, channels, or data.

list_cloud_agent_capabilities

Scope: cloud_agents:read

List a cloud agent's capabilities and whether each is enabled.

list_cloud_agent_channels

Scope: cloud_agents:read

List the channels a cloud agent is assigned to (widget, phone, sms, email, whatsapp, social_dm, meet).

list_cloud_agent_conversations

Scope: cloud_agents:read

List conversations this space's cloud agents have had across channels (widget, phone, sms, whatsapp, email, social_dm...): visitor, contact link, summary, message count, call duration, outcome, last activity. This is where cloud-agent CALL records live — inbound, outbound/test, and campaign calls all land here as channel='phone'. Filter by agent_id, channel, status, contact_id, or since.

list_cloud_agent_knowledge

Scope: cloud_agents:read

List a cloud agent's knowledge sources and their indexing status (pending|indexing|ready|error) + chunk_count.

list_cloud_agent_playbooks

Scope: cloud_agents:read

List a cloud agent's post-call playbooks (outcome-triggered follow-ups that run after a voice call closes), in priority order.

list_cloud_agent_scopes

Scope: cloud_agents:read

List the resource scopes on a cloud agent's capabilities. A capability with no scope row reaches every record of its type in the space; a scope row constrains it to specific ids or tags.

list_cloud_agent_test_scenarios

Scope: cloud_agents:read

List a cloud agent's saved eval scenarios (regression tests) with their last pass/fail result and reply.

list_cloud_agent_variants

Scope: cloud_agents:read

List a cloud agent's A/B instruction variants AND their live results (conversations + deflection_rate per variant, including base_instructions). Deflection = handled without a human handoff. Use this to see whether an experiment has a winner before keeping/removing variants.

list_cloud_agent_versions

Scope: cloud_agents:read

List a cloud agent's config version history (newest first, default 20, max 50). A DB trigger auto-snapshots the PRIOR config on every meaningful change — including changes YOU make via these tools — so every edit is reversible. Returns a compact config_preview per version (long fields truncated); restore_cloud_agent_version applies the full stored config.

list_cloud_agent_voice_options

Scope: cloud_agents:read

List the voice catalog for cloud agents: providers (cartesia | deepgram), per-provider voices (id + name + style), voice LLM models, STT providers and languages. Use before set_cloud_agent_voice to pick a valid voice_id.

list_cloud_agents

Scope: cloud_agents:read

List cloud agents in the space.

list_snapshots

Scope: cloud_agents:read

List portable snapshots (cloud agents or apps) you can install into this space — your own library plus any shared into this space. Each entry reports dependency_count and whether it came from_this_space. Use install_snapshot with an id to install one.

list_video_avatars

Scope: cloud_agents:read

List the video avatars a cloud agent can appear as on camera (id, name, preview image), plus valid vision_model options. Use before set_cloud_agent_video.

remove_cloud_agent_channel

Scope: cloud_agents:write

Remove a channel assignment from a cloud agent. channel_id from list_cloud_agent_channels.

remove_cloud_agent_knowledge

Scope: cloud_agents:write

Detach a knowledge source from a cloud agent (its chunks are removed too). source_id from list_cloud_agent_knowledge.

remove_cloud_agent_playbook

Scope: cloud_agents:write

Delete a post-call playbook. playbook_id from list_cloud_agent_playbooks.

remove_cloud_agent_scope

Scope: cloud_agents:write

Remove all resource scoping for a capability, making it space-wide again.

remove_cloud_agent_test_scenario

Scope: cloud_agents:write

Delete an eval scenario. scenario_id from list_cloud_agent_test_scenarios.

remove_cloud_agent_variant

Scope: cloud_agents:write

Delete an A/B instruction variant (e.g. the loser after an experiment). variant_id from list_cloud_agent_variants.

restore_cloud_agent_version

Scope: cloud_agents:write

Roll a cloud agent back to a saved config version (instructions, guardrails, greeting, model, temperature, context, safety). The config that is live right now gets auto-saved as a new version first, so a restore is itself reversible. version_id from list_cloud_agent_versions. Use this when a config change made the agent worse (e.g. eval scenarios started failing).

run_cloud_agent_deep_check

Scope: cloud_agents:write

Run the AI deep check on a cloud agent NOW (billable — one LLM audit charged to the space wallet). Reads the whole config (instructions, restrictions, playbooks, capabilities, booking-page forms) and returns contradictions with suggested fixes. Run after editing the agent to verify your fixes landed clean.

run_cloud_agent_test_scenarios

Scope: cloud_agents:write

Run the agent's eval scenarios against the REAL chat pipeline and record pass/fail on each (billable — every scenario is one real conversation charged to the space wallet). Omit scenario_id to run the whole suite; pass it to run one. Each run uses a fresh conversation so scenarios don't leak context into each other. Returns per-scenario pass/fail with the reply and any missing expected substrings. Run this after config changes to catch regressions before customers do.

set_cloud_agent_approvals

Scope: cloud_agents:write

Set which agent actions require the owner's approval before they run (queued for review instead of executing immediately). Replaces the full list; pass [] to clear. Valid keys: send_email, reply_to_email, send_email_campaign, publish_social_post, schedule_social_post, reply_social_dm, reply_social_comment, send_rcs, book_appointment, create_booking_page.

set_cloud_agent_capabilities

Scope: cloud_agents:write

Enable/disable a cloud agent's capabilities (permissions). Pass capability keys like contacts_read, contacts_create, pages_create, calendar_event_create, tasks_create, social_post_publish, email_campaign_send, sms, phone_inbound. Check the Capabilities UI for the full catalog.

set_cloud_agent_channel

Scope: cloud_agents:write

Assign/enable a channel for a cloud agent. channel_type: widget|phone|sms|email|whatsapp|social_dm|platform|meet. resource_id is the phone number / email address / social account id it routes to (omit for widget). Phone auto-configures SIP routing.

set_cloud_agent_context

Scope: cloud_agents:write

Set a cloud agent's per-capability operating defaults + rules (cloud_agents.capability_context). Enabling a capability grants the tool; this tells the agent WHICH resource to use and HOW (e.g. calendar → default_booking_page_id + 'book through Intro Call'; tables → default_table_id + 'log every call'). Pass category (calendar|tables|forms|contacts|…) with rules and/or the relevant default id. Merges into the existing context — partial calls keep other categories.

set_cloud_agent_limits

Scope: cloud_agents:write

Set rate limits + daily budget for a cloud agent. per_day = max replies/day; per_sender_hour = max inbound per conversation/hour; daily_spend_usd = max wallet spend/day. Any field set to null or 0 = unlimited. Partial update.

set_cloud_agent_playbook

Scope: cloud_agents:write

Create or update a post-call playbook — an autonomous follow-up that runs AFTER a voice call closes with a matching outcome (they never appear in the live prompt; the agent needs the voice channel enabled). Pass playbook_id to update; omit to create (title + trigger_type + objective required). trigger_type: after_every_call | call_no_booking | caller_hung_up_early | asked_for_human | agent_couldnt_answer. allowed_tools empty = all of the agent's enabled tools. escalation_rule = when/how to pull in a human.

set_cloud_agent_privacy

Scope: cloud_agents:write

Set conversation retention for a cloud agent. retention_days = positive integer days after which conversations auto-delete, or null to keep them indefinitely.

set_cloud_agent_safety

Scope: cloud_agents:write

Set safety guards for a cloud agent. pii_redaction strips PII from saved memories; input_guard screens inbound messages for prompt-injection; output_guard screens the agent's replies for PII leaks / abuse. Guard modes: off | flag (log only) | block. Partial — only provided fields change.

set_cloud_agent_scope

Scope: cloud_agents:write

Constrain ONE capability to specific records or tags (resource_type is derived from the capability). mode: 'allow' (whitelist the given ids/tags), 'deny' (blacklist them), or 'owner_only' (only records this agent itself created). An 'allow' call with no resource_ids and no tag_ids clears the scope (capability becomes space-wide again). tag_ids only apply to contact/table/form/page. Scopable capabilities include contacts_read/edit, tables_read/row_update, pages_edit, forms_read, social_dm_reply, email_campaign_send, etc. — call with an unscopable capability to get the full list back in the error.

set_cloud_agent_test_scenario

Scope: cloud_agents:write

Create or update an eval scenario — a saved regression test: a prompt plus the substrings the reply must contain (case-insensitive). Omit scenario_id to create (name + prompt required); pass it to update. Empty expect_contains = pass if the agent replies at all. Build a suite of these, then re-run after every config change with run_cloud_agent_test_scenarios.

set_cloud_agent_variant

Scope: cloud_agents:write

Create or update an A/B instruction variant. Each NEW conversation is randomly assigned an active variant by weight (its instructions replace the base ones for that conversation); with no active variants the agent uses its base instructions. Omit variant_id to create (label + instructions required); pass it to update label/instructions/weight/active. Compare outcomes with list_cloud_agent_variants.

set_cloud_agent_video

Scope: cloud_agents:write

Enable/configure video for a cloud agent (camera + screen-share vision on calls and Meet). video_enabled turns vision on; vision_model is the model that analyzes what's on camera (see list_video_avatars for options). video_avatar_id gives the agent an animated on-camera avatar with lip sync — pick one from list_video_avatars (pass its name/preview as avatar_name/avatar_preview_url); pass video_avatar_id: null to remove it. Video is independent of voice.

set_cloud_agent_voice

Scope: cloud_agents:write

Enable/configure voice for a cloud agent (used on calls and the widget call button). voice_id is a Cartesia/Deepgram voice id — list_cloud_agent_voice_options shows available ones.

test_cloud_agent

Scope: cloud_agents:write

Send a message to a cloud agent and get its reply back — for verifying an agent before publishing. Runs the REAL chat pipeline, so the conversation is billed to the space wallet (like the in-app Test panel). Returns { reply, messages (the bubbles it would send), conversation_id }. Pass conversation_id to continue a prior test thread (multi-turn); omit for a fresh one. channel defaults to 'platform'.

update_cloud_agent

Scope: cloud_agents:write

Update a cloud agent's core config (name, instructions, status, greeting, model, context, temperature, max_tokens, avatar_url, language, guardrails, multi-bubble texting). Set status='active' to publish.

update_cloud_agent_widget

Scope: cloud_agents:write

Configure a cloud agent's chat widget: primary_color, position (bottom-right|bottom-left), greeting_text, placeholder_text, show_branding, allowed_domains (string[]), custom_css, allow_calls, allow_attachments, home_title, home_cards (array).