Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit f1b10ee

Browse files
curtismancurtisman
committedFeb 7, 2025··
update
1 parent 8341dfa commit f1b10ee

File tree

14 files changed

+265
-407
lines changed

14 files changed

+265
-407
lines changed
 

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ Microsoft TypeAgent Repo is a mono-repo, with components organized with the foll
8282
- [`python`](./python) Python code ([Readme](./python/README.md))
8383
- [`dotnet`](./dotnet) Dotnet (C#) code ([Readme](./dotnet/README.md))
8484

85+
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.
86+
8587
## Contributing
8688

8789
This project welcomes contributions and suggestions. Most contributions require you to

‎docs/tutorial/agent.md

+243
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# External Agents
2+
3+
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).
4+
5+
This document describes how you can build your own application agents.
6+
7+
## Prerequisites
8+
9+
Begin by exploring the following:
10+
11+
- **Agent-Sdk**: Read about the architecture of the [**agent-sdk**](../../ts/packages/agentSdk/README.md).
12+
- **Example Agents**:
13+
- 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.
14+
- The [Echo](../../ts/examples/agentExamples/echo/) agent illustrates the basics of building your own external application agents.
15+
16+
## Steps to build an `Echo` agent:
17+
18+
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.
19+
20+
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)
21+
22+
### Step 1: Create and author the `Echo` agent package
23+
24+
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:
25+
26+
**package.json** [package.json](../../ts/examples/agentExamples/echo/package.json) :
27+
28+
The `package.json` contains references to **handler** and **manifest** files in the `exports` field.
29+
30+
```json
31+
{
32+
"name": "echo",
33+
"version": "0.0.1",
34+
"description": "Echo example for TypeAgent",
35+
"license": "MIT",
36+
"author": "Microsoft",
37+
"type": "module",
38+
"exports": {
39+
"./agent/manifest": "./src/echoManifest.json",
40+
"./agent/handlers": "./dist/echoActionHandler.js"
41+
},
42+
"scripts": {
43+
"build": "npm run tsc",
44+
"clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log",
45+
"tsc": "tsc -b"
46+
},
47+
"keywords": [],
48+
"dependencies": {
49+
"@typeagent/agent-sdk": "0.0.1"
50+
},
51+
"devDependencies": {
52+
"rimraf": "^5.0.5",
53+
"typescript": "^5.4.2"
54+
}
55+
}
56+
```
57+
58+
Every application agent requires the following files to be present in the agent's [**source**](../../ts/examples/agentExamples/echo/src/) directory.
59+
60+
- **Agent Manifest File**: The manifest file is used to register the agent with the TypeAgent ecosystem.
61+
- **Action Schema File**: The action schema file is used to define the actions that the agent can perform.
62+
- **Agent Action Handler**: Your code that perform's the agent's actions.
63+
64+
**Agent Manifest File** : [`src/echoManifest.json`](../../ts/examples/agentExamples/echo/src/echoManifest.json)
65+
66+
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.
67+
68+
```json
69+
{
70+
"emojiChar": "🦜",
71+
"schema": {
72+
"description": "A basic echo agent.",
73+
"schemaFile": "./echoActionSchema.ts",
74+
"schemaType": "EchoAction"
75+
}
76+
}
77+
```
78+
79+
**Agent Action Schema File** : [`src/echoActionSchema.ts`](../../ts/examples/agentExamples/echo/src/echoActionSchema.ts)
80+
81+
```ts
82+
export type EchoAction = GenEchoAction;
83+
84+
// 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.
85+
// will contain the text to be echoed back to the user.
86+
export type GenEchoAction = {
87+
actionName: "echoGen";
88+
parameters: {
89+
text: string;
90+
};
91+
};
92+
```
93+
94+
**Agent action handler** : [`src/echoActionHandler.ts`](../../ts/examples/agentExamples/echo/src/echoActionHandler.ts)
95+
96+
```ts
97+
import { ActionContext, AppAgent, TypeAgentAction } from "@typeagent/agent-sdk";
98+
import {
99+
createActionResultFromTextDisplay,
100+
createActionResultFromError,
101+
} from "@typeagent/agent-sdk/helpers/action";
102+
import { EchoAction } from "./echoActionSchema.js";
103+
104+
export function instantiate(): AppAgent {
105+
return {
106+
initializeAgentContext: initializeEchoContext,
107+
executeAction: executeEchoAction,
108+
};
109+
}
110+
111+
type EchoActionContext = {
112+
echoCount: number;
113+
};
114+
115+
async function initializeEchoContext(): Promise<EchoActionContext> {
116+
return { echoCount: 0 };
117+
}
118+
119+
async function executeEchoAction(
120+
action: TypeAgentAction<EchoAction>,
121+
context: ActionContext<EchoActionContext>
122+
) {
123+
// The context created in initializeEchoContext is returned in the action context.
124+
const echoContext = context.sessionContext.agentContext;
125+
switch (action.actionName) {
126+
case "echoGen":
127+
const displayText = `>> Echo ${++echoContext.echoCount}: ${
128+
action.parameters.text
129+
}`;
130+
return createActionResultFromTextDisplay(displayText, displayText);
131+
132+
default:
133+
return createActionResultFromError("Unable to process the action");
134+
}
135+
}
136+
```
137+
138+
**Typescript build config file** [`tsconfig.json`](../../ts/examples/agentExamples/echo/tsconfig.json)
139+
140+
```json
141+
{
142+
"compilerOptions": {
143+
"composite": true,
144+
"target": "es2021",
145+
"lib": ["es2021"],
146+
"module": "node16",
147+
"declaration": true,
148+
"declarationMap": true,
149+
"esModuleInterop": true,
150+
"exactOptionalPropertyTypes": true,
151+
"forceConsistentCasingInFileNames": true,
152+
"incremental": true,
153+
"noEmitOnError": true,
154+
"noUnusedLocals": true,
155+
"skipLibCheck": true,
156+
"strict": true,
157+
"sourceMap": true,
158+
"rootDir": "./src",
159+
"outDir": "./dist"
160+
},
161+
"include": ["./src/**/*"],
162+
"ts-node": {
163+
"esm": true
164+
}
165+
}
166+
```
167+
168+
#### Folder structure for **Echo** agent:
169+
170+
![alt text](./imgs/image-files.png)
171+
172+
<a id="install_agent"></a>
173+
174+
#### Step 2: Build the Agent
175+
176+
First make sure the [TypeAgent's typescript code](../../ts) is built.
177+
178+
- Go to `<repo>/ts`
179+
- `pnpm i`
180+
- `pnpm run build`
181+
182+
Then create a link globally to the `@typeagent/agent-sdk` package for the `Echo` agent to consume.
183+
184+
- Go to `<repo>/ts/packages/agentSdk`
185+
- `npm link`
186+
187+
In the `Echo` package, run the following to link to `@typeagent/agent-sdk` package and build
188+
189+
- `npm link @typeagent/agent-sdk`
190+
- `npm install`
191+
- `npm run build`
192+
193+
### Step 3: Install `Echo` agent in TypeAgent cli or shell.
194+
195+
Start TypeAgent [Shell](../../ts/packages/shell) or [CLI](../../ts/packages/cli)
196+
197+
```bash
198+
# you can run these commands from the `ts` folder
199+
# in the TypeAgent root.
200+
201+
pnpm run cli interactive
202+
203+
or
204+
205+
pnpm run shell
206+
```
207+
208+
In the [Shell](../../ts/packages/shell) or [CLI](../../ts/packages/cli), install the echo agent and check the status by issuing the command:
209+
210+
```
211+
@install echo <path to echo package>
212+
@config agent
213+
```
214+
215+
The `Echo` agent should be in the list and enabled.
216+
217+
### Step 4: See the `Echo` agent in action
218+
219+
`Echo` agent is now ready. Test it out by issuing some request to see the `Echo` agent in action
220+
221+
When to run the cli this is how interaction with the `Echo` agent will look like:
222+
![alt text](./imgs/image-cli.png)
223+
224+
When to run the shell this is how interaction with the `Echo` agent will look like:
225+
![alt text](./imgs/image-shell.png)
226+
227+
The `Echo` agent will be reloaded again after installation. It can be uninstalled using the command:
228+
229+
```
230+
@uninstall echo
231+
```
232+
233+
## Next step
234+
235+
Start modifying the `Echo` agent and add new action schema and action handlers.
236+
237+
## Trademarks
238+
239+
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
240+
trademarks or logos is subject to and must follow
241+
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
242+
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
243+
Any use of third-party trademarks or logos are subject to those third-party's policies.

‎ts/packages/agentSdk/imgs/image-cli.png ‎docs/tutorial/imgs/image-cli.png

File renamed without changes.

‎ts/packages/agentSdk/imgs/image-files.png ‎docs/tutorial/imgs/image-files.png

File renamed without changes.

‎ts/packages/agentSdk/imgs/image-shell.png ‎docs/tutorial/imgs/image-shell.png

File renamed without changes.

‎ts/examples/agentExamples/echo/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Echo Agent
22

3-
The Echo Agent demonstrates how to use the [agent-sdk](../../../packages/agentSdk/ExternalAgents_README.md) to write agents as installable packages.
3+
The Echo Agent demonstrates how to use the [agent-sdk](../../../../docs/tutorial/agent.md) to write agents as installable packages.
44

55
## Trademarks
66

‎ts/examples/agentExamples/echo/package.json

+1-2
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,10 @@
1414
"type": "module",
1515
"exports": {
1616
"./agent/handlers": "./dist/echoActionHandler.js",
17-
"./agent/manifest": "./dist/echoManifest.json"
17+
"./agent/manifest": "./src/echoManifest.json"
1818
},
1919
"scripts": {
2020
"build": "npm run tsc",
21-
"postbuild": "copyfiles -u 1 \"src/**/*Schema*.ts\" \"src/**/*Manifest*.json\" dist",
2221
"clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log",
2322
"prettier": "prettier --check . --ignore-path ../../../.prettierignore",
2423
"prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",

‎ts/examples/agentExamples/echo/src/echoActionHandler.ts

+13-55
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,39 @@
1-
// Copyright (c) Microsoft Corporation.
2-
// Licensed under the MIT License.
3-
4-
import {
5-
ActionContext,
6-
AppAction,
7-
AppAgent,
8-
SessionContext,
9-
ActionResult,
10-
} from "@typeagent/agent-sdk";
1+
import { ActionContext, AppAgent, TypeAgentAction } from "@typeagent/agent-sdk";
112
import {
123
createActionResultFromTextDisplay,
134
createActionResultFromError,
145
} from "@typeagent/agent-sdk/helpers/action";
15-
16-
import { EchoAction } from "./echoActionsSchema.js";
6+
import { EchoAction } from "./echoActionSchema.js";
177

188
export function instantiate(): AppAgent {
199
return {
2010
initializeAgentContext: initializeEchoContext,
21-
updateAgentContext: updateEchoContext,
2211
executeAction: executeEchoAction,
2312
};
2413
}
2514

2615
type EchoActionContext = {
2716
echoCount: number;
28-
echoRequests: Set<string> | undefined;
2917
};
3018

31-
async function initializeEchoContext() {
32-
return {
33-
echoCount: 0,
34-
echoRequests: undefined,
35-
};
36-
}
37-
38-
async function updateEchoContext(
39-
enable: boolean,
40-
context: SessionContext<EchoActionContext>,
41-
): Promise<void> {
42-
if (enable) {
43-
context.agentContext.echoRequests = new Set<string>();
44-
context.agentContext.echoCount = 0;
45-
}
46-
context.agentContext.echoCount++;
19+
async function initializeEchoContext(): Promise<EchoActionContext> {
20+
return { echoCount: 0 };
4721
}
4822

4923
async function executeEchoAction(
50-
action: AppAction,
24+
action: TypeAgentAction<EchoAction>,
5125
context: ActionContext<EchoActionContext>,
5226
) {
53-
let result = await handleEchoAction(
54-
action as EchoAction,
55-
context.sessionContext.agentContext,
56-
);
57-
return result;
58-
}
59-
60-
async function handleEchoAction(
61-
action: EchoAction,
62-
echoContext: EchoActionContext,
63-
) {
64-
let result: ActionResult | undefined = undefined;
65-
let displayText: string | undefined = undefined;
27+
// The context created in initializeEchoContext is returned in the action context.
28+
const echoContext = context.sessionContext.agentContext;
6629
switch (action.actionName) {
6730
case "echoGen":
68-
displayText = `>> Echo: ${action.parameters.text}`;
69-
result = createActionResultFromTextDisplay(
70-
displayText,
71-
displayText,
72-
);
73-
break;
31+
const displayText = `>> Echo ${++echoContext.echoCount}: ${
32+
action.parameters.text
33+
}`;
34+
return createActionResultFromTextDisplay(displayText, displayText);
35+
7436
default:
75-
result = createActionResultFromError(
76-
"Unable to process the action",
77-
);
78-
break;
37+
return createActionResultFromError("Unable to process the action");
7938
}
80-
return result;
8139
}

‎ts/examples/agentExamples/echo/src/echoManifest.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"emojiChar": "🦜",
33
"schema": {
44
"description": "A basic echo agent.",
5-
"schemaFile": "echoActionsSchema.ts",
5+
"schemaFile": "./echoActionSchema.ts",
66
"schemaType": "EchoAction"
77
}
88
}

‎ts/examples/agentExamples/measure/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Work in progress.
66

77
## Installation
88

9-
- Follow the standard exteneral [Agent installation steps](../../../packages/agentSdk/ExternalAgents_README.md#install_agent)
9+
- Follow the standard external [Agent installation steps](../../../../docs/tutorial/agent.md#step-3-install-echo-agent-in-typeagent-cli-or-shell)
1010

1111
## Trademarks
1212

‎ts/packages/agentSdk/ExternalAgents_README.md

-324
This file was deleted.

‎ts/packages/agentSdk/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This package contains interface definitions and utilities for implementing a **D
44

55
- [List](../agents/list/) agent is a good example and initial template for building a dispatcher agent.
66
- The [Dispatcher README](../dispatcher/README.md) contains instructions on how to register a dispatcher agent with the TypeAgent Dispatcher.
7-
- You can also create agents as [installable packages](./ExternalAgents_README.md) called [**external application agents**](./ExternalAgents_README.md).
7+
- You can also create [agents as NPM packages](../../../docs/tutorial/agent.md) that can be installed/register to the [Shell](../shell) or [CLI](../cli)
88

99
## Agent SDK
1010

‎ts/packages/dispatcher/README.md

+2-22
Original file line numberDiff line numberDiff line change
@@ -163,29 +163,9 @@ Use the `@const <args>` command at the prompt to control the construction store.
163163

164164
## Adding Dispatcher Agent
165165

166-
Addition Dispatcher Agent can be create to extend the capabilities of the **single personal assistant**.
166+
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).
167167

168-
### NPM Module
169-
170-
Go to Agent SDK [README](../agentSdk/README.md) for details on how to create a dispatcher agent in a NPM modules.
171-
172-
Dispatcher currently only supports "static" loading of dispatcher agent. To add a dispatcher agent:
173-
174-
- Add the package in as dependency in the dispatcher's [package.json](./package.json)
175-
- Add a declaration of the module under `agents` in the dispatcher's [config.json](./data/config.json)
176-
177-
```
178-
"agents": {
179-
"<agentName>": {
180-
"type": "module",
181-
"name": "<packageName>",
182-
}
183-
}
184-
```
185-
186-
### Inline dispatcher agent
187-
188-
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.)
168+
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).
189169

190170
## Trademarks
191171

0 commit comments

Comments
 (0)
Please sign in to comment.