Open Source · MIT Licensed

Build agent swarms,
virtual worlds,
and autonomous systems

A TypeScript framework where AI agents live, think, and work together. Each agent has its own brain, memory, and tools. Snap them into teams. Scale them across machines. The class tree is the architecture.

Get StartedGitHub
Quick Start
$ npm i -g @interactkit/cli
$ interactkit init my-world
$ cd my-world && pnpm install
$ pnpm dev

You now have a running agent with an LLM brain, memory, and tools.

How it works

Everything is an entity — a TypeScript class that does one thing. Give it a brain, snap entities together, and the LLM sees all available tools automatically.

1
Define an entity
@Entity()
class Memory extends BaseEntity {
  @Describe()
  describe() {
    return `Memory: ${this.entries.length} entries.`
  }

  @State({ description: 'Entries' })
  private entries: string[] = []

  @Tool({ description: 'Store' })
  async store(input: { text: string }) {
    this.entries.push(input.text)
  }
}
2
Give it a brain
@Entity()
class Brain extends LLMEntity {
  @Describe()
  describe() {
    return 'Helpful assistant.'
  }

  @Executor()
  private llm = new ChatOpenAI({
    model: 'gpt-4o-mini'
  })

  @Ref()
  private memory!: Remote<Memory>
}
3
Snap them together
@Entity()
class Agent extends BaseEntity {
  @Component()
  private brain!: Remote<Brain>

  @Component()
  private memory!: Remote<Memory>
}

// Brain sees Memory's tools
// automatically. No glue code.
saas-company
SaasCompany
CEOLLM
SupportTeam
TicketRouterLLM
Tier1Support
T1AgentLLM
reply()
resolve()
escalate()
Tier2Support
KnowledgeBase
Engineering
Sales
ConversationContext
SlackMCP
GitHubMCP
StripeMCP
LinearMCP

What lives in your world

Entities
Each @Entity is a persistent, autonomous unit with its own state, tools, and behavior. One class, one job.
Self-describing agents
@Describe() feeds live state into LLM prompts. The system prompt reflects the current world — not a static string.
Persistent memory
@State auto-saves to database, restores on restart, and syncs across replicas.
Connections
@Component wires parent-child, @Ref links peers. Method calls work the same in-process or across machines.
External services
Any MCP server becomes a typed entity with one CLI command. Slack, GitHub, Stripe — no glue code.
Hooks & rhythms
@Hook with Init, Tick, Cron, HTTP, and WebSocket runners. Agents act on their own schedule.
Streams
EntityStream pushes real-time data from child to parent. Works in-memory or across Redis.
Build-time validation
Codegen catches missing decorators, bad refs, and Remote<T> violations before your app runs.
Distributed scaling
detached: true and it scales independently. Run 5 replicas — tasks distribute via competing consumers.
Testing built in
bootTest, mockLLM, mockEntity. Deterministic LLM tests without API calls. No special test runner.
Auto deployment
interactkit build generates Docker Compose, entrypoints per unit, and a deployment plan.
Extensions
Custom hooks, adapters, and entities as npm packages. Redis, Prisma, Cron, HTTP, WebSocket.

What can you build?

The entity tree is the architecture. These are real patterns, not demos.

Agent swarms
Multi-agent
SupportTeam
  +-- Triage (LLM)
  +-- BillingAgent
  |   +-- BillingBrain (LLM)
  |   +-- Stripe (MCP)
  |   +-- Memory
  +-- TechAgent
  |   +-- TechBrain (LLM)
  |   +-- Docs
  |   +-- Jira (MCP)
  +-- SharedContext

Teams of specialists that delegate, collaborate, and solve problems together. Each brain sees exactly the tools it needs.

Virtual worlds
Simulation
Simulation
  +-- Persona("Alice")
  |   +-- Brain (LLM)
  |   +-- Memory
  |   +-- Reddit
  |   +-- Twitter
  +-- Persona("Bob")
  |   +-- Brain (LLM)
  |   +-- Memory
  +-- Coordinator

AI personas with persistent identities that evolve over time. Memory accumulates across runs. Each persona lives its own life.

Autonomous systems
Self-driving
InfraMonitor
  +-- Brain (LLM)
  +-- Slack (MCP)
  +-- PagerDuty (MCP)
  +-- CloudAPI
// Hooks drive autonomy:
@Hook(Tick.Runner({ 60s }))
@Hook(Cron.Runner({ 9am }))
@Hook(HttpRequest.Runner())

Agents that watch, decide, and act without a human in the loop. Wire hooks to timers, cron, or webhooks.

What makes it different

ChallengeHow InteractKit handles it
Agent coordinationAgents compose into a tree. Each LLM delegates to children and siblings.
Tool visibilityEach brain only sees tools from its @Ref and @Component targets. No filtering.
Shared contextConversationContext lets multiple brains share one conversation history.
Persistent state@State auto-saves to database, restores on restart, syncs across replicas.
External servicesinteractkit add Slack --mcp-stdio "..." generates a fully typed entity.
Scalingdetached: true + Remote<T>. Same code runs across machines.
Autonomy@Hook with Tick, Cron, HTTP, WebSocket. Agents act on their own.
ObservabilityEntityStream exposes every LLM response and tool call in real time.
Ready to build your world?
MIT licensed. Open source. Read the docs and spin up your first agent swarm.
Read the DocsStar on GitHub