Building a Chatbot with Agentica

typia.llm.application<Class>() gives you the tools an LLM can call. Agentica builds the agent loop around those tools — the orchestration layer that decides which function to call, when, and how to recover from mistakes.

If typia.llm.application is “describe my service to an LLM,” Agentica is “actually run a conversation in which an LLM uses that service.”

First example

src/index.ts


import { Agentica } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";
 
import { BbsArticleService } from "./BbsArticleService";
 
const agent = new Agentica({
  service: {
    api: new OpenAI({ apiKey: "*****" }),
    model: "openai/gpt-4.1-mini",
  },
  controllers: [
    typia.llm.controller<BbsArticleService>(
      "bbs",
      new BbsArticleService(),
    ),
  ],
});
 
await agent.conversate("Hello, I want to create an article.");

That’s a complete chatbot: it understands intent, picks the right method on BbsArticleService, fills the arguments from the conversation, and asks follow-up questions when arguments are missing. No prompt engineering, no agent graph definition.

agentica-conceptual-diagram

@nestia/agent was renamed to @agentica/* to make room for additional packages built on the same idea.

Full source

undefined

src/index.ts


import { Agentica } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";
 
import { BbsArticleService } from "./BbsArticleService";
 
const agent = new Agentica({
  service: {
    api: new OpenAI({ apiKey: "*****" }),
    model: "openai/gpt-4.1-mini",
  },
  controllers: [
    typia.llm.controller<BbsArticleService>(
      "bbs",
      new BbsArticleService(),
    ),
  ],
});
await agent.conversate("Hello, I want to create an article.");

undefined

examples/src/llm/BbsArticleService.ts


import { tags } from "typia";
 
import { IBbsArticle } from "./IBbsArticle";
 
export declare class BbsArticleService {
  /**
   * Get all articles.
   *
   * List up every articles archived in the BBS DB.
   *
   * @returns List of every articles
   */
  public index(): IBbsArticle.IPage;
 
  /**
   * Create a new article.
   *
   * Writes a new article and archives it into the DB.
   *
   * @param props Properties of create function
   * @returns Newly created article
   */
  public create(props: {
    /** Information of the article to create */
    input: IBbsArticle.ICreate;
  }): IBbsArticle;
 
  /**
   * Update an article.
   *
   * Updates an article with new content.
   *
   * @param props Properties of update function
   * @param input New content to update
   */
  public update(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
 
    /** New content to update. */
    input: IBbsArticle.IUpdate;
  }): void;
 
  /**
   * Erase an article.
   *
   * Erases an article from the DB.
   *
   * @param props Properties of erase function
   */
  public erase(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
  }): void;
}

undefined

examples/src/llm/IBbsArticle.ts


import { tags } from "typia";
 
/**
 * Article entity.
 *
 * `IBbsArticle` is an entity representing an article in the BBS (Bulletin Board
 * System).
 */
export interface IBbsArticle extends IBbsArticle.ICreate {
  /** Primary Key. */
  id: string & tags.Format<"uuid">;
 
  /** Creation time of the article. */
  created_at: string & tags.Format<"date-time">;
 
  /** Last updated time of the article. */
  updated_at: string & tags.Format<"date-time">;
}
export namespace IBbsArticle {
  /** Information of the article to create. */
  export interface ICreate {
    /**
     * Title of the article.
     *
     * Representative title of the article.
     */
    title: string;
 
    /**
     * Content body.
     *
     * Content body of the article written in the markdown format.
     */
    body: string;
 
    /**
     * Thumbnail image URI.
     *
     * Thumbnail image URI which can represent the article.
     *
     * If configured as `null`, it means that no thumbnail image in the article.
     */
    thumbnail:
      | null
      | (string & tags.Format<"uri"> & tags.ContentMediaType<"image/*">);
  }
 
  /**
   * Information of the article to update.
   *
   * Only the filled properties will be updated.
   */
  export type IUpdate = Partial<ICreate>;
 
  /** Page of articles. */
  export interface IPage {
    /** List of articles. */
    articles: IBbsArticle[];
  }
}

Live demo: nestia.io/chat/bbs

From an OpenAPI document

You don’t have to start from TypeScript code. Agentica accepts an OpenAPI document directly — every endpoint becomes a tool the LLM can call.

src/main.ts


import { Agentica, assertHttpController } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";
 
import { MobileFileSystem } from "./services/MobileFileSystem";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "openai/gpt-4.1-mini",
  },
  controllers: [
    // Class-based functions
    typia.llm.controller<MobileFileSystem>("filesystem", new MobileFileSystem()),
 
    // Swagger / OpenAPI document → functions
    assertHttpController({
      name: "shopping",
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then((r) => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer ********" },
      },
    }),
  ],
});
 
