TypeAgent Shell and CLI are built using TypeAgent Dispatcher. It has a configurable and extensible architecture that allow custom agents to plug into the system. The TypeAgent repo includes several example agents. Application agents can be built outside the TypeAgent repo by using the TypeAgent SDK. These agents can be packaged as npm packages and then surfaced in the Shell or CLI.

This document describes how to build a custom application agent as an independent local NPM package outside of the repo that works with a locally built TypeAgent Shell or CLI. The are two example agents in this repo you can reference: Echo Agent and Measure Agent.

Begin by exploring the following:

• TypeAgent SDK: Read about the architecture of the TypeAgent SDK.
• Example Agents:
  • Review agents under the agents directory. The List agent provides a good example and template for building an agent.
  • The Echo agent illustrates the basics of building your own custom application agents.

For the rest of the documentation, we will assume that the custom 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 with some modification (NOTE: The only difference is the @typeagent/agent-sdk dependency)

Follow the following steps to create the Echo agent packages manually. Start by create a directory echo outside of the TypeAgent repo. Then populate the directory with the following content:

package.json package.json :

The package.json contains references to handler and manifest files in the exports field.

{
  "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"
  }
}

Typescript build config file tsconfig.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
  }
}

Every application agent requires the following files to be present in the agent's source 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

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.

{
  "emojiChar": "🦜",
  "schema": {
    "description": "A basic echo agent.",
    "schemaFile": "./echoActionSchema.ts",
    "schemaType": "EchoAction"
  }
}

Agent Action Schema File : src/echoActionSchema.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

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<EchoActionContext> {
  return { echoCount: 0 };
}

async function executeEchoAction(
  action: TypeAgentAction<EchoAction>,
  context: ActionContext<EchoActionContext>
) {
  // 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");
  }
}

┣━ package.json
┣━ tsconfig.json
┗━ src
   ┣━ echoManifest.json
   ┣━ echoActionSchema.ts
   ┗━ echoActionHandler.ts

First make sure the TypeAgent's typescript code is built.

• Go to <repo>/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 <repo>/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

Start TypeAgent Shell or CLI

# you can run these commands from the `ts` folder
# in the TypeAgent root.

pnpm run cli interactive

or

pnpm run shell

In the Shell or CLI, install the echo agent and check the status by issuing the command:

@install echo <path to echo package>
@config agent

The Echo agent should be in the list and enabled.

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:

When to run the shell this is how interaction with the Echo agent will look like:

The Echo agent will be reloaded again after installation. It can be uninstalled using the command:

@uninstall echo

Start modifying the Echo agent and add new action schema and action handlers.