# Type-Safe Agents: Leveraging apcore-js in TypeScript

> Source: <https://dev.to/tercelyi/type-safe-agents-leveraging-apcore-js-in-typescript-2447>
> Published: 2026-06-06 12:32:25+00:00

While Python dominates the AI research space, TypeScript is the engine of the modern full-stack web. From high-performance Node.js backends to complex React frontends, TypeScript provides the structure and safety that large-scale engineering teams demand.

When we built the **apcore-js** SDK, we didn't just want to "port" the Python logic. We wanted to create a first-class, type-safe experience that leverages the unique strengths of the JavaScript ecosystem.

In this twentieth article of our series, we explore how to build AI-Perceivable modules in TypeScript using apcore and **TypeBox**.

A core tenet of the apcore protocol is that a module’s behavior should be identical regardless of the implementation language. A module named `executor.user.get`

must accept the same JSON input and produce the same output in both Python and TypeScript.

apcore-js achieves this by using **TypeBox** as its core schema engine. TypeBox allows us to define JSON Schemas that double as TypeScript types, giving us compile-time safety and runtime validation in a single definition.

In apcore-js, you define your module's contract using TypeBox's `Static`

and `Type`

primitives:

``` js
import { Type, Static } from '@sinclair/typebox';

export const InputSchema = Type.Object({
  userId: Type.String({ description: "The unique UUID of the user." }),
  includePrivate: Type.Boolean({ default: false, description: "Whether to include sensitive fields." })
});

export type Input = Static<typeof InputSchema>;
```

By adding the `description`

field directly into the TypeBox definition, you are creating the "Cognitive Interface" for the AI while simultaneously providing type hints for your IDE.

apcore-js supports both class-based and functional module definitions. The class-based approach is idiomatic for TypeScript developers:

``` js
import { ClassModule, ModuleAnnotations, Context } from '@apcore/core';

export class GetUserModule extends ClassModule {
  id = "executor.user.get";
  description = "Retrieve detailed user profiles.";
  inputSchema = InputSchema;

  annotations = new ModuleAnnotations({
    readonly: true,
    destructive: false
  });

  async execute(inputs: Input, context: Context): Promise<object> {
    // inputs is fully typed!
    const user = await db.users.findUnique({ where: { id: inputs.userId } });
    return { status: "success", user };
  }
}
```

Managing a registry in Node.js is just as easy as in Python. apcore-js includes a `FileSystemLoader`

that scans your directory structure.

One of the cleverest parts of the SDK is its **Automatic ID Normalization**. In TypeScript, it’s common to name your files using `camelCase`

(e.g., `sendEmail.ts`

). apcore-js automatically maps this to the canonical `snake_case`

(e.g., `send_email`

) required by the protocol. This ensures that an AI Agent sees a consistent naming convention even in a polyglot environment.

AI Agents in the Node ecosystem often live inside microservices. apcore-js is built for distributed environments. It automatically propagates the `trace_id`

through `Promise`

chains and can integrate with existing tracing headers (like Zipkin or Jaeger) via custom middleware.

``` js
const result = await executor.callAsync("executor.user.get", { userId: "123" }, context);
```

By combining the rigor of the apcore protocol with the safety of TypeScript and TypeBox, **apcore-js** allows you to build AI-Perceivable systems that are as reliable as they are intelligent. You get the best of both worlds: high-velocity development and rock-solid architectural constraints.

**Now that we’ve mastered the two most popular languages for AI, it’s time to look at the performance tier. In our next article, we dive into Zero-Cost Abstraction: Building High-Performance AI Modules in Rust.**

*This is Article #20 of the **Building the AI-Perceivable World** series. Type safety is the first step to AI safety.*

**GitHub**: [aiperceivable/apcore-typescript](https://github.com/aiperceivable/apcore-typescript)