Agentica Guide Documents

Setup

npm

Terminal


npm install @agentica/rpc tgrid
npm install @agentica/core @samchon/openapi

pnpm

Terminal


pnpm install @agentica/core @agentica/rpc tgrid
pnpm install @agentica/core @samchon/openapi

yarn

Terminal


yarn add @agentica/core @agentica/rpc tgrid
yarn add @agentica/core @samchon/openapi

You can start WebSocket client Agentic AI application by installing @agentica/rpc and tgrid packages. tgrid is a TypeScript based RPC (Remote Procedure Call) framework supporting WebSocket protocol, and @agentica/rpc is an wrapper module of @agentica/core following the WebSocket RPC.

Also, if you want to develop advanced features not only handling text contents but also manging LLM function calling schemas like #Arguments Hooking case, you need to setup @agentica/core and @samchon/openapi packages too. @agentica/core contains detailed event types, and @samchon/openapi provides LLM function calling schemas.

Development

Main Program

client/src/main.ts


import { IAgenticaRpcListener, IAgenticaRpcService } from "@agentica/rpc";
import { Driver, WebSocketConnector } from "tgrid";
 
// Create WebSocketConnector with type specifications
const connector: WebSocketConnector<
  null,
  IAgenticaRpcListener,
  IAgenticaRpcService
> = new WebSocketConnector(null, {
  // and configuring IAgenticaRpcListener instance
  // server will call these functions remotely 
  // (Remote Procedure Call)
  text: async (evt) => {
    console.log(evt.role, evt.text);
  },
  select: async (evt) => {
    console.log("selector", evt.selection);
  },
  execute: async (evt) => {
    console.log("execute", evt.operation, evt.arguments, evt.value);
  },
  describe: async (evt) => {
    console.log("describer", evt.text);
  },
});
 
// Connect to the server
await connector.connect("ws://localhost:3001");
 
// Call the server's functions remotely (Remote Procedure Call)
const driver: Driver<IAgenticaRpcService> = connector.getDriver();
await driver.conversate("Hello, what you can do?");
 
// Disconnect after your job
await connector.close();

undefined

@agentica/rpc/IAgenticaRpcService


import type { AgenticaUserMessageContent, IAgenticaController } from "@agentica/core";
 
/**
 * RPC interface of AI agent service.
 *
 * `IAgenticaRpcService` is an interface defining an AI agent service
 * provided from the server to client through the RPC (Remote Procedure Call)
 * paradigm in the websocket protocol.
 *
 * The client will call the {@link conversate} function remotely, and the
 * server responses to the client by calling the client's
 * {@link IAgenticaRpcListener} functions remotely too.
 *
 * @author Samchon
 */
export interface IAgenticaRpcService {
  /**
   * Conversate with the AI agent.
   *
   * User talks to the AI agent with the content.
   *
   * When AI agent responds some actions like conversating or executing
   * LLM (Large Language Model) function calling, the functions defined in the
   * {@link IAgenticaRpcListener} would be called through the RPC
   * (Remote Procedure Call) paradigm.
   *
   * @param content The content to talk
   * @returns Returned when the conversation process is completely done
   */
  conversate: (
    content:
      | string
      | AgenticaUserMessageContent
      | Array<AgenticaUserMessageContent>,
  ) => Promise<void>;
 
  /**
   * Get controllers.
   *
   * Get controllers, collection of functions that would be
   * called by the AI chatbot.
   */
  getControllers: () => Promise<IAgenticaController[]>;
}

undefined

@agentica/rpc/IAgenticaRpcListener


import type { IAgenticaEventJson } from "@agentica/core";
 
