Microsoft Agent 2 Tutorial

This tutorial has been contributed by VisionForce www.visionforceweb.com. If you would like to contribute your work please contact us.

Part 1 - Introduction

1.1 What is Microsoft Agent?

Microsoft Agent is a set of tools to enrich your program's environment. It makes "characters" talk, move around, and even play out animations. They can also respond to a user's speech, spoken through a microphone (known as conversational interfaces).
Microsoft Agent is simple to program and fun to use, but it can still do complex things.

1.2 What are the characters?

The "characters" are animated graphics put together in the Microsoft Agent Character Editor. There are different kinds of characters, some can talk, some can't, some are for Microsoft Office, some are just for Windows. The Microsoft Agent Character Editor adds commands to the characters that can be activated through Microsoft Agent.

You can download characters at http://www.cantoche.com/english/gallery/msagent.htm, or,you can design your own with the Microsoft Agent Character Editor. It is available at http://www.microsoft.com/msagent/.

When you load a character through Microsoft Agent, a "character icon" appears in the taskbar. If you move your mouse over the icon, a tool tip appears, telling you the name of the character. Single-clicking the icon displays the character. When the character is displayed, it is displayed in it's own window. The user can move the character by dragging it with the left mouse button. Note: You do not have to click on the character icon to show the character; you can also do it in code, how to do that will be shown later.

In addition to the talking, the character displays a word balloon that shows what is saying, the balloon hides when the character is finished talking. Note: You can disable the word balloon in the code, how to do that will be shown later.

If speech input is enabled, when the user presses the character's push-to-talk button on the keyboard, a listening tool tip is displayed notifying the user that the character is listening. If the character recognizes something that the user spoke through the microphone, the listening tool tip displays what the character heard, and if programmed to, the character will respond. The character will not recognize anything the user speaks unless it was added as a command to the character in the code. How to add commands to characters will be shown later.

Part 2 - Begin using Microsoft Agent

2.1 Loading the Microsoft Agent control

To load the Microsoft Agent control, click on the Tools toolbar and select Customize Toolbox. Once you are in the Customize Toolbox dialog, select the COM Components tab, and choose the Microsoft Agent Control 2.0. Put the Microsoft Agent control on the form and change its Name property to agtAgent.

If you don't have the Microsoft Agent 2.0 control in your list of COM Components, you need to download the Microsoft Agent 2.0 SDK from http://www.microsoft.com/msagent

2.2 Loading a character and showing it

To load a character add this code into your Form_Load section.

Dim Character As AgentObjects.IAgentCtlCharacter
Dim sChar As String

Try

	' The path to the character file
	sChar = "file path"

	' Load the character
	agtAgent.Characters.Load("CharacterID", sChar)

	' Set the "Character" declaration to be the character
	' just loaded
	Character = agtAgent.Characters("CharacterID")

	' Set the character's language to english
	Character.LanguageID = &H409

	' Show the character
	Character.Show()

Catch ex As Exception
	MessageBox.Show("Description: " & _
		ex.Message, "Error!", MessageBoxButtons.OK, _
		MessageBoxIcon.Warning)
End Try

2.3 Getting a character's information

To get a character's name, description, and extra data, add this to your code:

Dim sName As String
Dim sDescription As String
Dim sExtraData As String

sName = Character.Name			' Character's Name property
sDescription = Character.Description	' Character's Description
sExtraData = Character.ExtraData	' Character's ExtraData

2.4 Getting the names of the character's animations

This part uses a ComboBox with the Name cboCombo.
To get the names of the character's animations, add this to your code:

Dim animationName As String

' Clear the ComboBox
cboCombo.Items.Clear()

' Load each animation the currently selected character
' has into the ComboBox
For Each animationName In Character.AnimationNames
	cboCombo.Items.Add(animationName)
Next

2.5 Hiding a character

To hide a character, add this to your code.

Character.Hide()

Part 3 - Make a character talk and play out animations

