Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createApp
✓ import { createApp } from '@agentick/core';
✗ const { createApp } = require('@agentick/core');
Agentick is primarily an ESM-first framework, especially when used with modern Node.js and TypeScript.
System
✓ import { System } from '@agentick/core';
✗ import System from '@agentick/core';
System is a named export from the @agentick/core package.
createTool
✓ import { createTool } from '@agentick/core';
✗ const createTool = require('@agentick/core').createTool;
This function is central to defining custom AI tools within the Agentick JSX environment.
openai
✓ import { openai } from '@agentick/openai';
Used to configure the OpenAI model integration for your Agentick application.
This quickstart demonstrates creating a simple research agent using Agentick's JSX components to define system instructions, include conversation history, and integrate a custom search tool, then running it with an OpenAI model.
import { createApp, System, Timeline, createTool, useContinuation } from "@agentick/core";
import { openai } from "@agentick/openai";
import { z } from "zod";
const knowledgeBase = {
search: async (query: string) => {
// Simulate a search against a knowledge base
console.log(`Searching for: ${query}`);
if (query.includes("quantum computing")) {
return [{ title: "Quantum computing advances", snippet: "Recent breakthroughs in error correction and qubit stability." }];
}
return [{ title: "General AI trends", snippet: "Overview of current AI research directions." }];
}
};
const Search = createTool({
name: "search",
description: "Search the knowledge base",
input: z.object({ query: z.string() }),
handler: async ({ query }) => {
const results = await knowledgeBase.search(query);
return [{ type: "text", text: JSON.stringify(results) }];
}
});
function ResearchAgent() {
useContinuation((result) => result.tick < 10); // Limit ticks to prevent infinite loops
return (
<>
<System>Search thoroughly, then write a summary based on the findings.</System>
<Timeline />
<Search />
</>
);
}
// Ensure process.env.OPENAI_API_KEY is set or passed securely
const openAIApiKey = process.env.OPENAI_API_KEY ?? '';
const app = createApp(ResearchAgent, { model: openai({ model: "gpt-4o", apiKey: openAIApiKey }) });
(async () => {
if (!openAIApiKey) {
console.error("OPENAI_API_KEY environment variable is not set. Please set it to run the example.");
return;
}
const result = await app.run({
messages: [
{ role: "user", content: [{ type: "text", text: "What's new in quantum computing?" }] }
]
});
console.log("Agent Response:", result.response);
})();
Errors
Common errors & fixes
Cannot use JSX unless the '--jsx' flag is provided. ts(17004)
The TypeScript compiler is not configured to process JSX syntax, or the `jsxImportSource` is missing.
fixEnsure your `tsconfig.json` includes `"jsx": "react-jsx"` and `"jsxImportSource": "react"` under `compilerOptions`.
Module not found: Error: Can't resolve '@agentick/core'
One or more of the required Agentick packages or its peer dependencies have not been installed in your project.
fixRun `npm install agentick @agentick/openai zod react` to install the core framework, model integrations, schema validation, and React.
TypeError: Cannot read properties of undefined (reading 'split') or similar runtime error related to missing API key.
The OpenAI API key (or other model provider key) required for the model integration is not provided or is invalid.
fixEnsure the `OPENAI_API_KEY` environment variable is set or explicitly pass the `apiKey` property when initializing the OpenAI model in `createApp`.
Audit
Dependencies
@agentick/corerequiredCore functionality for the Agentick framework.
@agentick/openaioptionalIntegration for OpenAI models.
zodrequiredSchema validation for defining tool inputs and outputs.
reactrequiredPeer dependency for JSX reconciliation and hooks.