/**
 * RPC interface of AI agent listener.
 *
 * `IAgenticaRpcListener` is an interface defining an AI agent listener
 * provided from the client to server through the RPC (Remote Procedure Call)
 * paradigm in the websocket protocol.
 *
 * It has defined the event listener functions of {@link AgenticaEvent}
 * types. If you skip some event typed functions' implementations,
 * the skipped event would be ignored.
 *
 * Also, the event like listener functions of `IAgenticaRpcListener` type
 * are remotely called when a client calls the
 * {@link IAgenticaRpcService.conversate} function remotely, so that the
 * server responses to the client by the event listener functions.
 *
 * You can connect to the WebSocket server of the AI agent like below:
 *
 * ```typescript
 * import { IAgenticaRpcListener, IAgenticaRpcService } from "@agentica/core";
 * import { Driver, WebSocketConnector } from "tgrid";
 *
 * const connector: WebSocketConnector<
 *   null,
 *   IAgenticaRpcListener,
 *   IAgenticaRpcService
 * > = new WebSocketConnector(null, {
 *   text: async (evt) => {
 *     console.log(evt.role, evt.text);
 *   },
 *   describe: async (evt) => {
 *     console.log("describer", evt.text);
 *   },
 * });
 * await connector.connect("ws://localhost:3001");
 *
 * const driver: Driver<IAgenticaRpcService> = connector.getDriver();
 * await driver.conversate("Hello, what you can do?");
 * ```
 *
 * @author Samchon
 */
export interface IAgenticaRpcListener {
  /**
   * Describe the function executions' results.
   *
   * Inform description message of the function execution's results from
   * the AI agent server to client.
   *
   * @param evt Event of a description of function execution results
   */
  describe: (evt: IAgenticaEventJson.IDescribe) => Promise<void>;
 
  /**
   * Assistant conversation message.
   *
   * @param evt Event of assistant conversation
   */
  assistantMessage: (evt: IAgenticaEventJson.IAssistantMessage) => Promise<void>;
 
  /**
   * User conversation message.
   *
   * @param evt Event of user conversation
   */
  userMessage?: (evt: IAgenticaEventJson.IUserMessage) => Promise<void>;
 
  /**
   * Initialize the AI agent.
   *
   * Informs an initialization of controller functions from
   * the AI agent server to client.
   *
   * @param evt Event of initialization
   */
  initialize?: (evt: IAgenticaEventJson.IInitialize) => Promise<void>;
 
  /**
   * Select a function to call.
   *
   * Informs a selected function to call from the AI agent server to client.
   *
   * @param evt Event of selecting a function to call
   */
  select?: (evt: IAgenticaEventJson.ISelect) => Promise<void>;
 
  /**
   * Cancel a function to call.
   *
   * Informs a canceling function to call from the AI agent server to client.
   *
   * @param evt Event of canceling a function to call
   */
  cancel?: (evt: IAgenticaEventJson.ICancel) => Promise<void>;
 
  /**
   * Call a function.
   *
   * Informs a function calling from the AI agent server to client.
   *
   * This event comes before the function execution, so that if you return
   * a different value from the original {@link IAgenticaEventJson.ICall.arguments},
   * you can modify the arguments of the function calling.
   *
   * Otherwise you do not return anything (`undefined`) or `null` value, the
   * arguments of the function calling would not be modified. Also, if you are
   * not interested in the function calling event, you can skit its
   * implementation.
   *
   * @param evt Event of a function calling
   * @return New arguments if you want to modify, otherwise null or undefined
   */
  call?: (evt: IAgenticaEventJson.ICall) => Promise<object | null | void | undefined>;
 
  /**
   * Executition of a function.
   *
   * Informs a function execution from the AI agent server to client.
   *
   * @param evt Event of a function execution
   */
  execute?: (evt: IAgenticaEventJson.IExecute) => Promise<void>;
}

You can develop WebSocket client application like above.

At first, create an WebSocketConnector instance with IAgenticaRpcListener and IAgenticaRpcService type specifications, and constructing the IAgenticaRpcListener typed instance to provide event handlers. The IAgenticaRpcListener typed would be provided to the WebSocket server, so that the server will call the IAgenticaRpcListener functions remotely (Remote Procedure Call).

