agentiny

Build reactive agents in TypeScript with state, triggers, conditions, and actions.

Zero runtime dependencies. Full TypeScript support. Designed for in-process automation, workflow orchestration, and AI-assisted actions.

import { Agent } from '@agentiny/core';

const agent = new Agent({ initialState: { count: 0 } });

agent.when((state) => state.count > 5, [(state) => console.log('Milestone reached:', state.count)]);

await agent.start();
agent.setState({ count: 10 });
await agent.settle();
await agent.stop();

Packages

Package	Purpose	Status
@agentiny/core	Core trigger-condition-action framework	Foundation
@agentiny/utils	Retry, timeout, and validation helpers	Ready
@agentiny/openai	OpenAI-backed agent actions	Ready
@agentiny/anthropic	Anthropic-backed agent actions	Ready
@agentiny/gemini	Google Gemini-backed agent actions	Ready

Quick Start

Install the core package

npm install @agentiny/core

Create an agent

import { Agent } from '@agentiny/core';

interface AppState {
  temperature: number;
  alarm: boolean;
}

const agent = new Agent<AppState>({
  initialState: { temperature: 0, alarm: false },
});

agent.when(
  (state) => state.temperature > 30,
  [(state) => (state.alarm = true), (state) => console.log('Alert!')],
);

agent.when(
  (state) => state.temperature <= 25,
  [(state) => (state.alarm = false), (state) => console.log('Normal')],
);

await agent.start();
agent.setState({ temperature: 35 });
await agent.settle();
agent.setState({ temperature: 20 });
await agent.settle();
await agent.stop();

Schedule actions on time

every(interval, ...) fires repeatedly. The interval is either milliseconds or a duration string (ms, s, m, h). at(time, ...) fires at a wall-clock time in the host's local timezone — "HH:MM" (24h) or "9:30pm" / "9:30 AM" (12h); repeats daily, or pass { once: true } for a single-shot.

agent.every('2h', [refreshFeed]);
agent.every('5s', [poll], { immediate: true });
agent.at('21:30', [sendDailyReport]);
agent.at('00:00', [resetCounters], { once: true });

Add AI actions

import { Agent } from '@agentiny/core';
import { createOpenAIAction } from '@agentiny/openai';

const aiAction = createOpenAIAction({
  apiKey: process.env.OPENAI_API_KEY,
  prompt: (state) => `Respond to: ${state.userInput}`,
  onResponse: (result, state) => {
    state.reply = result.text;
  },
});

const agent = new Agent({ initialState: { userInput: '' } });
agent.when((state) => state.userInput.length > 0, [aiAction]);

Core Concepts

• Triggers decide when an agent should act, using state checks, named events, or wall-clock time.
• Conditions add extra guards before actions run.
• Actions mutate state or perform side effects.
• settle() waits for cascading trigger/action chains to finish.
• waitFor(predicate) resolves with the state once a specific condition is met.

Documentation

• Core README - Full core package documentation
• Utils - Retry, timeout, and validation helpers
• OpenAI - OpenAI integration
• Anthropic - Anthropic integration
• Gemini - Google Gemini integration

Development

Use Node.js 22.12+ and npm 10+. Node.js 24 is recommended (.nvmrc).

git clone https://github.com/keldrik/agentiny.git
cd agentiny
npm ci
npm run check

Common commands:

npm run typecheck
npm run lint
npm run lint:fix
npm run format
npm run format:write
npm run build
npm test
npm run test:smoke

Linting uses oxlint and formatting uses oxfmt. npm run check runs the same lint, formatting, type, test, build, and package-export checks as CI. Tests use mocked AI clients and do not require API keys.

See CONTRIBUTING.md for the workspace layout, individual package commands, editor setup, and dependency workflow.

License

MIT - See LICENSE.