await agent.conversate("I wanna buy MacBook Pro");

Live demo: nestia.io/chat/shopping
Backend source: github.com/samchon/shopping-backend
Swagger UI: open in @nestia/editor

How the loop works

Three sub-agents share the work:

Selector — reads the latest user message, decides which of the registered functions are candidates this turn. If none apply, it falls back to plain conversational replies.
Caller — given the candidate functions, tries to call them. If the conversation hasn’t given it enough information for the parameters, it asks the user a follow-up.
Describer — once the caller has produced results, turns them into a human-readable reply.

That separation is what keeps Agentica simple: each sub-agent does one thing and you don’t have to draw a state graph to keep it on track.

Validation feedback

LLM function calling is not perfect. Models make type mistakes — for example, they fill an Array<string> field with just a string. The fix is to give the model the structured error and ask it to retry.

Agentica relies on the same harness as typia.llm.application:


import { FunctionCall } from "pseudo";
import { ILlmFunction, IValidation } from "typia";
 
export const correctFunctionCall = (p: {
  call: FunctionCall;
  functions: Array<ILlmFunction<"chatgpt">>;
  retry: (reason: string, errors?: IValidation.IError[]) => Promise<unknown>;
}): Promise<unknown> => {
  const func = p.functions.find((f) => f.name === p.call.name);
  if (func === undefined) {
    return p.retry("Unable to find the matched function name. Try it again.");
  }
 
  const result: IValidation<unknown> = func.validate(p.call.arguments);
  if (!result.success) {
    // 1st trial: ~50% pass (gpt-4o-mini on shopping mall demo)
    // 2nd trial with validation feedback: ~99%
    // 3rd trial with validation feedback again: never failed in my testing
    return p.retry(
      "Type errors are detected. Correct it through validation errors.",
      result.errors,
    );
  }
  return result.data;
};

The numbers in the comments come from running the shopping chatbot demo above. The pattern works for the same reason it works in application and at AutoBe — typia’s validator gives the LLM enough detail (path, expected type, actual value) to fix its own mistakes.

Some LLM providers don’t even honor all the JSON Schema constraint keywords. The validation feedback channel works around that too: the model doesn’t have to understand "format": "uuid" — it just sees expected: "string & Format<\"uuid\">" in the error and tries again. The keywords most commonly ignored by providers, grouped by base type:

string — minLength, maxLength, pattern, format, contentMediaType
number — minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf
array — minItems, maxItems, uniqueItems, items

typia checks every one of these at runtime and surfaces failures into the feedback channel — so whether or not the provider taught the model to honor the schema keyword in the first place, the model gets a chance to fix the value on the next turn.

Components	`typia`	`TypeBox`	`ajv`	`io-ts`	`zod`	`C.V.`
Easy to use	✅	❌	❌	❌	❌	❌
Object (simple)	✔	✔	✔	✔	✔	✔
Object (hierarchical)	✔	✔	✔	✔	✔	✔
Object (recursive)	✔	❌	✔	✔	✔	✔
Object (union, implicit)	✅	❌	❌	❌	❌	❌
Object (union, explicit)	✔	✔	✔	✔	✔	❌
Object (additional tags)	✔	✔	✔	✔	✔	✔
Object (template literal types)	✔	✔	✔	❌	❌	❌
Object (dynamic properties)	✔	✔	✔	❌	❌	❌
Array (rest tuple)	✅	❌	❌	❌	❌	❌
Array (hierarchical)	✔	✔	✔	✔	✔	✔
Array (recursive)	✔	✔	✔	✔	✔	❌
Array (recursive, union)	✔	✔	❌	✔	✔	❌
Array (R+U, implicit)	✅	❌	❌	❌	❌	❌
Array (repeated)	✅	❌	❌	❌	❌	❌
Array (repeated, union)	✅	❌	❌	❌	❌	❌
Ultimate Union Type	✅	❌	❌	❌	❌	❌

C.V. means class-validator

OpenAPI pipeline

Agentica accepts Swagger 2.0 / OpenAPI 3.0 / 3.1. The conversion goes through an intermediate “emended” 3.1 representation that strips out the ambiguity and duplication of the public OpenAPI specs, then to a migration schema, and finally to whichever LLM provider’s function-calling format you target.

Why the intermediate step? Without it, you’d need n×m converters (every OpenAPI version × every LLM provider). With it, you need n+m.

Where to go next

The class-based tool API → typia.llm.application
The OpenAPI-based tool API → HttpLlm
Validation feedback mechanics → LlmJson
Documentation tips for better LLM behavior → Documentation Strategy
Agentica itself → github.com/wrtnlabs/agentica