{"slug": "type-safe-agents-leveraging-apcore-js-in-typescript", "title": "Type-Safe Agents: Leveraging apcore-js in TypeScript", "summary": "The apcore-js SDK now enables developers to build type-safe, AI-perceivable modules in TypeScript using TypeBox for compile-time safety and runtime validation. The SDK supports both class-based and functional module definitions, automatic ID normalization between camelCase and snake_case, and distributed tracing propagation for microservice environments. By combining the apcore protocol with TypeScript's type system, the project ensures that AI agents receive consistent JSON inputs and outputs across both Python and TypeScript implementations.", "body_md": "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.\n\nWhen 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.\n\nIn this twentieth article of our series, we explore how to build AI-Perceivable modules in TypeScript using apcore and **TypeBox**.\n\nA 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`\n\nmust accept the same JSON input and produce the same output in both Python and TypeScript.\n\napcore-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.\n\nIn apcore-js, you define your module's contract using TypeBox's `Static`\n\nand `Type`\n\nprimitives:\n\n``` js\nimport { Type, Static } from '@sinclair/typebox';\n\nexport const InputSchema = Type.Object({\n  userId: Type.String({ description: \"The unique UUID of the user.\" }),\n  includePrivate: Type.Boolean({ default: false, description: \"Whether to include sensitive fields.\" })\n});\n\nexport type Input = Static<typeof InputSchema>;\n```\n\nBy adding the `description`\n\nfield directly into the TypeBox definition, you are creating the \"Cognitive Interface\" for the AI while simultaneously providing type hints for your IDE.\n\napcore-js supports both class-based and functional module definitions. The class-based approach is idiomatic for TypeScript developers:\n\n``` js\nimport { ClassModule, ModuleAnnotations, Context } from '@apcore/core';\n\nexport class GetUserModule extends ClassModule {\n  id = \"executor.user.get\";\n  description = \"Retrieve detailed user profiles.\";\n  inputSchema = InputSchema;\n\n  annotations = new ModuleAnnotations({\n    readonly: true,\n    destructive: false\n  });\n\n  async execute(inputs: Input, context: Context): Promise<object> {\n    // inputs is fully typed!\n    const user = await db.users.findUnique({ where: { id: inputs.userId } });\n    return { status: \"success\", user };\n  }\n}\n```\n\nManaging a registry in Node.js is just as easy as in Python. apcore-js includes a `FileSystemLoader`\n\nthat scans your directory structure.\n\nOne of the cleverest parts of the SDK is its **Automatic ID Normalization**. In TypeScript, it’s common to name your files using `camelCase`\n\n(e.g., `sendEmail.ts`\n\n). apcore-js automatically maps this to the canonical `snake_case`\n\n(e.g., `send_email`\n\n) required by the protocol. This ensures that an AI Agent sees a consistent naming convention even in a polyglot environment.\n\nAI Agents in the Node ecosystem often live inside microservices. apcore-js is built for distributed environments. It automatically propagates the `trace_id`\n\nthrough `Promise`\n\nchains and can integrate with existing tracing headers (like Zipkin or Jaeger) via custom middleware.\n\n``` js\nconst result = await executor.callAsync(\"executor.user.get\", { userId: \"123\" }, context);\n```\n\nBy 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.\n\n**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.**\n\n*This is Article #20 of the **Building the AI-Perceivable World** series. Type safety is the first step to AI safety.*\n\n**GitHub**: [aiperceivable/apcore-typescript](https://github.com/aiperceivable/apcore-typescript)", "url": "https://wpnews.pro/news/type-safe-agents-leveraging-apcore-js-in-typescript", "canonical_source": "https://dev.to/tercelyi/type-safe-agents-leveraging-apcore-js-in-typescript-2447", "published_at": "2026-06-06 12:32:25+00:00", "updated_at": "2026-06-06 13:11:56.137399+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "artificial-intelligence", "ai-products"], "entities": ["apcore-js", "TypeScript", "TypeBox", "apcore"], "alternates": {"html": "https://wpnews.pro/news/type-safe-agents-leveraging-apcore-js-in-typescript", "markdown": "https://wpnews.pro/news/type-safe-agents-leveraging-apcore-js-in-typescript.md", "text": "https://wpnews.pro/news/type-safe-agents-leveraging-apcore-js-in-typescript.txt", "jsonld": "https://wpnews.pro/news/type-safe-agents-leveraging-apcore-js-in-typescript.jsonld"}}