Scripting Solutions with WSH and COM: Have Agents Work for You, Part 2


In "Scripting Solutions with WSH and COM: Have Agents Work for You, Part 1," July 2001, I introduced you to Microsoft Agent 2.0. I showed you how to instantiate an agent, use basic methods and properties to make an agent come alive, and ensure that an agent behaves properly on screen. This month, I continue looking at what you can do with agents. First, I show you how to use animations and various methods and properties to make agents enter, exit, speak, think, gesture, and move. Then, I give you hints about how to explore the animations and expand your knowledge.

Entering and Exiting
As I explained in Part 1, Microsoft Agent comes with four animated characters (i.e., agents): Genie, Merlin, Peedy, and Robby. Each agent comes with a unique set of animations that you can use. Two animations that you'll likely use often are the Show animation, which prompts the agent to make an entrance, and the Hide animation, which prompts the agent to exit gracefully. The animation sequence that appears depends on the agent. For example, Robby makes his entrance by walking through a doorway, whereas Peedy makes an entrance by flying on screen. As Figure 1 shows, Genie makes his entrance by mystically appearing in a puff of smoke.

You can call the Show and Hide animations several ways. For example, you can make Robby appear with the command


Counterintuitively, this command is equivalent to

Robby.Show False

Thus, if you want the agent to appear but you don't want the entrance animation, you use the command

Robby.Show True

If you want Robby to exit the screen gracefully with the Hide animation, you can use either



Robby.Hide False

If you want Robby to immediately disappear with no animation, you use the command

Robby.Hide True

To determine whether an agent is currently visible or hidden, you can call the Visible property. For example, you can use the command


to determine Merlin's status. If the command returns the value of True, Merlin is onscreen. If the command returns the value of False, Merlin isn't onscreen. As Listing 1 shows, you can use this command in an If...Then...Else statement to take action in response to whether Merlin is visible or hidden.

By default, all the animations, including Show and Hide, include sound effects. You can use the SoundEffectsOn property to turn off the sound effects. You set this property to False with code such as

Peedy.SoundEffectsOn = False

To turn the sound effects back on, you set the property to True.

Speaking and Thinking
You can use the Speak method to make an agent speak. As the first code sample in Listing 2 shows, you call the Speak method, then specify the lines to speak. Figure 2 shows the results of running this code. In addition to the message appearing in a cartoon word balloon, Peedy speaks the message if you have a text-to-speech engine installed.

You can use the Characters::Balloon object to alter a cartoon word balloon's appearance. This object has several properties that let you customize the balloon. For example, you can use the FontSize property to change the font size of the text in the balloon.

You can change the way in which an agent speaks by including tags inside the spoken lines. For example, you can emphasize a word by placing the \Emp\ tag in front of that word. You can include the \Chr=""Monotone""\ tag at the beginning of the spoken line to make an agent speak in a monotone voice or the \Chr=""Whisper""\ tag to make the agent whisper. You can change the pitch with the \Pit=n\ tag, where n is the desired pitch in hertz. For example, in the third code sample in Listing 2, I changed Peedy's voice to be high-pitched. Because I also changed the voice to a monotone, this speech pattern is probably more appropriate for Robby the robot than Peedy the parrot.

You can have an agent relay a message without speaking at all. The Think method displays the message you specify in a thought word balloon.

Each agent's animation set includes GestureUp, GestureDown, GestureLeft, and GestureRight. If you want an agent to gesture to a specific spot, you can use the GestureAt method. When you call this method, the agent automatically uses the appropriate gesture animation (i.e., GestureUp, GestureDown, GestureLeft, or GestureRight) to gesture toward the location you specify. You use (x,y) coordinates in pixels to specify the location with code such as

Merlin.GestureAt 300,200

The top left of the screen is the coordinates' point of origin.

Each agent's animation set includes MoveUp, MoveDown, MoveLeft, and MoveRight. If you want an agent to move to a specific location, you can use the MoveTo method. Like the GestureAt method, the MoveTo method needs the (x,y) coordinates in pixels. For example, to move Peedy to the (500,230) coordinates, you use the command

