Agentica: turning TypeScript classes, OpenAPI documents and MCP servers into LLM function calls

The problem Agentica targets: hand-written tool schemas

Every function-calling setup needs the same three things: a list of callable functions, a JSON schema describing each argument, and a loop that feeds the model's chosen call back into your code. The schema is the expensive part. It drifts from the implementation the moment someone renames a field, and it has to be rewritten per provider because OpenAI, Gemini, Claude, DeepSeek and Llama do not agree on which JSON Schema draft they accept. The README's flowchart makes this the central claim: JSON Schema v4 through v7, 2019-03 and 2020-12 are all upgraded or emended into what it calls "OpenAPI v3.1 (emended)", and that single representation is what the framework hands to the model.

The intended user is a TypeScript developer who already has working code. The README states the pitch plainly: "Are you a TypeScript developer? Then you're already an AI developer." That is a positioning statement, not a capability, but it identifies the audience correctly. If your functions live in a class, in a NestJS controller, or behind a Swagger document, Agentica's job is to make those callable without a separate schema-authoring step. If your functions do not exist yet, the framework gives you nothing to wrap.

Three controller types and how they reach the model

The architecture is a controller list attached to a vendor configuration. Each controller is one source of functions, and the agent merges them into a single tool set for the model. The README names exactly three protocols: TypeScript Class, Swagger/OpenAPI Document, and MCP (Model Context Protocol) Server.

The TypeScript class path goes through typia, the schema generator from the same ecosystem. typia.llm.controller<MobileFileSystem>("filesystem", new MobileFileSystem()) takes the class type and produces the function definitions the model sees. This is the part that justifies the repository description's phrase "enhanced by compiler skills": the schema comes from the type system, so a renamed property is a compile error rather than a silent mismatch between the prompt and the implementation.

The OpenAPI path goes through assertHttpController, which takes a name, a model hint, a parsed document, and a connection object with host and headers. The README's example fetches a live swagger.json and passes a bearer token in the headers. The name matters more than it looks: the model sees it as the namespace for those operations, so two controllers named the same thing would collide.

MCP is listed as a supported protocol but the README does not show a code sample for it, so the exact entry point is not something this article can state.

Installing Agentica and getting a first agent to answer

The documented install path is the setup wizard, run with npx. It asks for a package manager, a project type, and a set of embedded controllers chosen from a multi-select list. The README shows npm, pnpm and yarn as options, with the note that yarn berry is not supported.

$ npx agentica start <directory>

The wizard then prompts for Project Type and Embedded Controllers. The README lists NodeJS Agent Server, NestJS Agent Server, React Client Application and Standalone Application. Any option other than Standalone Application, according to the README, implements the WebSocket Protocol for client-server communication. That is a real constraint on the choice: picking NestJS Agent Server means you are adopting a socket protocol between client and agent, not just a library.

The embedded controller list includes Google Calendar, Google News, Github, Reddit and Slack, with the README's sample showing Github selected.