3.1 Make a character talk

To make a character talk, first, of course, you must load the character (Chapter 2 shows how to load a character), and then, add this to your code:

 Character.Speak("Hello")

This code will make the character say "Hello".

3.2 Make a character play out an animation

To make a character play out an animation, first, of course, you need to find out which animations the character has (Chapter 2 shows how to find out which animations a character has), and then, add this to your code:

Character.Play("Sad")

It is good to have error handling here because, if the character has the "Sad" animation, the character act sad; if the character doesn't have the Sad animation, an error will be generated.

Part 4 - Movement and gesturing

4.1 Moving a character

To make a character move a character, add this to your code:

 Character.MoveTo(20, 45)

This will make the character move to X coordinate 20, and Y coordinate 45.

4.2 Making a character gesture at (point to) certain places

To make a character gesture towards somewhere, add this to your code:

 Character.GestureAt(20, 45)

This will make the character gesture at X coordinate 20, and Y coordinate 45.

Part 5 - Speech recognition, unloading, and credits

5.1 Adding commands to a character

Commands are the words or sentences that the user speaks through the microphone, but, the character will not recognize any command given by the user unless you program a command into it. To add a command to your character, add this to your code:

Character.Commands.Add("LetsGoForLunch.", , _
	"Lets go for lunch.", True, False)

This adds the command "LetsGoForLunch" to your character. The first time "LetsGoForLunch" is written, that is the command Name, the command name is how the character hears the commands. The next time "LetsGoForLunch" is written, that is the command Voice, that is what the Listening tip will show; like if the command name was "KillItAllNow" and the command voice was "KillIt", then the listening tip would display, "Character heard KillIt."

5.2 Making a character respond to a command

To make a character respond to the "LetsGoForLunch" command, add this to your code:

Private SubagtAgent_Command(ByVal sender As Object, _
	ByVal e As AxAgentObjects._AgentEvents_CommandEvent) _
	Handles agtAgent.Command

	Dim command As AgentObjects.IAgentCtlUserInput = _
		CType (e.userInput, AgentObjects.IAgentCtlUserInput)

	If command.Name = "LetsGoForLunch" Then
		Character.Speak("No thanks, I'm not hungry.")
	End If
End Sub

This code is in the agtAgent_Command sub. The If/Then statement says, if the command Name is "LetsGoForLunch" then the character will say, "No thanks, I'm not hungry."

5.3 Making it easier

To make programming commands easier, you can add brackets ([ ]), stars (*), addition signs (+), and vertical bars (|) into the command Name.

You use the star to specify zero or more instances of the word, like this: "Don't* kill me!"
Don't can be said zero or more times and the character will still recognize it as "Don't kill me!"

You use the vertical bar to let the character know that the word can be said different ways or that it can be said multiple times, like this: "Sayev|Save". People with a accent might say "Sayev", while others would say "Save". You would do it like this so that something could be said multiple times:
"call (one|two|three|four|five|six|seven|eight|nine|zero)",
This way the person can say "call 123-455-9321" and so on.

You can use the plus sign the same way you use the star, except with the plus sign its one or more instances of the word.

You can use brackets to tell the character that a person can say a word, but they don't have to, like this: "(hello|hi [there])", this means that the person doesn't have to say "there", and they can say a combination of "hello there", or "hi there", or "hello", and so on.

5.4 Unloading the character

Unloading the character is extremely simple:

agtAgent.Characters.Unload("CharacterID")

5.5 Closing

Now you should have a basic knowledge of how to use Microsoft Agent; so why don't you email me and tell me what you think. How was the tutorial? Was there something more you wanted to learn? I want to know.

5.6 Something else you should get: AgentX

AgentX is my "Agent Character Previewer", a full, object-oriented example on how to use Microsoft Agent 2.0 in Visual Basic .Net. You should download it from Planet-Source-Code.

5.7 Credits

Created by: VisionForce
Email:webmaster@visionforceweb.com