And then connect to the server with WebSocketConnector.connect() method specifying the server’s WebSocket address. If server accepts the connection, you can go to the next step. Otherwise server rejects your connection, an exception would be thrown.

After the connection, you can start conversation by calling the server’s functions remotely (Remote Procedure Call) to the Driver<IAgenticaRpcService> typed instance obtained from the WebSocketConnector.getDriver() method. Whenever you call some functions of the Driver<IAgenticaRpcService> instance, the server will call the corresponding functions of the IAgenticaRpcListener instance.

Note that, WebSocket protocol is different with HTTP protocol. The connection would be kept until you call the WebSocketConnector.close() method manually. So, if your business has been completed, please don’t forget to closing the connection.

Arguments Hooking

Client Application

client/src/main.ts


import { IAgenticaRpcListener, IAgenticaRpcService } from "@agentica/rpc";
import { ILlamaSchema, ILlmFunction } from "@samchon/openapi";
import { Driver, WebSocketConnector } from "tgrid";
 
const fillArguments = async (
  param: ILlamaSchema.IParameters
): Promise<Record<string, any>> => {
  ...
};
 
const connector: WebSocketConnector<
  null,
  IAgenticaRpcListener,
  IAgenticaRpcService
> = new WebSocketConnector(null, {
  text: async (evt) => {
    console.log(evt.role, evt.text);
  },
  describe: async (evt) => {
    console.log("describer", evt.text);
  },
  call: async (event) => {
    const func: ILlmFunction | undefined = controllers
      .find((c) => c.name === event.operation.controller)
      ?.application.functions.find(
        (f) => f.name === event.operation.function,
      );
    if (!func?.separated?.human) return null;
    return fillArguments(func.separated.human);
  },
});
await connector.connect("ws://localhost:3001");
 
const driver: Driver<IAgenticaRpcService> = connector.getDriver();
const controllers = await driver.getControllers();
await driver.conversate("I wanna create an article with file uploading.");
 
await connector.close();

Server Application

server/src/main.ts


import { Agentica } from "@agentica/core";
import {
  AgenticaRpcService,
  IAgenticaRpcListener,
  IAgenticaRpcService,
} from "@agentica/rpc";
import { LlamaTypeChecker } from "@samchon/openapi";
import OpenAI from "openai";
import { WebSocketServer } from "tgrid";
import typia from "typia";
 
const server: WebSocketServer<
  null,
  IAgenticaRpcService,
  IAgenticaRpcListener
> = new WebSocketServer();
await server.open(3_001, async (acceptor) => {
  const agent: Agentica = new Agentica({
    vendor: {
      api: new OpenAI({
        apiKey: "********",
        baseURL: "http://localhost:3000/llama",
      }),
      model: "llama-3.3-70b",
    },
    controllers: [
      {
        name: "bbs",
        protocol: "class",
        application: typia.llm.application<BbsArticleService>({
          separate: (schema) =>
            LlamaTypeChecker.isString(schema) &&
            schema.format === "uri" &&
            schema.contentMediaType !== undefined,
        }),
        execute: new BbsArticleService(),
      },
    ],
  });
  const service: AgenticaRpcService = new AgenticaRpcService({
    agent,
    listener: acceptor.getDriver(),
  });
  await acceptor.accept(service);
});

undefined

@agentica/rpc/IAgenticaRpcListener


import type { IAgenticaEventJson } from "@agentica/core";
 
