AI Employees over MCP

Two ways to work with your AI employees from an external agent: chat with one in a sandbox, or run its native actions directly on a real contact.

Chat with an AI employee

agents_chat_start → agents_chat_send (repeat) → agents_chat_end. Requires the agents:run scope (admin only).

The chat runs the agent's real flow in a disposable sandbox: a throwaway contact and conversation marked as test data. CRM actions the agent takes (tags, stage moves, contact fields) land on that sandbox contact; external effects — sending on the channel, emails, webhooks, credits — are simulated and reported as such. Nothing reaches your real contacts.

// agents_chat_start
{ "agent_id": "…", "lead_simulation": { "name": "Ana", "company": "Acme", "phone": "+5511999990000" } }
// → { "session_id": "…", "agent": { "id", "name", "channel" }, "status": "active", "expires_at": "…" }

// agents_chat_send
{ "session_id": "…", "message": "Quero saber o preço do plano anual" }
// →
{
  "session_id": "…",
  "turn": 1,
  "replies": ["Claro! O plano anual…"],
  "status": "paused",                 // running | paused | completed | transferred | failed | blocked
  "waiting_for": "lead_reply",        // lead_reply | timer | null
  "can_skip_wait": false,
  "executed_nodes": ["trigger_1", "ai_step_2"],
  "side_effects": [
    { "tool": "add_tag", "args": { "tags": ["decisor"] }, "result": { "added": 1 }, "simulated": false, "scope": "sandbox" },
    { "tool": "send_email", "simulated": true, "scope": "sandbox" }
  ],
  "blocked_reason": null,
  "error": null,
  "expires_at": "…"
}

• event instead of message simulates what the channel would send: chat_started, invite_accepted, invite_ignored, no_response, wait_skipped (advances a timer when can_skip_wait is true).
• The agent needs an active channel of its type (a connected WhatsApp number for a WhatsApp agent, and so on); otherwise NO_ACTIVE_CHANNEL with details.channel_type. This mirrors the in-app Test mode.
• Sessions expire after 30 idle minutes (SESSION_EXPIRED) and the sandbox is discarded. At most 5 active sessions per API key (LIMIT_REACHED). Always call agents_chat_end when done.
• lead_simulation.tag_ids pre-applies tags to the simulated lead so trigger filters and conditions can be exercised.

Run native actions directly

These tools execute the same actions an AI employee would, on a real contact, without a flow. Scope agent_tools:execute (admin only), except knowledge_search (knowledge:read) and agent_transfer_to_human (conversations:write).

Tool	Requires	What happens
knowledge_search	agent_id, query	Semantic search over the agent's knowledge libraries (FAQs, objections, documents, cases)
agent_register_lead_source	contact_id, source	Sets the contact's lead source and attribution (campaign, adset, creative)
agent_send_email	contact_id, subject, body	Sends a real transactional email to the contact
agent_transfer_to_human	agent_id, conversation_id	Routes a real conversation to the sector/user configured on the agent
agent_schedule_meeting	agent_id, conversation_id	Sends the agent scheduling link as a message in the conversation
agent_check_availability	agent_id	Free slots of the seller the agent would book with. Holds each slot for 10 min, so it is a write tool (accepts idempotency_key; dry_run still queries live)
agent_book_meeting	agent_id, contact_id, slot_id	Books one of the slot_ids returned by agent_check_availability

• contact_id, agent_id and conversation_id must belong to your account; a sandbox contact is refused.
• dry_run: true runs the action in test mode (nothing is written, simulated: true), except knowledge_search (a read) and agent_check_availability (holds are placed even in test mode, by design of the agent tool).
• agents_chat_end is idempotent: ending an already-ended session returns already_ended: true.
• Without conversation_id, agent_check_availability does not persist the seller lock, so a later agent_book_meeting may land on another seller in round-robin sectors. Pass the conversation when you have one.
• The remaining native tools (add_tag, remove_tag, move_stage, create_opportunity, set_contact_field, lookup_contact_field) are the implementation behind contacts_add_tags, contacts_remove_tags, opportunities_move_stage, opportunities_create, contacts_update and contacts_get. The full catalog with JSON Schemas is the getraze://tool-catalog resource.