Agentick AI Component Framework

Common errors

• Cannot use JSX unless the '--jsx' flag is provided. ts(17004)

  cause The TypeScript compiler is not configured to process JSX syntax, or the `jsxImportSource` is missing.
  fix Ensure your `tsconfig.json` includes `"jsx": "react-jsx"` and `"jsxImportSource": "react"` under `compilerOptions`.

• Module not found: Error: Can't resolve '@agentick/core'

  cause One or more of the required Agentick packages or its peer dependencies have not been installed in your project.
  fix Run `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.

  cause The OpenAI API key (or other model provider key) required for the model integration is not provided or is invalid.
  fix Ensure the `OPENAI_API_KEY` environment variable is set or explicitly pass the `apiKey` property when initializing the OpenAI model in `createApp`.

Warnings

• breaking As a pre-1.0 package (currently 0.14.47), Agentick is under active development. Users should anticipate frequent breaking changes between minor versions as the API matures and stabilizes. Always review release notes when upgrading.
  Fix: Consult the official GitHub repository for recent changelogs and migration guides before updating dependencies. Pin exact versions in production.
• gotcha To use Agentick's JSX syntax with TypeScript, your `tsconfig.json` must be correctly configured. Specifically, the `compilerOptions.jsx` and `compilerOptions.jsxImportSource` fields are critical.
  Fix: Add the following to your `tsconfig.json` under `compilerOptions`: `"jsx": "react-jsx"` and `"jsxImportSource": "react"`.
• gotcha Agentick employs a novel paradigm where the AI model's context window is built declaratively with React-like JSX components. This differs significantly from traditional prompt engineering or chain-based AI frameworks, requiring a mental model shift.
  Fix: Familiarize yourself with the core concepts of Agentick's 'React reconciler for LLMs' approach. Understand that components render directly into the model's perceived input, and hooks control execution flow.

Install

• npm install agentick npm
• yarn add agentick yarn
• pnpm add agentick pnpm

Imports

• createApp
  wrong:

  const { createApp } = require('@agentick/core');

  correct:

  import { createApp } from '@agentick/core';

  Agentick is primarily an ESM-first framework, especially when used with modern Node.js and TypeScript.
• System
  wrong:

  import System from '@agentick/core';

  correct:

  import { System } from '@agentick/core';

  System is a named export from the @agentick/core package.
• createTool
  wrong:

  const createTool = require('@agentick/core').createTool;

  correct:

  import { createTool } from '@agentick/core';

  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.

Quickstart

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);
})();