Part 1 - Adding Agent Commands
To get the Agent to respond to userinput you will need to add commands. Commands are a word or series of words the Agent waits for. Once one of the commands is spoken the agent will call the Commands() Event and return the name of the command that was spoken.
Name your Agent Control MSAgent.
Add this to the Form_Load() Event:
MSAgent.Characters.Load "DefaultCharacter"
Set AgentChar= MsAgent.Characters("DefaultCharacter")
AgentChar.Commands.Add "Notepad", "Notepad", "Notepad", True, True
Private Sub MsAgent_Command(ByVal UserInput As Object)
MsgBox UserInput.Name
End Sub
There, now try running it. Press SCROLLLOCK and then say your agents name to get him to appear. Once the agent has appeared press SCROLLLOCK again to get the agent to listen and then say the word "Notepad". A msgbox should appear with the word notepad in it, since that is the name we gave our command.
The first parameter listed above is the name that is what the Command() Event will return to you when your command is spoken. The next is the Caption parameter, which will determine how this command is displayed in the Agent Voice Commands Window. The third is the Voice property. The voice property is what the user must say to evoke this command. The voice property does not have to be the same as the Name or the Caption.
Now take a look at this line of code:
AgentChar.Commands.Add "notepad", "notepad", "[...] notepad [...]", True, True
Notice the ellipses in brackets? These have a special meaning to the Text to speech engine. These basically mean to ignore any speech before and after the word notepad. So you could say something like this "Open notepad please" and it will still return the "Notepad" command. Be careful when using the ellipses though, since they slow down processing considerably.
Part 2 - It's all Guesswork!
When a command is spoken the Agent takes its best guess and then returns you a command. The command may not always be correct, since the Agent is really just making a guess. Imagine this scenario: You have the agent setup to delete a database entry when the user speaks a specific command. Now you would want to ensure that MSAgent is fairly confident in the command before you wipe out valuable data. Thankfully MSAgent has a property designed to let you know just how certain the agent is about a command.
The UserInput object has a confidence property designed just for this purpose; the Confidence property. Confidence properties in MSAgent can range from -100 to 100. Try this:
Private Sub MsAgent_Command(ByVal UserInput As Object)
If UserInput.Confidence > -50 Then
MsgBox UserInput.Name
Else
MsgBox "I have " & UserInput.Confidence & " confidence in that command"
End If
End Sub
Sometimes you want to have different confidence levels for different commands. There is a property for this as well. Each command object can have a confidence level specified and a confidence text specified. If the agents confidence level does not meet or exceed the confidence level you set then the confidence text will be displayed in the agents ToolTip. Try adding this to the Form_Load:
AgentChar.Commands("notepad").Confidence = "50"
AgentChar.Commands("notepad").ConfidenceText = "Was that notepad you wanted?"
Notice that when the agents confidence level is below 50 it will display the ConfidenceText in the tooltip. But you should also notice that the agent will still proceed with the command and show the msgbox. To avoid that you would need to add code to check the UserInput confidence setting and the Command confidence setting to see if the latter is met or exceeded. Something like this:
If UserInput.Confidence > AgentChar.Commands(UserInput.Name).Confidence Then
MsgBox UserInput.Name
End If
There is also other parameters to let you know what other commands the agent considered when guessing. You can get the name of the second best match using the UserInput.Alt1Name, and the third best match using the UserInput.Alt2Name properties. Each of these have their own confidence scoring (Alt1Confidence, and Alt2Confidence). I guess one use for this would be to query the user showing all three choices and get the user to clarify the choice.
Sometimes the agent will get a built in command like "Show" or "Hide". In this case no Command names are returned. So to determine if any command names are returned the best way is to check the Userinput.Count property. This will tell you if 1, 2 or 3 guesses were returned from the agent. If only two are returned then the Alt2Name property will be empty so there will be no use checking it.
