Click to return to the Microsoft Agent home page    
Web Workshop  |  Streaming & Interactive Media  |  Microsoft Agent

Microsoft Agent Technical Notes


Microsoft Corporation

Updated October 1998

Download Download this document in Microsoft Word (.DOC) format (zipped, 10.2K).

The following information documents common questions when developing for Microsoft® Agent.

Contents
General FAQ
Licensing FAQ
Programming/Scripting Information

General FAQ

With the release of Microsoft Agent version 2.0, will my pages built with the previous release (1.52) still work?

Can I define my own character?

Will Microsoft Agent be available for platforms other than Microsoft Windows® 95, Windows 98, and Windows NT®?

Will Microsoft Agent be available in other languages?

How do I uninstall Microsoft Agent?

Licensing FAQ
Programming/Scripting Information

General FAQ

With the release of Microsoft Agent version 2.0, will my pages built with the previous release (1.52) still work?

The 2.0 release of Microsoft Agent is compatible with the previous 1.52 release. However, note that Agent 2.0 installs to a different directory than Agent 1.5. If you are using the Agent ActiveX® control and you keep both versions 1.5 and 2.0 installed, you should convert your code to use the 2.0 version to avoid any design time incompatibilities.

TopBack to list of questions

Can I define my own character?

Yes. You can use any animation rendering package, provided that you can produce your images in a 2-bit (monochrome), 4-bit, or 8-bit color Windows® bitmap format. Then you can use the Microsoft Agent Character Editor to assemble and compile your animations.

TopBack to list of questions

Will Microsoft Agent be available for platforms other than Microsoft Windows® 95, Windows 98, and Windows NT®?

Microsoft Agent is currently only offered for the Microsoft Windows platform.

TopBack to list of questions

Will Microsoft Agent be available in other languages?

Microsoft Agent includes support for the following languages in addition to English (U.S.): Arabic, French, German, Hebrew, Italian, Japanese, Korean, Spanish, simplified Chinese and traditional Chinese. We are also considering other languages. Please note that this language support is for Agent's core services; speech input and output engines are not a part of Agent core services and so we do not currently offer speech engine support for all the languages for which Agent is available. However, additional language speech engines may be available from other vendors. Check our Speech Recognition and Text-To-Speech pages for further information on what engines are available.

TopBack to list of questions

How do I uninstall Microsoft Agent?

Microsoft Agent 2.0 has been designed to be a Microsoft operating system component. As a result, once it is installed it cannot be uninstalled without reinstalling the operating system.

TopBack to list of questions

Licensing FAQ

Can I distribute Microsoft Agent and its characters?

Microsoft Agent can be automatically downloaded directly from the Microsoft site by including the Microsoft Agent control's CLSID in an HTML <OBJECT> tag on your Web page, which will automatically offer to download and install the control when a user without Microsoft Agent installed loads the page. Such use is covered in the Microsoft Agent End User License agreement that displays when Microsoft Agent is installed. This license does not include provisions for you to distribute Agent from your server or as a part of your application. Application developers who wish to include Microsoft Agent and any of its components as part of their application must complete a distribution license. A distribution license is required for any individual or company that wishes to distribute any Microsoft Agent component, regardless whether for profit. For more information about distribution licenses, see the Licensing document.

TopBack to list of questions

Can I use the Microsoft Agent characters?

You may use the Microsoft characters designated for download at the Microsoft Agent Web site subject to the conditions included in the End User License Agreement or the Microsoft Agent Distribution License Agreement. For further information, see our Licensing page. Note that such use requires that the character be used only as part of a script or application that uses Microsoft Agent. The character images alone cannot be included in packaging or promotional material.

Note that the Microsoft Agent 2.0 characters (ACS format) available from our Downloading page, automatically installs to the \Chars subdirectory of Microsoft Agent's directory (that is installed in the directory where Windows is installed. You may access the ACF/ACA version of the characters from the Microsoft servers following the information included on the Microsoft Agent Character Data page. To post this latter format to your own server, you must submit a distribution license agreement and request these files. They are not made available without a valid distribution license.

TopBack to list of questions

How do I modify the Microsoft supplied characters?