If you skip the wizard, the core package is used directly. The README's opening example constructs an Agentica instance with an OpenAI vendor at gpt-4o-mini and two controllers, then calls conversate with a natural-language request.

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: "gpt-4o-mini",
  },
  controllers: [
    typia.llm.controller<MobileFileSystem>(
      "filesystem",
      new MobileFileSystem(),
    ),
    assertHttpController({
      name: "shopping",
      model: "chatgpt",
      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");

What you should see is a conversation turn in which the model selects one of the registered functions and the framework executes it. The README does not document what conversate returns or how to read intermediate tool calls from it, so plan to inspect the return value yourself rather than trusting a documented shape.

There is also a hosted playground at wrtnlabs.io/agentica/playground with three demos: one for a TypeScript class, one for an OpenAPI document upload, and one for an enterprise e-commerce agent. Running the playground first is cheaper than scaffolding a project to find out whether your schema survives the conversion.

Where Agentica breaks down

The OpenAPI controller is the weakest link, and the README's own example shows why. assertHttpController takes a document and a connection, which means authentication and host are configured at the controller level, not per operation. A document whose operations span multiple hosts, or that mixes authenticated and public endpoints, does not map cleanly onto one controller. You would need two controllers, and the model then has to pick between two namespaces that may describe the same resource.

The name is also a prompt surface. The README gives no guidance on naming controllers or on how many functions a single controller should expose. Every function in every controller is a candidate in the model's tool list, so a large OpenAPI document becomes a large tool list, and the framework does not document a filtering or selection step. This is a design trade-off rather than a bug, but it is the one most likely to bite on a real enterprise API.

The version line is the second concern. Releases moved from v0.44.1 on 2026-03-15 to v0.45.0 on 2026-04-27 to v0.45.1 on 2026-05-20. The last push to the repository was on 2026-05-25. That is a fast cadence on a pre-1.0 package, and nothing in the README promises API stability. If you are pinning a dependency for a long-lived service, budget for upgrade work between minor versions.

Finally, the README does not document rollback, retries, or what happens when a model emits a function call whose arguments fail the generated schema. The typia path makes invalid arguments less likely, since the schema comes from the type, but the failure path is not described.

Agentica compared with the Vercel AI SDK approach

The closest comparison in the TypeScript ecosystem is the Vercel AI SDK, which also targets function calling from TypeScript. The difference is where the schema comes from. The AI SDK expects you to describe tools explicitly, typically with a schema library such as Zod, and to write the execute function for each one. You get a uniform interface and explicit control over every tool definition.

Agentica inverts that. You do not write tool definitions at all. typia reads the class type; assertHttpController reads the OpenAPI document. The framework's claim is that the schema is derived rather than declared, so the source of truth stays in your existing code or your existing API spec.

That is a genuine difference in approach, and it cuts both ways. Derivation removes a whole class of drift bugs, and it makes a large existing API surface usable without hand-porting each operation. It also removes your ability to shape individual tool descriptions, which is where prompt engineering for tool selection usually happens. If your model keeps picking the wrong function, the Vercel AI SDK gives you a description field to fix it; Agentica's README does not document an equivalent knob for the OpenAPI path.

A second difference is scope. The AI SDK is a general model interface with tool calling as one feature. Agentica is narrower: the README describes it as specialized in function calling, and the three controller protocols are the whole surface. Narrower means less to learn and less to configure, and also less to fall back on when function calling is not the problem you have.

Licence, maintenance and the cost of staying current

Agentica is MIT licensed, and the root package.json carries "license": "MIT" with author Wrtn Technologies. MIT is permissive: you can use it commercially, modify it, and redistribute it, provided the copyright notice and licence text are preserved. This is a description of the licence terms, not legal advice; if your organisation has specific obligations around attribution in distributed binaries, check those separately.

The repository is not archived, and the last push was on 2026-05-25. The root package.json is a private workspace root named @agentica/station at version 0.45.1, with the publishable code under packages/ and a pnpm workspace declared in pnpm-workspace.yaml. The engines field requires pnpm >= 10, and a preinstall script runs npx only-allow pnpm, so npm and yarn will refuse to install the monorepo itself. That constraint applies to contributing to the repository, not to consuming @agentica/core from npm.

Upgrade cost is the real maintenance question. The project uses bumpp for releases and a deploy/sync_readme.js script that runs before version bumps, which suggests the README is kept in sync with releases rather than drifting. Nothing in the README describes a deprecation policy or a compatibility guarantee across 0.x versions. Treat the version you pin as the version you will need to re-test.

Editorial conclusion

Adopt Agentica if your tools already exist as a TypeScript class, an OpenAPI document or an MCP server and you want the model to call them without writing JSON schemas by hand; the typia.llm.controller path is the shortest route from working code to a working agent. Do not adopt it if you need a hosted runtime, a Python stack, or a stable API surface, because the version line moved from 0.44.1 to 0.45.1 in roughly two months. Verify first that the model you intend to use accepts the JSON Schema dialect Agentica emits for your controller, and that your OpenAPI document survives assertHttpController without a manual edit.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wrtnlabs/agentica on GitHub