Peedy.MoveTo 500,230

As Figure 3 shows, Peedy then flies to the specified coordinates.

As I explained in Part 1, when you have two or more agents on screen, you need to use the Wait method to tell one agent to wait until the other agent action has completed its action. So, if you want to move Peedy and Genie is also onscreen, you need to use the code

Genie.Wait Peedy.MoveTo 500,230

Exploring the Animations
So far, I've discussed only a few of the animations available for each agent. You can run code to obtain a list of all the available animations for an agent. For example, Listing 3 contains code that lists the available animations for Peedy. Figure 4 shows the results of running this code. To obtain the animation list for another agent, simply change the code Peedy.AnimationNames in the For Each...Next statement to Robby.AnimationNames, Merlin.AnimationNames, or Genie.AnimationNames, depending on which agent you're interested in.

Another way to learn about the available animations is to visit the Microsoft Developer Network (MSDN) Online Library. Go to and navigate to Platform SDK Documentation, User Interface Services, Microsoft Agent. Under Microsoft Agent, you'll find the entry Microsoft Agent Animations for Genie Character as well as entries for the three other characters. When you click one of these entries, a table appears that lists the available animations. The table includes short descriptions of the animations.

Written descriptions are no substitute for viewing the animations. To view the antics of Peedy, Genie, Robby, and Merlin firsthand, you can use the Play method. This method plays the animation you specify for the character you specify. For example, if you want to watch Robby's Surprised animation and Peedy's Confused animation, you use the commands

Robby.Play "Surprised"
Peedy.Play "Confused"

Extending What You've Learned
You now know the basics of how to use Microsoft Agent. Here are some ways you can expand on what you've learned so far:

  • The Microsoft Agent Documentation Web page ( offers a good starting point for further exploring Microsoft Agent. This page offers links to an introduction to the technology, a quick reference guide, a list of error codes and more.

  • Agents can speak multiple languages, including French or Arabic. You can download various language components from the Microsoft Agent Downloads Web page (

  • Agents can respond to spoken text and commands if you use the Speech API (SAPI) toolkit. You can download the needed SAPI 4.0a files from the Microsoft Agent Downloads Web page.

  • The number of people who have experience with Microsoft Agent is growing. A community has formed and developed a Web ring (i.e., a group of Web sites with a common interest that are linked). In this ring, you can find additional characters, tools, and sample code. The starting page is at

  • Genie, Merlin, Peedy, and Robby are only a few of the many agents available. You can find a great selection of agents that you can download for free at You can also purchase agents. One of the best stores for Microsoft Agent materials is on the Agentry Web site ( This store contains more than 380 agents and more than 160 applications.

  • If you plan to use Microsoft Agent often or need to develop code quickly, I recommend that you purchase the Microsoft Agent Scripting Helper (MASH) application from BellCraft Technologies ( With MASH, you simply move the characters around the screen and specify what you want them to say and do. MASH automatically generates the code. MASH supports several scripting and programming languages, including VBScript. The cost is only $19.95.

  • You can use Microsoft Agent within Microsoft Office 2000 and Office 97 applications to create interactive documents and presentations in which characters can speak or use text to help Office application users. You must use Visual Basic for Applications (VBA) as the language. Microsoft has some advanced sample code for you to download at workshop/imedia/agent/sampleoffice.asp.

  • You can create a character from scratch, complete with animations and abilities. For more information and the downloadable kit to create characters, go to workshop/imedia/agent/agentdevdl.asp.

  • A variety of books about Microsoft Agent are available. For example, Microsoft Press offers the Microsoft Agent Software Development Kit ( This book is similar to the software development kit (SDK) in the MSDN Online Library, albeit in a portable book form.

A host of information about Microsoft Agent is available to keep you entertained for quite a while. Who said scripting had to be boring?

Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.