Modification of the Microsoft supplied characters is not supported. However, you may create and distribute your own characters.

TopBack to list of questions

Can I distribute the speech engines that are supplied with Microsoft Agent with my own applications?

Microsoft licenses certain speech engines for use with Microsoft Agent-enabled Web sites and applications. To see the engines that may be licensed, see the Licensing page.

TopBack to list of questions

Can I distribute the Microsoft Agent Character Editor and Microsoft Linguistic Information Sound Editing Tool?

Distribution of these tools is limited to downloading them from the Microsoft Web site or dispensing them as part of any software development kit Microsoft may provide.

TopBack to list of questions

Programming/Scripting Information

When I use Microsoft Visual Basic® (or other development tools) for scripting Microsoft Agent, I do not see all the properties and events used in your samples. How do I access them?

Most of the events, methods, and properties supported by the Microsoft Agent control are exposed only at run time. Consult Programming the Microsoft Agent Control for further information.

TopBack to list of questions

The Map tag (or some other tag) doesn't seem to work.

Some tags include quoted strings. For some programming languages, such as Visual Basic® Scripting Edition (VBScript) and Visual Basic®, you may have to use two quote marks to designate the tag's parameter or concatenate a double-quote character as part of the string. The latter is shown in this Visual Basic example:

Agent1.Characters("Genie").Speak "This is \map=" + chr(34) + "Spoken text" _
+ chr(34) + "=" + chr(34) + "Balloon text" + chr(34) + "\."

For C, C++, and Java programming, precede backslashes and double quotes with a backslash. For example:

BSTR bszSpeak = SysAllocString(L"This is \\map=\"Spoken text\"=\"Balloon text\"\\");

pCharacter->Speak(bszSpeak, ......);

Note that Microsoft Agent does not support all the tags specified in the Microsoft Speech API. In addition, support for some parameters may depend on the text-to-speech engine installed. For further information, see Speech Output Tags.

TopBack to list of questions

I seem to get RequestStart and RequestComplete events in my scripts even though I don't set any requests.

This is a problem in Visual Basic® Scripting Edition (VBScript) 1.0. It has been addressed in VBScript 2.0 and subsequent versions, which can be downloaded from the VBScript Web page  Non-MSDN Online link.

TopBack to list of questions

I don't seem to get RequestStart and RequestComplete events in my script (or program).

This could be caused by one of the following problems:

TopBack to list of questions

I am using the Microsoft Agent control with other ActiveX® controls on my Web page, and I don't seem to get any events.

Check to see if the other controls are correctly installed. If another ActiveX control fails to correctly register itself, the Microsoft Agent control may receive its events.

TopBack to list of questions

What programming languages can I use to program the Microsoft Agent control?

Microsoft Agent should be supportable from any language that supports the ActiveX interface. It includes code samples for Microsoft Visual Basic®, VBScript, JScript®, C/C++, and Java.

TopBack to list of questions

Can I access the parameters returned from Microsoft Agent using JScript®?

Yes, but currently the only way to do this is using the <SCRIPT LANGUAGE="JScript" FOR="object" EVENT="event()"> syntax. Although this syntax is supported for Microsoft Internet Explorer, other browsers do not support it, so you may want to avoid using JScript for this part of your page's script.

TopBack to list of questions

Can Microsoft Agent be used with speech recognition or speech synthesis (text-to-speech, or TTS) engines other than those supplied by Microsoft?

Yes, provided that the engine supports the Microsoft Speech API (SAPI) interfaces required by Microsoft Agent. Check with the engine supplier. For complete details on the SAPI interfaces required by Microsoft Agent, see Speech Engine Support Requirements.

TopBack to list of questions

My page includes HTML Object tags for Microsoft Agent, the Lernout & Hauspie TruVoice TTS engine, and the Microsoft Command and Control speech recognition engine, but not all the components install.

Typically, the problem can be corrected by refreshing the page. As a general practice, it is best to specify the Microsoft Agent Control <OBJECT> tag first, then the Lernout & Hauspie TruVoice engine, then the Command and Control speech recognition engine.

TopBack to list of questions

