From f1b10ee40238d0bc2b078706d33f76387f54e536 Mon Sep 17 00:00:00 2001 From: Curtis Man Date: Thu, 6 Feb 2025 17:47:29 -0800 Subject: [PATCH] update --- README.md | 2 + docs/tutorial/agent.md | 243 +++++++++++++ .../tutorial}/imgs/image-cli.png | Bin .../tutorial}/imgs/image-files.png | Bin .../tutorial}/imgs/image-shell.png | Bin ts/examples/agentExamples/echo/README.md | 2 +- ts/examples/agentExamples/echo/package.json | 3 +- .../echo/src/echoActionHandler.ts | 68 +--- ...hoActionsSchema.ts => echoActionSchema.ts} | 0 .../agentExamples/echo/src/echoManifest.json | 2 +- ts/examples/agentExamples/measure/README.md | 2 +- ts/packages/agentSdk/ExternalAgents_README.md | 324 ------------------ ts/packages/agentSdk/README.md | 2 +- ts/packages/dispatcher/README.md | 24 +- 14 files changed, 265 insertions(+), 407 deletions(-) create mode 100644 docs/tutorial/agent.md rename {ts/packages/agentSdk => docs/tutorial}/imgs/image-cli.png (100%) rename {ts/packages/agentSdk => docs/tutorial}/imgs/image-files.png (100%) rename {ts/packages/agentSdk => docs/tutorial}/imgs/image-shell.png (100%) rename ts/examples/agentExamples/echo/src/{echoActionsSchema.ts => echoActionSchema.ts} (100%) delete mode 100644 ts/packages/agentSdk/ExternalAgents_README.md diff --git a/README.md b/README.md index a78d788d0..1b95a11bd 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,8 @@ Microsoft TypeAgent Repo is a mono-repo, with components organized with the foll - [`python`](./python) Python code ([Readme](./python/README.md)) - [`dotnet`](./dotnet) Dotnet (C#) code ([Readme](./dotnet/README.md)) +For developer who want to experiment with TypeAgent and see how typed action schema drives actions, the [Agent Shell](./ts/packages/shell) example allow additional agent to be installed/registered to extent functionality. The `Echo` agent [tutorial](./docs/tutorial/agent.md) is a starting point to create a plugin agent, and [Agent SDK](./ts/packages/agentSdk/) provides the details of the interface between [Dispatcher](./ts/packages/dispatcher) and the agent. + ## Contributing This project welcomes contributions and suggestions. Most contributions require you to diff --git a/docs/tutorial/agent.md b/docs/tutorial/agent.md new file mode 100644 index 000000000..8ccb509c4 --- /dev/null +++ b/docs/tutorial/agent.md @@ -0,0 +1,243 @@ +# External Agents + +The TypeAgent repo includes several example [agents](../../ts/packages/agents/). You can also build **your own application agents** **_outside_** the TypeAgent repo by using the [agent-sdk](../../ts/packages/agentSdk/README.md). You can package these agents as npm packages and surface them in the [TypeAgent Shell](../../ts/packages/shell) and [TypeAgent CLI](../../ts/packages/cli). + +This document describes how you can build your own application agents. + +## Prerequisites + +Begin by exploring the following: + +- **Agent-Sdk**: Read about the architecture of the [**agent-sdk**](../../ts/packages/agentSdk/README.md). +- **Example Agents**: + - Review agents under the [agents](../../ts/packages/agents) directory. The [List](../../ts/packages/agents/list/) agent provides a good example and template for building an agent. + - The [Echo](../../ts/examples/agentExamples/echo/) agent illustrates the basics of building your own external application agents. + +## Steps to build an `Echo` agent: + +For the rest of the documentation, we will assume that the external agent is named **echo**. The echo agent performs a single action: echos any input back to the user. + +You can see the end result of this tutorial in [Echo](../../ts/examples/agentExamples/echo/) with some modification (NOTE: The only difference is the @typeagent/agent-sdk dependency) + +### Step 1: Create and author the `Echo` agent package + +Follow the following steps to create the `Echo` agent packages manually. Start by create a directory `echo`. Then populate the directory with the following content: + +**package.json** [package.json](../../ts/examples/agentExamples/echo/package.json) : + +The `package.json` contains references to **handler** and **manifest** files in the `exports` field. + +```json +{ + "name": "echo", + "version": "0.0.1", + "description": "Echo example for TypeAgent", + "license": "MIT", + "author": "Microsoft", + "type": "module", + "exports": { + "./agent/manifest": "./src/echoManifest.json", + "./agent/handlers": "./dist/echoActionHandler.js" + }, + "scripts": { + "build": "npm run tsc", + "clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log", + "tsc": "tsc -b" + }, + "keywords": [], + "dependencies": { + "@typeagent/agent-sdk": "0.0.1" + }, + "devDependencies": { + "rimraf": "^5.0.5", + "typescript": "^5.4.2" + } +} +``` + +Every application agent requires the following files to be present in the agent's [**source**](../../ts/examples/agentExamples/echo/src/) directory. + +- **Agent Manifest File**: The manifest file is used to register the agent with the TypeAgent ecosystem. +- **Action Schema File**: The action schema file is used to define the actions that the agent can perform. +- **Agent Action Handler**: Your code that perform's the agent's actions. + +**Agent Manifest File** : [`src/echoManifest.json`](../../ts/examples/agentExamples/echo/src/echoManifest.json) + +The manifest file contain reference in `schemaFile` to the path to **schema** file (relative path to the **manifest** file) and the `schemaType` corresponds to the union type of all the actions. + +```json +{ + "emojiChar": "🦜", + "schema": { + "description": "A basic echo agent.", + "schemaFile": "./echoActionSchema.ts", + "schemaType": "EchoAction" + } +} +``` + +**Agent Action Schema File** : [`src/echoActionSchema.ts`](../../ts/examples/agentExamples/echo/src/echoActionSchema.ts) + +```ts +export type EchoAction = GenEchoAction; + +// If the user asks to echo a message back, the system will return a GenEchoAction. The text parameter is the message to be echoed back. +// will contain the text to be echoed back to the user. +export type GenEchoAction = { + actionName: "echoGen"; + parameters: { + text: string; + }; +}; +``` + +**Agent action handler** : [`src/echoActionHandler.ts`](../../ts/examples/agentExamples/echo/src/echoActionHandler.ts) + +```ts +import { ActionContext, AppAgent, TypeAgentAction } from "@typeagent/agent-sdk"; +import { + createActionResultFromTextDisplay, + createActionResultFromError, +} from "@typeagent/agent-sdk/helpers/action"; +import { EchoAction } from "./echoActionSchema.js"; + +export function instantiate(): AppAgent { + return { + initializeAgentContext: initializeEchoContext, + executeAction: executeEchoAction, + }; +} + +type EchoActionContext = { + echoCount: number; +}; + +async function initializeEchoContext(): Promise { + return { echoCount: 0 }; +} + +async function executeEchoAction( + action: TypeAgentAction, + context: ActionContext +) { + // The context created in initializeEchoContext is returned in the action context. + const echoContext = context.sessionContext.agentContext; + switch (action.actionName) { + case "echoGen": + const displayText = `>> Echo ${++echoContext.echoCount}: ${ + action.parameters.text + }`; + return createActionResultFromTextDisplay(displayText, displayText); + + default: + return createActionResultFromError("Unable to process the action"); + } +} +``` + +**Typescript build config file** [`tsconfig.json`](../../ts/examples/agentExamples/echo/tsconfig.json) + +```json +{ + "compilerOptions": { + "composite": true, + "target": "es2021", + "lib": ["es2021"], + "module": "node16", + "declaration": true, + "declarationMap": true, + "esModuleInterop": true, + "exactOptionalPropertyTypes": true, + "forceConsistentCasingInFileNames": true, + "incremental": true, + "noEmitOnError": true, + "noUnusedLocals": true, + "skipLibCheck": true, + "strict": true, + "sourceMap": true, + "rootDir": "./src", + "outDir": "./dist" + }, + "include": ["./src/**/*"], + "ts-node": { + "esm": true + } +} +``` + +#### Folder structure for **Echo** agent: + +![alt text](./imgs/image-files.png) + + + +#### Step 2: Build the Agent + +First make sure the [TypeAgent's typescript code](../../ts) is built. + +- Go to `/ts` +- `pnpm i` +- `pnpm run build` + +Then create a link globally to the `@typeagent/agent-sdk` package for the `Echo` agent to consume. + +- Go to `/ts/packages/agentSdk` +- `npm link` + +In the `Echo` package, run the following to link to `@typeagent/agent-sdk` package and build + +- `npm link @typeagent/agent-sdk` +- `npm install` +- `npm run build` + +### Step 3: Install `Echo` agent in TypeAgent cli or shell. + +Start TypeAgent [Shell](../../ts/packages/shell) or [CLI](../../ts/packages/cli) + +```bash +# you can run these commands from the `ts` folder +# in the TypeAgent root. + +pnpm run cli interactive + +or + +pnpm run shell +``` + +In the [Shell](../../ts/packages/shell) or [CLI](../../ts/packages/cli), install the echo agent and check the status by issuing the command: + +``` +@install echo +@config agent +``` + +The `Echo` agent should be in the list and enabled. + +### Step 4: See the `Echo` agent in action + +`Echo` agent is now ready. Test it out by issuing some request to see the `Echo` agent in action + +When to run the cli this is how interaction with the `Echo` agent will look like: +![alt text](./imgs/image-cli.png) + +When to run the shell this is how interaction with the `Echo` agent will look like: +![alt text](./imgs/image-shell.png) + +The `Echo` agent will be reloaded again after installation. It can be uninstalled using the command: + +``` +@uninstall echo +``` + +## Next step + +Start modifying the `Echo` agent and add new action schema and action handlers. + +## Trademarks + +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft +trademarks or logos is subject to and must follow +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. +Any use of third-party trademarks or logos are subject to those third-party's policies. diff --git a/ts/packages/agentSdk/imgs/image-cli.png b/docs/tutorial/imgs/image-cli.png similarity index 100% rename from ts/packages/agentSdk/imgs/image-cli.png rename to docs/tutorial/imgs/image-cli.png diff --git a/ts/packages/agentSdk/imgs/image-files.png b/docs/tutorial/imgs/image-files.png similarity index 100% rename from ts/packages/agentSdk/imgs/image-files.png rename to docs/tutorial/imgs/image-files.png diff --git a/ts/packages/agentSdk/imgs/image-shell.png b/docs/tutorial/imgs/image-shell.png similarity index 100% rename from ts/packages/agentSdk/imgs/image-shell.png rename to docs/tutorial/imgs/image-shell.png diff --git a/ts/examples/agentExamples/echo/README.md b/ts/examples/agentExamples/echo/README.md index c19cc2817..40303d556 100644 --- a/ts/examples/agentExamples/echo/README.md +++ b/ts/examples/agentExamples/echo/README.md @@ -1,6 +1,6 @@ # Echo Agent -The Echo Agent demonstrates how to use the [agent-sdk](../../../packages/agentSdk/ExternalAgents_README.md) to write agents as installable packages. +The Echo Agent demonstrates how to use the [agent-sdk](../../../../docs/tutorial/agent.md) to write agents as installable packages. ## Trademarks diff --git a/ts/examples/agentExamples/echo/package.json b/ts/examples/agentExamples/echo/package.json index e80b04f4b..0a3654583 100644 --- a/ts/examples/agentExamples/echo/package.json +++ b/ts/examples/agentExamples/echo/package.json @@ -14,11 +14,10 @@ "type": "module", "exports": { "./agent/handlers": "./dist/echoActionHandler.js", - "./agent/manifest": "./dist/echoManifest.json" + "./agent/manifest": "./src/echoManifest.json" }, "scripts": { "build": "npm run tsc", - "postbuild": "copyfiles -u 1 \"src/**/*Schema*.ts\" \"src/**/*Manifest*.json\" dist", "clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log", "prettier": "prettier --check . --ignore-path ../../../.prettierignore", "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore", diff --git a/ts/examples/agentExamples/echo/src/echoActionHandler.ts b/ts/examples/agentExamples/echo/src/echoActionHandler.ts index f39a81e03..e3f2d4340 100644 --- a/ts/examples/agentExamples/echo/src/echoActionHandler.ts +++ b/ts/examples/agentExamples/echo/src/echoActionHandler.ts @@ -1,81 +1,39 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT License. - -import { - ActionContext, - AppAction, - AppAgent, - SessionContext, - ActionResult, -} from "@typeagent/agent-sdk"; +import { ActionContext, AppAgent, TypeAgentAction } from "@typeagent/agent-sdk"; import { createActionResultFromTextDisplay, createActionResultFromError, } from "@typeagent/agent-sdk/helpers/action"; - -import { EchoAction } from "./echoActionsSchema.js"; +import { EchoAction } from "./echoActionSchema.js"; export function instantiate(): AppAgent { return { initializeAgentContext: initializeEchoContext, - updateAgentContext: updateEchoContext, executeAction: executeEchoAction, }; } type EchoActionContext = { echoCount: number; - echoRequests: Set | undefined; }; -async function initializeEchoContext() { - return { - echoCount: 0, - echoRequests: undefined, - }; -} - -async function updateEchoContext( - enable: boolean, - context: SessionContext, -): Promise { - if (enable) { - context.agentContext.echoRequests = new Set(); - context.agentContext.echoCount = 0; - } - context.agentContext.echoCount++; +async function initializeEchoContext(): Promise { + return { echoCount: 0 }; } async function executeEchoAction( - action: AppAction, + action: TypeAgentAction, context: ActionContext, ) { - let result = await handleEchoAction( - action as EchoAction, - context.sessionContext.agentContext, - ); - return result; -} - -async function handleEchoAction( - action: EchoAction, - echoContext: EchoActionContext, -) { - let result: ActionResult | undefined = undefined; - let displayText: string | undefined = undefined; + // The context created in initializeEchoContext is returned in the action context. + const echoContext = context.sessionContext.agentContext; switch (action.actionName) { case "echoGen": - displayText = `>> Echo: ${action.parameters.text}`; - result = createActionResultFromTextDisplay( - displayText, - displayText, - ); - break; + const displayText = `>> Echo ${++echoContext.echoCount}: ${ + action.parameters.text + }`; + return createActionResultFromTextDisplay(displayText, displayText); + default: - result = createActionResultFromError( - "Unable to process the action", - ); - break; + return createActionResultFromError("Unable to process the action"); } - return result; } diff --git a/ts/examples/agentExamples/echo/src/echoActionsSchema.ts b/ts/examples/agentExamples/echo/src/echoActionSchema.ts similarity index 100% rename from ts/examples/agentExamples/echo/src/echoActionsSchema.ts rename to ts/examples/agentExamples/echo/src/echoActionSchema.ts diff --git a/ts/examples/agentExamples/echo/src/echoManifest.json b/ts/examples/agentExamples/echo/src/echoManifest.json index 27ff2d86f..a37ea067d 100644 --- a/ts/examples/agentExamples/echo/src/echoManifest.json +++ b/ts/examples/agentExamples/echo/src/echoManifest.json @@ -2,7 +2,7 @@ "emojiChar": "🦜", "schema": { "description": "A basic echo agent.", - "schemaFile": "echoActionsSchema.ts", + "schemaFile": "./echoActionSchema.ts", "schemaType": "EchoAction" } } diff --git a/ts/examples/agentExamples/measure/README.md b/ts/examples/agentExamples/measure/README.md index 3969e855e..20ae52630 100644 --- a/ts/examples/agentExamples/measure/README.md +++ b/ts/examples/agentExamples/measure/README.md @@ -6,7 +6,7 @@ Work in progress. ## Installation -- Follow the standard exteneral [Agent installation steps](../../../packages/agentSdk/ExternalAgents_README.md#install_agent) +- Follow the standard external [Agent installation steps](../../../../docs/tutorial/agent.md#step-3-install-echo-agent-in-typeagent-cli-or-shell) ## Trademarks diff --git a/ts/packages/agentSdk/ExternalAgents_README.md b/ts/packages/agentSdk/ExternalAgents_README.md deleted file mode 100644 index bfc7beead..000000000 --- a/ts/packages/agentSdk/ExternalAgents_README.md +++ /dev/null @@ -1,324 +0,0 @@ -# External Agents - -The TypeAgent repo includes several example [agents](../../packages/agents/). You can also build **your own application agents** **_outside_** the TypeAgent repo by using the [agent-sdk](./README.md). You can package these **_external_** agents as npm packages and surface them in the [TypeAgent Shell](../shell) and [TypeAgent CLI](../cli). - -This document describes how you can build your own external application agents. - -## Prerequisites - -Begin by exploring the following: - -- **Agent-Sdk**: Read about the architecture of the [**agent-sdk**](./README.md). -- **Example Agents**: - - Review agents under the [agents](../agents) directory. The [List](../agents/list/) agent provides a good example and template for building an agent. - - The [Echo](../../examples/agentExamples/echo/) agent illustrates the basics of building your own external application agents. - -## Steps to build an `Echo` agent: - -For the rest of the documentation, we will assume that the external agent is named **echo**. The echo agent performs a single action: echos any input back to the user. - -### Step 1: Create a new package for the agent - -**package.json** : Run `npm init -y` to create a new package. - -The example [package.json](../../examples//agentExamples//echo/package.json) contains references to **handler**, **schema** and **manifest** files. **Step 2** explains what they are. - -```json -{ - "name": "echo", - "version": "0.0.1", - "description": "Echo example for TypeAgent", - "license": "MIT", - "author": "Microsoft", - "type": "module", - "exports": { - "./agent/manifest": "./dist/echoManifest.json", - "./agent/handlers": "./dist/echoActionHandler.js" - }, - "scripts": { - "build": "npm run tsc && npm run copy:manifest", - "postbuild": "copyfiles -u 1 \"src/**/*Schema*.ts\" \"src/**/*Manifest*.json\" dist", - "clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log", - "prettier": "prettier --check . --ignore-path ../../../.prettierignore", - "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore", - "tsc": "tsc -b" - }, - "keywords": [], - "dependencies": { - "@typeagent/agent-sdk": "0.0.1" - }, - "devDependencies": { - "copyfiles": "^2.4.1", - "prettier": "^3.2.5", - "rimraf": "^5.0.5", - "typescript": "^5.4.2" - } -} -``` - -#### Agent SDK dependency - -Add `agent-sdk` as a dependency in the package.json file. - -- If you are developing your agent in the TypeAgent repo or workspace, reference the SDK directly - -``` - "dependencies": { - "@typeagent/agent-sdk": "workspace:*" - } -``` - -- If your agent uses an external **npm** registry for agent-sdk, create a `.npmrc` file in the [externalagents](#scaffolding) (see section on [Scaffolding](#scaffolding)) directory with the following contents: - -``` - -@typeagent:registry=https:// -always-auth=true - -``` - -### Step 2: Author your agent - -Every application agent requires the following files to be present in the agent's [**source**](../../examples/agentExamples/echo/src/) directory. - -- **Agent Manifest File**: The manifest file is used to register the agent with the TypeAgent ecosystem. -- **Action Schema File**: The action schema file is used to define the actions that the agent can perform. -- **Agent Action Handler**: Your code that perform's the agent's actions. - -**Agent Manifest File** : [`echoManifest.json`](../../examples/agentExamples/echo/src/echoManifest.json) - -```json -{ - "emojiChar": "🦜", - "schema": { - "description": "A basic echo agent.", - "schemaFile": "echoActionsSchema.ts", - "schemaType": "EchoAction" - } -} -``` - -**Agent Action Schema File** : [`echoActionsSchema.ts`](../../examples//agentExamples/echo/src/echoActionsSchema.ts) - -```ts -export type EchoAction = GenEchoAction; - -// If the user asks to echo a message back, the system will return a GenEchoAction. The text parameter is the message to be echoed back. -// will contain the text to be echoed back to the user. -export type GenEchoAction = { - actionName: "echoGen"; - parameters: { - text?: string; - // Generate an alternate response based on the request - altResponse?: string; - }; -}; -``` - -**Agent action handler** : [`echoActionHandler.ts`](../../examples//agentExamples/echo/src/echoActionHandler.ts) - -```ts -// Below is sample code for a simple echo agent. - -import { - ActionContext, - AppAction, - AppAgent, - SessionContext, - ActionResult, -} from "@typeagent/agent-sdk"; -import { - createActionResultFromTextDisplay, - createActionResultFromError, -} from "@typeagent/agent-sdk/helpers/action"; -import { EchoAction } from "./echoActionsSchema.js"; - -export function instantiate(): AppAgent { - return { - initializeAgentContext: initializeEchoContext, - updateAgentContext: updateEchoContext, - executeAction: executeEchoAction, - }; -} - -type EchoActionContext = { - echoCount: number; - echoRequests: Set | undefined; -}; - -async function initializeEchoContext() { - return { - echoCount: 0, - echoRequests: undefined, - }; -} - -async function updateEchoContext( - enable: boolean, - context: SessionContext, -): Promise { - if (enable) { - context.agentContext.echoRequests = new Set(); - context.agentContext.echoCount = 0; - } - context.agentContext.echoCount++; -} - -async function executeEchoAction( - action: AppAction, - context: ActionContext, -) { - let result = await handleEchoAction( - action as EchoAction, - context.sessionContext.agentContext, - ); - return result; -} - -async function handleEchoAction( - action: EchoAction, - echoContext: EchoActionContext, -) { - let result: ActionResult | undefined = undefined; - let displayText: string | undefined = undefined; - switch (action.actionName) { - case "echoGen": - displayText = `>> Echo: ${action.parameters.text}`; - result = createActionResultFromTextDisplay(displayText, displayText); - break; - default: - result = createActionResultFromError("Unable to process the action"); - break; - } - return result; -} -``` - -#### Folder structure for **Echo** agent: - -![alt text](./imgs/image-files.png) - - - -### Step 3: Install your Agent - - - -- Go to the **TypeAgent Profiles** directory: - - - Use the **@session info** command in either the TypeAgent CLI or Shell to get the **path to the current profile directory**. - - The profile directory is typically located here: - - - bash: `cd ~.typeagent\profiles\dev` - - Windows: `cd %USERPROFILE%\.typeagent\profiles\dev` - -- Create an **externalAgentsConfig.json** file in this directory. This file contains references to all external agents. - - ```json - { - "agents": { - "echo": { - "type": "module", - "name": "echo", - "path": - } - } - } - ``` - -- If you are working in the TypeAgent repo or workspace, **add a path to your agent** in externalAgentsConfig.json. - - The path should point to the folder where your build places output files. E.g. the path to the example **Echo** agent is `\ts\examples\agentExamples\echo\dist` - - Ensure that schema and manifest files are placed in the same folder using a post-build step, as shown in the sample [package.json](../../examples//agentExamples//echo/package.json). -- **Else** follow the **_steps below_** to **build a package** for your agent and register it. - -#### Step 3.1: Build `Echo` agent package - -Run `npm pack` from the echo agent's directory to create a tarball of the agent package. This tarball(echo-0.0.1.tgz) can be used to install the agent in the TypeAgent ecosystem. - -#### Step 3.2: Install the `Echo` agent - -Copy the tar file to the [TypeAgent profiles directory](#profiles). - - - -#### Step 3.3: Scaffolding for external agents - -TypeAgent links external agents using a **scaffold**. Run the following command to scaffold the external agent: - -- Go to the [TypeAgent Profiles](#profiles) directory -- Create an **externalagents** directory - - bash: - ```bash - mkdir externalagents && cd externalagents - npm init -y - ``` - - Windows: - ``` - md externalagents && cd externalagents - npm init -y - ``` - -If your external agent depends on the an external artifact registry for agent-sdk, create a `.npmrc` file in the externalagents directory with the following contents: - -``` -@typeagent:registry=https:// -always-auth=true -``` - -Now add dependency to the echo agent using the following command: - -```bash -npm i ..\echo-0.0.1.tgz -``` - -The above command will install the echo agent in the externalagents node package. - -```json -{ - "name": "externalagents", - "version": "1.0.0", - "description": "External agents package contianing references to TypeAgent application agents.", - "main": "index.js", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "author": "", - "license": "MIT License", - "dependencies": { - "echo": "file:../echo-0.0.1.tgz" - } -} -``` - -### Step 4: Run the TypeAgent cli or shell to see the `Echo` agent in action. - -```bash -# you can run these commands from the `ts` folder -# in the TypeAgent root. - -pnpm run cli interactive - -or - -pnpm run shell -``` - -If the above steps are followed correctly, you should see the `Echo` agent in the TypeAgent ecosystem. - -When to run the cli this is how interaction with the `Echo` agent will look like: -![alt text](./imgs/image-cli.png) - -When to run the shell this is how interaction with the `Echo` agent will look like: -![alt text](./imgs/image-shell.png) - -## Trademarks - -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft -trademarks or logos is subject to and must follow -[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. - -``` - -``` diff --git a/ts/packages/agentSdk/README.md b/ts/packages/agentSdk/README.md index 825ceb0a1..f25342d6f 100644 --- a/ts/packages/agentSdk/README.md +++ b/ts/packages/agentSdk/README.md @@ -4,7 +4,7 @@ This package contains interface definitions and utilities for implementing a **D - [List](../agents/list/) agent is a good example and initial template for building a dispatcher agent. - The [Dispatcher README](../dispatcher/README.md) contains instructions on how to register a dispatcher agent with the TypeAgent Dispatcher. -- You can also create agents as [installable packages](./ExternalAgents_README.md) called [**external application agents**](./ExternalAgents_README.md). +- You can also create [agents as NPM packages](../../../docs/tutorial/agent.md) that can be installed/register to the [Shell](../shell) or [CLI](../cli) ## Agent SDK diff --git a/ts/packages/dispatcher/README.md b/ts/packages/dispatcher/README.md index 8d0c6f98c..7629b7588 100644 --- a/ts/packages/dispatcher/README.md +++ b/ts/packages/dispatcher/README.md @@ -163,29 +163,9 @@ Use the `@const ` command at the prompt to control the construction store. ## Adding Dispatcher Agent -Addition Dispatcher Agent can be create to extend the capabilities of the **single personal assistant**. +Additional Dispatcher Agent can be create and added to the dispatcher to extend the capabilities of TypeAgent as a **single personal assistant**. [Agent SDK](../agentSdk) defines the interfaces and helper needed to develop an agent. The `Echo` agent [tutorial](../../../docs/tutorial/agent.md) illustrate the steps to create a basic agent in a NPM module and install into TypeAgent's [shell](../shell) and [CLI](../cli). -### NPM Module - -Go to Agent SDK [README](../agentSdk/README.md) for details on how to create a dispatcher agent in a NPM modules. - -Dispatcher currently only supports "static" loading of dispatcher agent. To add a dispatcher agent: - -- Add the package in as dependency in the dispatcher's [package.json](./package.json) -- Add a declaration of the module under `agents` in the dispatcher's [config.json](./data/config.json) - -``` - "agents": { - "": { - "type": "module", - "name": "", - } - } -``` - -### Inline dispatcher agent - -For internal use only, but an agent can be inlined in the dispatcher. This should only be used for agents that strongly ties to the inner working of the dispatcher (e.g. system configuration, etc.) +By default dispatcher only comes with `system` and `dispatcher` agents, providing minimal base functionality. Additional agents are provided using [AppAgentProvider](./src/agentProvider/agentProvider.ts)) when the dispatcher is created by the host. The host of the dispatcher (like [shell](../shell) and [CLI](../cli)) is configured with the default provider with subset of agents implemented in this repo, and a extensible provider that allow additional agent to be dynamically install/registered. (See [default-agent-provider](../defaultAgentProvider/) package). ## Trademarks