⚠️ Warning: This is alpha software under active development. APIs may change. Not recommended for production use yet.

Idyllic compiles TypeScript classes into stateful actors on Cloudflare's edge. You write agent logic. The framework handles persistence, streaming, and typed RPC.

class ResearchAgent extends AgenticSystem {
  @field query = '';
  @field response = stream<string>('');
  @field sources: Source[] = [];

  @action()
  async research(topic: string) {
    this.query = topic;

    for await (const chunk of this.llm.stream(topic)) {
      this.response.append(chunk);
    }
    this.response.complete();
  }
}

State syncs to connected clients over WebSocket. Methods become typed RPCs. Agents survive restarts, disconnects, and deploys.

Why Idyllic

Applications, not conversations. Your agent's interface isn't chat(). It's typed methods on stateful objects.

TypeScript-native. Classes, types, decorators. No DSL. No YAML. If you know TypeScript, you know Idyllic.

Real-time by default. State streams to your UI. Agents stream to each other. No polling. No webhooks.

Edge deployment. Write a class, deploy a globally distributed stateful actor. 300+ locations. No Kubernetes.

Quick Start

npx @idyllic-labs/idyllic dev

This scaffolds a new project and starts the dev server with hot reload.

React Integration

import { useSystem } from '@idyllic-labs/idyllic/react';
import { ResearchAgentMeta, type ResearchAgentClient } from './idyllic/__generated__/client';

function App() {
  const { query, response, research } = useSystem<ResearchAgentClient>({
    meta: ResearchAgentMeta
  });

  return (
    <div>
      <button onClick={() => research('quantum computing')}>Research</button>
      <p>{response.current}</p>
      {response.status === 'streaming' && <span>...</span>}
    </div>
  );
}

Core Primitives

| Primitive | Purpose | |-----------|---------| | @field | Client-synced state. Assignments broadcast to all connected clients. | | stream<T>() | Streaming field with .append() and .complete(). | | @action() | Method callable from clients via typed RPC. |

Documentation

Full documentation at docs.idyllic.so

• Getting Started
• Core Concepts
• API Reference
• Deployment

License

MIT