After calling the MoveTo method, my character seems to freeze even though I have Return animations assigned to Moving state animations.

When you play an animation, the animation services continue to display its last frame until another animation is called. Therefore, you should play another animation after calling MoveTo. If you defined a Return animation for the Moving state animation, the server will play it first.

When I query the character's Pitch property, it returns a value of -1.

This occurs if the character has been compiled using a speech engine's default pitch property: that is, the pitch was not changed when the character was built.

TopBack to list of questions

When running under Internet Explorer 4.0 Preview 1 or 2, events don't fire after Microsoft Agent has been running, or the character leaves behind parts of its animation.

These problems are related to the Internet Explorer 4.0 Preview 1 and 2. Install the official commercial release of Internet Explorer 4.0 Non-MSDN Online link.

TopBack to list of questions

When my code attempts to set the TTS mode ID for a text-to-speech engine, I get the following error: An outgoing call cannot be made since the application is dispatching an input-synchronous call.

To set the TTSModeID property, you must have Speech.dll installed. This is typically a part of the speech engine's installation code. You may also install this by installing the Speech object control panel, available from the Microsoft Agent Downloads page.

TopBack to list of questions

When I retry loading a character that failed to load, the call fails with a "Character already loaded" error.

The Microsoft Agent control does not unload a character object (release the reference) when its associated character file fails to load. If you want to retry loading the character, you must explicitly call Unload before you call Load the second time. If you attempt this from a Web page script, you also need to precede the Unload call with an On Error Resume Next statement, or the Unload call will also fail. (Note that JScript has no On Error Resume Next statement.)

However, you may not need to include code to immediately retry loading a character when the file fails to load. Microsoft Internet Explorer and the Microsoft Agent server component automatically attempt to retry several times, so the chances that your retry will result in a successful load are remote. A better strategy is to wait (set a timer) a few seconds before you retry.

TopBack to list of questions

How can I install Microsoft Agent as part of my application or from my Web server?

You can install Agent from the Microsoft Web site by including its CLSID in an HTML Object tag. However, if you want to include and install Agent from your own application installation program or from your own server, you must download the Microsoft Agent self-installing cabinet file, by downloading it from the Downloads page. When downloading, choose the browser's Save rather than Run option. Whenever this file is run, it automatically will install Microsoft Agent on the target machine. Therefore, you can specify the file in your installation script.

Note that to distribute Microsoft Agent in this way requires that you submit a distribution license agreement. For further information, see the licensing page. Further information is included in the license agreement about installation.

Do not attempt to install Microsoft Agent by copying its various .DLLs and attempting to register it yourself. Attempting to install Agent by any other means than executing its self-installing cabinet file, is not supported.

The target system must also include recent versions of MSVCRT.DLL (VC++ runtime). REGSVR32.EXE (registration tool included with Microsoft VC++), and COM. The best way to ensure the correct versions are installed, is to require that Microsoft Internet Explorer 3.02 or later is installed. However, you can also license these runtime requirements. (For the latest version of COM, access the DCOM update from the Microsoft web site.)

Microsoft Agent 2.0 will not install on Microsoft Windows NT5 since this version of the operating system already includes Agent.

TopBack to list of questions

Can I use the Visual Basic® Setup Wizard to install Microsoft Agent?

While you can create your own installation program using Visual Basic (VB) code you can't use the Visual Basic Setup Wizard to do this. To install Agent from VB, you can use Shell command, specifying the Microsoft Agent self-installing cabinet file.

TopBack to list of questions

How do I install Microsoft Agent to install on Windows 2000?

Microsoft Agent 2.0 does not install on Windows 2000 because it is already included as a part of the operating system.

TopBack to list of problems

Agentsvr crashes when call Speak with a WAV file.

This may result when the character has been using TTS for spoken output, then chanages to use a WAV file. Text was not supplied in the first parameter of the Speak method.

To avoid the crash, include a space character in the first parameter of the Speak method, even if you have not text output.



Back to topBack to top

Did you find this material useful? Gripes? Compliments? Suggestions for other articles? Write us!

© 1999 Microsoft Corporation. All rights reserved. Terms of use.