/**
 * RPC interface of AI agent listener.
 *
 * `IAgenticaRpcListener` is an interface defining an AI agent listener
 * provided from the client to server through the RPC (Remote Procedure Call)
 * paradigm in the websocket protocol.
 *
 * It has defined the event listener functions of {@link AgenticaEvent}
 * types. If you skip some event typed functions' implementations,
 * the skipped event would be ignored.
 *
 * Also, the event like listener functions of `IAgenticaRpcListener` type
 * are remotely called when a client calls the
 * {@link IAgenticaRpcService.conversate} function remotely, so that the
 * server responses to the client by the event listener functions.
 *
 * You can connect to the WebSocket server of the AI agent like below:
 *
 * ```typescript
 * import { IAgenticaRpcListener, IAgenticaRpcService } from "@agentica/core";
 * import { Driver, WebSocketConnector } from "tgrid";
 *
 * const connector: WebSocketConnector<
 *   null,
 *   IAgenticaRpcListener,
 *   IAgenticaRpcService
 * > = new WebSocketConnector(null, {
 *   text: async (evt) => {
 *     console.log(evt.role, evt.text);
 *   },
 *   describe: async (evt) => {
 *     console.log("describer", evt.text);
 *   },
 * });
 * await connector.connect("ws://localhost:3001");
 *
 * const driver: Driver<IAgenticaRpcService> = connector.getDriver();
 * await driver.conversate("Hello, what you can do?");
 * ```
 *
 * @author Samchon
 */
export interface IAgenticaRpcListener {
  /**
   * Describe the function executions' results.
   *
   * Inform description message of the function execution's results from
   * the AI agent server to client.
   *
   * @param evt Event of a description of function execution results
   */
  describe: (evt: IAgenticaEventJson.IDescribe) => Promise<void>;
 
  /**
   * Assistant conversation message.
   *
   * @param evt Event of assistant conversation
   */
  assistantMessage: (evt: IAgenticaEventJson.IAssistantMessage) => Promise<void>;
 
  /**
   * User conversation message.
   *
   * @param evt Event of user conversation
   */
  userMessage?: (evt: IAgenticaEventJson.IUserMessage) => Promise<void>;
 
  /**
   * Initialize the AI agent.
   *
   * Informs an initialization of controller functions from
   * the AI agent server to client.
   *
   * @param evt Event of initialization
   */
  initialize?: (evt: IAgenticaEventJson.IInitialize) => Promise<void>;
 
  /**
   * Select a function to call.
   *
   * Informs a selected function to call from the AI agent server to client.
   *
   * @param evt Event of selecting a function to call
   */
  select?: (evt: IAgenticaEventJson.ISelect) => Promise<void>;
 
  /**
   * Cancel a function to call.
   *
   * Informs a canceling function to call from the AI agent server to client.
   *
   * @param evt Event of canceling a function to call
   */
  cancel?: (evt: IAgenticaEventJson.ICancel) => Promise<void>;
 
  /**
   * Call a function.
   *
   * Informs a function calling from the AI agent server to client.
   *
   * This event comes before the function execution, so that if you return
   * a different value from the original {@link IAgenticaEventJson.ICall.arguments},
   * you can modify the arguments of the function calling.
   *
   * Otherwise you do not return anything (`undefined`) or `null` value, the
   * arguments of the function calling would not be modified. Also, if you are
   * not interested in the function calling event, you can skit its
   * implementation.
   *
   * @param evt Event of a function calling
   * @return New arguments if you want to modify, otherwise null or undefined
   */
  call?: (evt: IAgenticaEventJson.ICall) => Promise<object | null | void | undefined>;
 
  /**
   * Executition of a function.
   *
   * Informs a function execution from the AI agent server to client.
   *
   * @param evt Event of a function execution
   */
  execute?: (evt: IAgenticaEventJson.IExecute) => Promise<void>;
}

Looking at the IAgenticaRpcListener interface provided from client to server for event listening, you can find that only text and describe functions are mandatory, and the other functions are all optional. Among the optional functions, call function is a special one.

When providing IAgenticaRpcListener instance to the server, if you construct the call function to return some value exception null and undefined, it would be utilized instead of original arguments of the function calling. And such arguments modification is required when the server has separated the function parameters by a specific rule.

For example, if the WebSocket server has defined a rule that file arguments must be composed by client side by the file uploading window, you can construct the call function to return the new arguments combined with the file uploaded assets.

Above is the example utilizing the call function for such case.