OVERVIEW

Agents ! Suggest Edits (/docs/concept-agents/edit)

KEY CONCEPTS

Introduction (/docs/k
Agents Overview
Agents (/docs/co
(/docs/co
Google Project
Machine Learning (/d Agent Settings
Entities (/docs/conc General
Intents (/docs/conce ML Settings
Match Mode
Actions and Paramet
ML ClassiScation Threshold
Rich Messages (/doc
Export and Import
Response design for Export
Contexts (/docs/con Restore
Events (/docs/conce Import
Export and import to integrate with some known apps
Dialogs (/docs/dialo
Alexa
Training (/docs/traini
Cortana
Machine Learning Se Share
Prebuilt Agents (/doc
Analytics (/docs/anal
Agents Overview
API REFERENCE

FULFILLMENT Agents can be described as NLU (Natural Language Understanding)

modules for applications. Their purpose is to transform natural user
SDKS
language into actionable data.
INTEGRATIONS

DOMAINS (DEPRECATED)

GUIDELINES

VIDEOS

(https://Sles.readme.io/OwOSbicR5m1LIKRGZI9g_agents_processing.gif)

This transformation occurs when a user input matches one of the intents or
domains.

Intents (https://docs.api.ai/docs/concept-intents) are developer-deSned

components of agents, whereas domains
(https://docs.api.ai/docs/domains) are pre-deSned knowledge packages
that can be enabled or disabled in each particular agent.

Agents can be designed to manage a conversation \ow in a speciSc way.

This can be done with the help of contexts
(https://docs.api.ai/docs/concept-contexts), intent priorities
(https://docs.api.ai/docs/concept-intents#intents-priority), slot Slling
(https://docs.api.ai/docs/dialogs), responses
(https://docs.api.ai/docs/concept-intents#response), and fulSllment in the
form of webhook (https://docs.api.ai/docs/webhook).

" Agents are platform agnostic. You only have to design an agent
once, and then you can integrate it with a variety of platforms using
our SDKs (https://docs.api.ai/docs/sdks) and Integrations
(https://docs.api.ai/docs/integrations), or download Sles
compatible with your Alexa (https://docs.api.ai/docs/alexa-
integration) or Cortana (https://docs.api.ai/docs/cortana-
integration) apps.

Related topics:

How to create an agent (https://docs.api.ai/docs/get-started)

Authentication guidelines (https://docs.api.ai/docs/authentication)

GOOGLE PROJECT
If youre logged into API.AI with your Google account, you will see a Google
Project Seld on the agent creation page. This drop down menu will list your
existing Google Cloud Projects (http://cloud.google.com) (if you have any)
and the Create a new Google project option.
 (https://Sles.readme.io/8e543aa-gcp-001.png)

If Create a new Google project is selected when you create the agent, a
new Google project will be created using the agent name you entered.

" If the agent name you entered already exists as a Google Cloud
project, a randomized string of numbers and letters will be
appended to the end.

Agent Settings

To access your agent settings, click the gear button # in the API.AI
developer console.

GENERAL

Language See the list of currently available languages

(https://docs.api.ai/docs/languages). Note
that once the agent is created, you cannot
modify its language.
Avatar and Optional settings. You might want to modify
Description them if you decide to share your agent demo
page (https://docs.api.ai/docs/agent-demo-
page) publicly.

Default Time Time zone indicated in your agent settings will

Zone be used if no time zone is sent in the API query
requests
(https://docs.api.ai/docs/query#query-
parameters-and-json-Selds).

API keys Client access token and Developer access

token required for sending HTTP requests to
the agent. Read more in Authentication
(https://docs.api.ai/docs/authentication).

ML SETTINGS

" This feature is currently available for agents in English, German,

Spanish, French, Italian, Russian, and SimpliSed Chinese.

Match Mode
This setting deSnes what algorithms should be used for machine learning
classiScation. It applies to all the intents in which Machine learning is
enabled.

Hybrid match mode Sts best for agents with a small number of
examples in intents and/or wide use of templates syntax and
composite entities.
ML only match mode can be used for agents with a large number of
examples in intents, especially the ones using @sys.any .

(https://Sles.readme.io/fd8849b-ML_match_mode.png)
ML ClassiScation Threshold
You can deSne a threshold value in the range from 0 to 1 for the parameter
"score" returned in JSON responses to queries

(https://docs.api.ai/docs/query#response). If the returned value is less than

the threshold value, then a fallback intent (https://docs.api.ai/docs/concept-
intents#fallback-intent) will be triggered or, if there is no fallback intents
deSned, no intent will be triggered.

Note that fallback intents return "score": 1 and when no intent is triggered,
"score": 0 is returned.

To modify this setting, go to your agent settings > ML Settings > ML

ClassiScation Threshold and type in a new threshold value. Click 'Save' and
then 'Train' to retrain your agent ML model.

(https://Sles.readme.io/752c027-ML-threshold.png)

Export and Import

EXPORT
You can export your entire agent as a ZIP Sle which will contain some agent
settings and all of the intents and entities from your agent in JSON format.
To do this, go to your agent settings, select 'Export and Import' from the
horizontal menu, and click on the corresponding button.
 (https://Sles.readme.io/rk1E4fPzRJOvekWCi10s_agent_export3.png)

The exported agent.json Sle contains the following Selds:

Name Type Description

language String Agent's language

(https://docs.api.ai/docs/languages).

description String Optional agent description for the Agent demo

page (https://docs.api.ai/docs/agent-demo-
page).

enabledDomainFeatures Array Array of strings corresponding to the enabled

domains (https://docs.api.ai/docs/domains)
and domain fulSllment
(https://docs.api.ai/docs/domains#fulSllment).

defaultTimezone String Corresponds to the default time zone set in the

agent settings.

isPrivate Boolean true if the 'Private' option is selected in the

agent settings, false if the 'Public' option is
selected.

webhook Object

url String Public URL to the web service connected to the

agent via webhook
(https://docs.api.ai/docs/webhook).

headers Object Optional headers.

available Boolean true if webhook is enabled in the agent,

false otherwise.

useForDomains Boolean true if the 'Enable webhook for all Domains'

option is chosen in the webhook settings,
false if the 'Disable webhook for all Domains'
option is chosen.

customClassiSerMode String Corresponds to the Match mode

(https://docs.api.ai/docs/machine-learning-
settings#match-mode) from the ML Settings.

mlMinConSdence Number Corresponds to the ML ClassiScation

 Threshold (https://docs.api.ai/docs/machine-
learning-settings#ml-classiScation-threshold).

RESTORE
You can replace the current agent version with a new one.

$ All the intents and entities in the older version will be deleted
deleted.

(https://Sles.readme.io/efXWIJeERvqXaAA4KPw6_agent_restore.png)

IMPORT
You can upload new intents and entities without deleting the current ones.

$ Uploaded intents and entities will replace existing intents and

entities with the same name.

(https://Sles.readme.io/qFRPpLkVRA6Ahucu2Mxt_agent-
import.png)

$ When you perform Restore or Import to a newly created agent,

make sure to conSgure correct settings (language, integration and
fulSllment settings etc) in the agent being created.

Export and import to integrate with

some known apps
ALEXA
To export Alexa compatible Sles (https://docs.api.ai/docs/alexa-integration),
go to Integrations from the left side menu and select Amazon Alexa
integration. Then, click on the Export for Alexa button.

(https://Sles.readme.io/j6IPFYlpSZKBGfrCgFeK_Alexa-
export-settings.png)

CORTANA
If you created a Cortana compatible agent
(https://docs.api.ai/docs/cortana-integration), use Export for Cortana
button to export Cortana compatible VCD Sles.

(https://Sles.readme.io/WhvoKZh2ToO4ume61nEk_export-
for-cortana.png)

To import a Cortana compatible agent, it should be exported as a regular

agent. After creating a new agent, go to 'Integrations' from the left side menu
and enable Microsoft Cortana integration. Then, in the agent settings, click
the Import from zip button.
 (https://Sles.readme.io/7ekWtVaQRu0LQMLgna9K_import-
for-Cortana-enable-integration.png)

Share

API.AI agents can be shared with individuals on your team, allowing for
collaborative development and review.

(https://Sles.readme.io/04779eb-agent-sharing-001.gif)

Enter the email address of the person you want to share the agent to, choose
one of the following roles for that user, and then click Add
Add:

Developer - Ability to edit intents, entities, fulSllment, integrations

and training for the agent. This is ideal for team members like
developers and linguists.
Reviewer - Read-only access to intents and entities. This is ideal for
project managers, legal and anyone who just needs to review content.
 " Only the creator of the agent gets the role of Owner. Owners have
full agent access including agent settings, publishing, deletion etc.
Covers team roles like PM, Admin, etc.

A users role can be changed by choosing an alternate role from the drop
down menu for that user.

When youre done adding the people you want to share the agent to, make
sure to click the Save button.

$ Version Control and Collision Detection

At this time, API.AI does not have version control for agents, or
collision detection when making edits. This means changes could
potentially be overwritten by another user, in very speciSc
circumstances.

For instance, if one user enables the Webhook setting on the

FulSllment page, another user who is on the same page, won't see the
setting update until the page refreshes. The second user could then
click Save (with the setting disabled on their page) and the setting
would then be turned off.

The best way to avoid issues like this is to ensure users aren't working
on individual elements of the agent (intents, entities, etc.)
simultaneously.