Conversational Agents (Beta)

Beta

Conversational Agents are in Beta. Every endpoint in this section works end to end, but field names and limits may still change in backwards-compatible ways. Watch the changelog.

A Conversational Agent is an AI bot that reasons over a conversation and decides for itself what to do next: search your knowledge, search the web, remember a fact, load a skill, collect structured answers, or hand the conversation to a human. Agents answer on your messaging channels, in Live Chat and by email. A Flow can also start one to complete a task and get structured results back.

All agent endpoints live under https://api.sendseven.com/api/v1/automation.

Page	What it covers
Quickstart	Create, test and go live with an agent in six API calls
Agents API	Agents, skill links and knowledge sources
Skills API	Skills, versions, import, usage
Tools & turn lifecycle	What happens in one turn, tools and their limits
Test console & turn log	Run a turn without sending or billing, read the audit log
Skill goals	Collect validated answers, save them to the contact, run completion actions
Agents in Flows	The Run AI Assistant node with an agent target
Hand-off & assignment	When the agent hands over and who gets the conversation
Create an agent with AI	Let SendSeven draft the agent and its skills from your website
Billing, errors & limits	AI credits, error codes, every limit in one place

Plan availability

Conversational Agents are available on Professional, Scale and Enterprise. On Basic and API Only, every agent and skill endpoint returns 403 with error code feature_disabled. Agent replies and tool use are billed as AI credits.

Agent, FAQ Bot or Keyword Bot?

An agent plans each turn and picks its own tools, follows reusable, versioned skills, can collect validated answers with skill goals, and can return structured results to a Flow. The FAQ Bot answers every message from your Knowledge Base; the Keyword Bot sends fixed replies. The side-by-side comparison, including plans and billing, is in the Building Bots overview.

An agent also has a bot record (its bot_id), which is how it is attached to channels and how hand-off assignment is configured. You cannot create or test an agent through the bot endpoints: creating a bot with bot_type: "agent", changing a bot's type to or from agent, or starting a bot test chat on an agent's bot returns 400.

Core concepts

Agent

The agent holds the persona, instructions, language and escalation settings, tool switches, model tier, and the skills and knowledge sources it may use. See Agents API.

Skills

A skill is a named, reusable instruction set with a stable slug, for example order-return or qualify-lead. One skill can be linked to many agents.

• Versions. Every change to a skill's content creates a new, immutable version. Agents follow the current version unless the link pins a specific version. Restoring an old version copies it into a new version, so history is never rewritten.
• Description. The description says when the skill applies. It is required, because the agent uses it to decide which skills to load.
• Mode. Each link uses the skill's default_mode unless the link overrides it:

Mode	When the skill is part of the turn
always_on	Every turn. Use one always_on foundation skill for rules that always apply (company facts, tone, what not to do).
model_selected	When the conversation needs it. Before each turn a fast classifier reads the descriptions and preloads up to two matching skills; the agent can load more itself with the load_skill tool.
flow_only	Only when a Flow starts the agent with this skill.

• Tool allowlist. A skill can limit the tools available while it is loaded (tool_allowlist). See Tools & turn lifecycle.
• Goal. A skill version can carry a structured goal. See Skill goals.

Manage skills with the Skills API.

Skill goals

A skill can define a goal: the answers the agent must collect, how each answer is validated, which contact field it is saved to, and what happens when everything is collected (assign the conversation, send a webhook, start a Flow, hand over). Validation is done by SendSeven, not by the model, so only values that pass your rules are saved. See Skill goals.

Knowledge sources

source_type	What the agent searches
kb_folder	One Knowledge Base folder (one source per folder)
kb_all	Every Knowledge Base folder that is enabled for AI search
faq	Your FAQ: all published FAQ entries
web_search	The live web, limited to allowed_domains when set

An agent with no Knowledge Base, FAQ or folder sources searches your whole AI-searchable Knowledge Base. Conversation-history and ticket-summary folders are never searched by an agent. See Agents API — Knowledge sources.

Tools

Tool	Default	What it does
search_knowledge	on	Searches the agent's knowledge sources.
web_search	off	Searches the web. Also needs an enabled web_search knowledge source.
handoff	on	Hands the conversation to a human. Needs escalation to be enabled.
set_state	on	Remembers facts for the rest of the conversation.
load_skill	on	Loads a skill when the conversation needs it.
complete_task	—	Only when a Flow gives the agent a task. Not configurable.

Turn tools on or off with tools_config. Limits and details are in Tools & turn lifecycle.

Model tier

model_tier is standard ("Fast", the default: quickest, 1 AI credit per message) or advanced ("Deeper thinking": a reasoning model for harder conversations, 2 AI credits per reply it writes, with a fixed 15-second turn budget). Tool credits are the same for both. If the advanced model is unavailable for a step, that step falls back to the standard model, and a reply written by the standard model bills 1 credit per message. The model that answered is returned as model on the test console and the turn log.

Language

An agent has two language modes, set in language_settings:

Mode	language_detection_strategy	response_language	The agent answers in
Auto (default)	cascade	null	The contact's language
Fixed	fixed	the base_language code	base_language

Set both fields together when you switch modes. If you only change the strategy, an old response_language stays set and the agent keeps answering in that language. See Agents API — Language settings and Tools & turn lifecycle — Language.

Provenance and source footers

Every agent reply carries the sources it was based on in meta.provenance (max 8, kb, faq or web) and the answering agent in meta.agent_id. See Bot and agent message metadata.

Optionally, the reply also shows its sources to the contact:

• Knowledge Base sources footer: off by default. Turn it on with source_footer_enabled. source_footer_mode is urls_only (default: only links to your website pages) or urls_and_kb (also a generic "Knowledge Base" line for FAQ and document sources).
• Web search footer: always added when the agent used web search in that reply. It cannot be turned off.

Link check

Before a reply is sent, SendSeven checks every link on your own domains: domains that appear in the agent's persona, instructions or skills, in Knowledge Base documents found in this turn, or in allowed_domains. A link that does not appear in one of those sources is repaired to the closest known URL when it is a near miss (for example a mistyped domain), or removed otherwise. Links to other websites are left alone. Repairs show up as link_fixes in the test console.

Test console

POST /automation/agents/{agent_id}/test runs one turn against your real configuration. Nothing is sent to a contact and nothing is billed. It works while the agent is inactive, so you can test before you go live. See Test console & turn log.

Required scopes

Scope	Endpoints
automation:read	List and get agents, turns, knowledge sources; list and get skills, versions, usage and goal statistics
automation:create	Create agents and skills; all agent builder endpoints
automation:update	Update agents, replace an agent's skills, add/update/remove knowledge sources, run the test console; update skills and restore versions
automation:delete	Delete agents; delete or archive skills
automation:create and automation:update	Import skills

Hand-off assignment is configured on the agent's bot record (PATCH /automation/bots/{bot_id}, automation:update), and channel rules use /automation/bots/{bot_id}/rules.

Next steps

• Quickstart — build your first agent
• Run AI Assistant node — start an agent from a Flow
• Skill-based routing — route agent hand-offs to the right team members
• AI credits — how agent usage is billed
• Knowledge Base — manage the content agents search