In this example, you'll build a basic weather agent that provides simple, built- in responses to user's requests. An agent is essentially the container or project and it contains intents, entities, and the responses you want to deliver to your user. Intents are the mechanisms that pick up what your user is requesting (using entities) and direct the agent to respond accordingly.
For simple replies that don't include information gathered outside of the conversation, you can define the responses directly in the intents. More advanced responses can be made using your own logic and webhook for fulfillment. In later sections, you'll add fulfillment so the agent can reply with information it gathers from an external weather API call. For now you'll cover the basics.
Create an agent
An API.AI agent represents the conversational interface of your application, device, or bot. To create an agent:
- If you don't already have an API.AI account, sign up. If you have an account, login.
Click on Create Agent in the left navigation and fill in the following fields:
- Name - The name of your agent
- Language - Currently, API.AI supports many languages, and you cannot change the language after saving the agent.
- Time Zone - The time zone for the agent
Create an intent
An intent maps what a user says with what your agent does. This first intent will cover when the user asks for the weather.
To create an intent:
Click on the plus icon add next to Intents. You will notice some default intents are already in your agent. Just leave them be for now.
Enter a name for your intent. This can be whatever you'd like, but it should be intuitive for what the intent is going to accomplish.
In the User Says section, enter examples of what you might expect a user to ask for. Since you're creating a weather agent, you want to include questions about locations and different times. The more examples you provide, the more ways a user can ask a question and the agent will understand.
Enter these examples:
- What is the weather like
- What is the weather supposed to be
- Weather forecast
- What is the weather today
- Weather for tomorrow
- Weather forecast in San Francisco tomorrow
In the last three examples you'll notice the words
tomorroware highlighted with one color, and
San Franciscois highlighted with another. This means they were annotated as parameters that are assigned to existing date and city system entities. These date and city parameters allow API.AI to understand other dates and cities the user may say, and not just "today", "tomorrow", and "San Francisco".
Once you're done, click the Save button.
Try it out
Now that your agent can understand basic requests from the user, try out what you have so far.
In the console on the right, type in a request. The request should be a little different than the examples you provided in the User Says section. This can be something like "How's the weather in Denver tomorrow". After you type the request, hit "Enter/Return".
You won't get a conversational response, but you should see data in the following fields of the console:
- Response - "Not Available" because the agent doesn't have any actual responses set up yet
- Intent -
weathermeans the request hit the "weather" intent
- Parameters -
geo-cityhave their respective values from the request (e.g. tomorrow's date and "Denver")
Now you'll add basic responses to the intent so the agent doesn't just sit there in awkward silence. As mentioned before, responses added to an intent don't use external information. So this will only address the information the agent gathered from the user's request.
If you've navigated away from the "weather" intent, return to it by clicking on Intents and then the "weather" intent.
In the same way you entered the User Says examples, add the lines of text below in the Response section:
- Sorry I don't know the weather
- I'm not sure about the weather on $date
- I don't know the weather for $date in $geo-city but I hope it's nice!
You can see the last two responses reference entities by their value placeholders.
$datewill insert the date from the request, and
$geo-citywill insert the city.
When the agent responds, it takes into account the parameter values gathered and will use a reply that includes those values it picked up. For example, if the request only includes a date, the agent will use the second response from the list.
Once you're done, click the Save button.
Try it out, again
Back in the console on the right, enter the same request or enter a new one. You should see the following data in the console fields:
- Response - shows an appropriate response from the ones provided
- The response chosen is based off of the values you provide in the query (e.g. By providing only the date, the agent should respond with the option that only includes the date)
- Intent -
weatheragain a successful trigger of the intent
- Parameter - the values you provided in your query, should be reflected in the appropriate response
In the next part, you'll add fulfillment to get relevant weather information via an API call. You'll also ensure the conversation with your users goes smoothly, even if they wander off your conversational path, with branching.