{"id":46365018,"url":"https://github.com/tylerjrbuell/reactive-agents-ts","last_synced_at":"2026-03-16T02:18:02.231Z","repository":{"id":339614994,"uuid":"1161775137","full_name":"tylerjrbuell/reactive-agents-ts","owner":"tylerjrbuell","description":"Composable TypeScript AI agent framework — Effect-TS type safety, 5 reasoning strategies, persistent gateway, real-time streaming, multi-agent A2A","archived":false,"fork":false,"pushed_at":"2026-03-12T02:45:40.000Z","size":9632,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-12T08:07:07.770Z","etag":null,"topics":["agent-framework","agent-observability","agent-orchestration","agentic-ai","ai-agents","anthropic","automation","bun","composable","effect-ts","gateway","google-ai","llm","mcp","multi-agent","ollama","openai","streaming","type-safe","typescript"],"latest_commit_sha":null,"homepage":"https://docs.reactiveagents.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tylerjrbuell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T14:01:27.000Z","updated_at":"2026-03-12T02:45:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tylerjrbuell/reactive-agents-ts","commit_stats":null,"previous_names":["tylerjrbuell/reactive-agents-ts"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/tylerjrbuell/reactive-agents-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerjrbuell%2Freactive-agents-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerjrbuell%2Freactive-agents-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerjrbuell%2Freactive-agents-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerjrbuell%2Freactive-agents-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tylerjrbuell","download_url":"https://codeload.github.com/tylerjrbuell/reactive-agents-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerjrbuell%2Freactive-agents-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30429293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-observability","agent-orchestration","agentic-ai","ai-agents","anthropic","automation","bun","composable","effect-ts","gateway","google-ai","llm","mcp","multi-agent","ollama","openai","streaming","type-safe","typescript"],"created_at":"2026-03-05T02:12:28.538Z","updated_at":"2026-03-16T02:18:02.206Z","avatar_url":"https://github.com/tylerjrbuell.png","language":"TypeScript","funding_links":[],"categories":["⚙️ Implementations \u0026 Libraries","Frameworks"],"sub_categories":["Tools"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/logo.png\" alt=\"Reactive Agents\" width=\"280\" /\u003e\n\n# Reactive Agents — TypeScript AI Agent Framework\n\n**The open-source agent framework built for control, not magic.**\n\nEvery decision controllable, observable, and auditable. 22 packages. composable layers. 5 reasoning strategies. 6 LLM providers. Model-adaptive context profiles. 10-phase execution engine with lifecycle hooks. 2,194 tests across 288 files. Built on Effect-TS for type safety from prompt to production.\n\n[![CI](https://github.com/tylerjrbuell/reactive-agents-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/tylerjrbuell/reactive-agents-ts/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/badge/npm-%40reactive--agents-CB3837?logo=npm)](https://www.npmjs.com/org/reactive-agents)\n[![npm downloads](https://img.shields.io/npm/dm/reactive-agents?logo=npm)](https://www.npmjs.com/package/reactive-agents)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Effect-TS](https://img.shields.io/badge/Effect--TS-3.x-7C3AED)](https://effect.website)\n[![Bun](https://img.shields.io/badge/Bun-compatible-FBF0DF?logo=bun\u0026logoColor=000000)](https://bun.sh)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/tylerjrbuell/reactive-agents-ts/pulls)\n\n[Documentation](https://docs.reactiveagents.dev/) · [Discord](https://discord.gg/498xEG5A) · [Quick Start](#quick-start) · [Features](#features) · [Comparison](#comparison) · [Architecture](#architecture) · [Packages](#packages)\n\n\u003c/div\u003e\n\n---\n\n## Why Reactive Agents?\n\nMost AI agent frameworks are dynamically typed, monolithic, and opaque. They assume you're using GPT-4, break when you try smaller models, and hide every decision behind abstractions you can't inspect. **Reactive Agents** takes a fundamentally different approach:\n\n| Problem                        | How We Solve It                                                                     |\n| ------------------------------ | ----------------------------------------------------------------------------------- |\n| **No type safety**             | Effect-TS schemas validate every service boundary at compile time                   |\n| **Monolithic**                 | 13 independent layers -- enable only what you need                                  |\n| **Opaque decisions**           | 10-phase execution engine with before/after/error hooks on every phase              |\n| **Model lock-in**              | Model-adaptive context profiles (4 tiers: local, mid, large, frontier) help smaller models punch above their weight |\n| **Single reasoning mode**      | 5 strategies (ReAct, Reflexion, Plan-Execute, Tree-of-Thought, Adaptive)            |\n| **Unsafe by default**          | Guardrails block injection/PII/toxicity before the LLM sees input                   |\n| **No cost control**            | Complexity router picks the cheapest capable model; budget enforcement at 4 levels  |\n| **Poor DX**                    | Builder API chains capabilities in one place; great frameworks disappear, ours feels like superpowers |\n\n## Features\n\n- **5 reasoning strategies** + adaptive meta-strategy (ReAct, Reflexion, Plan-Execute, Tree-of-Thought, Adaptive)\n- **6 LLM providers** -- Anthropic, OpenAI, Google Gemini, Ollama (local), LiteLLM (40+ models), Test (deterministic)\n- **Model-adaptive context profiles** -- 4 tiers (local, mid, large, frontier) with tier-aware prompts, compaction, and truncation\n- **4-layer memory** -- working, episodic, semantic (vector + FTS5), procedural (bun:sqlite); ExperienceStore for cross-agent learning; background consolidation + decay\n- **Real-time token streaming** + SSE via `agent.runStream()` with AbortSignal cancellation, `IterationProgress` + `StreamCancelled` events, and `StreamCompleted.toolSummary`\n- **Persistent autonomous gateway** -- adaptive heartbeats, cron scheduling, webhook ingestion (GitHub adapter), composable policy engine\n- **Agent debrief + conversational chat** -- `agent.chat()` and `agent.session()` (with optional SQLite persistence via `SessionStoreService`) for adaptive Q\u0026A; post-run `DebriefSynthesizer` produces structured summaries persisted to SQLite\n- **A2A multi-agent protocol** -- Agent Cards, JSON-RPC 2.0 server/client, SSE streaming, agent-as-tool composition\n- **Multi-agent orchestration** -- sequential, parallel, pipeline, and map-reduce workflows with dynamic sub-agent spawning\n- **Production guardrails** -- injection detection, PII filtering, toxicity blocking, kill switch, behavioral contracts\n- **Ed25519 identity** -- real cryptographic agent certificates, RBAC, delegation, and audit trails\n- **Cost tracking** -- complexity routing across 27 signals, semantic caching, budget enforcement with persistence across restarts\n- **Professional metrics dashboard** -- EventBus-driven execution timeline, tool call summary, smart alerts, and cost estimation (zero manual instrumentation)\n- **Required tools guard** -- ensure agents call critical tools before answering (static list or adaptive LLM inference)\n- **Builder hardening** -- `withStrictValidation()`, `withTimeout()`, `withRetryPolicy()`, `withCacheTimeout()`, consolidated `withGuardrails()` thresholds, `withErrorHandler()`, `withFallbacks()`, `withLogging()`, `withHealthCheck()`, automatic strategy switching\n- **ToolBuilder fluent API** -- define tools without raw schema objects\n- **Provider fallback chains** -- `FallbackChain` + `withFallbacks()` for graceful degradation across providers/models\n- **Structured logging** -- `makeLoggerService()` with level filtering, JSON/text format, and file output with rotation via `withLogging()`\n- **Health checks** -- `withHealthCheck()` + `agent.health()` returns `{ status, checks[] }`\n- **Reactive intelligence** -- 5-source entropy sensor, reactive controller (early-stop, context compression, strategy switch), local learning engine (conformal calibration, Thompson Sampling bandit, skill synthesis), telemetry client (api.reactiveagents.dev), `.withReactiveIntelligence()` builder method\n- **2,194 tests** across 288 files\n\n## Quick Start\n\nInstall and run your first TypeScript AI agent in under 60 seconds.\n\n```bash\nbun add reactive-agents\n```\n\n\u003e **Note:** `effect` is included as a dependency of `reactive-agents` and installed automatically. If you import from `effect` directly in your own code (e.g. `import { Effect } from \"effect\"`), add it to your project explicitly: `bun add effect`.\n\n```typescript\nimport { ReactiveAgents } from \"reactive-agents\";\n\nconst agent = await ReactiveAgents.create()\n  .withName(\"assistant\")\n  .withProvider(\"anthropic\")\n  .withModel(\"claude-sonnet-4-20250514\")\n  .build();\n\nconst result = await agent.run(\"Explain quantum entanglement\");\nconsole.log(result.output);\nconsole.log(result.metadata); // { duration, cost, tokensUsed, stepsCount }\n```\n\n### Add Capabilities\n\nEvery capability is opt-in. Chain what you need:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withName(\"research-agent\")\n  .withProvider(\"anthropic\")\n  .withReasoning()                                       // ReAct reasoning loop\n  .withTools()                                           // Built-in tools + MCP support\n  .withMemory(\"1\")                                       // Persistent memory (FTS5 search)\n  .withGuardrails()                                      // Block injection, PII, toxicity\n  .withKillSwitch()                                      // Per-agent + global emergency halt\n  .withBehavioralContracts({                             // Enforce tool whitelist + iteration cap\n    deniedTools: [\"file-write\"],\n    maxIterations: 10,\n  })\n  .withVerification()                                    // Fact-check outputs\n  .withCostTracking()                                    // Budget enforcement + model routing\n  .withObservability({ verbosity: \"verbose\", live: true }) // Live log streaming + tracing\n  .withContextProfile({ tier: \"local\" })                 // Adaptive context for model tier\n  .withIdentity()                                        // RBAC + agent certificates (Ed25519)\n  .withInteraction()                                     // 5 autonomy modes\n  .withOrchestration()                                   // Multi-agent workflows\n  .withSelfImprovement()                                 // Cross-task strategy outcome learning\n  .withRequiredTools({                                   // Ensure critical tools are called\n    tools: [\"web-search\"],\n    maxRetries: 2,\n  })\n  .withStrictValidation()                                // Throw at build time if required config is missing\n  .withTimeout(60_000)                                   // Execution timeout (ms)\n  .withRetryPolicy({ maxRetries: 3, backoffMs: 1_000 })       // Retry on transient LLM failures\n  .withCacheTimeout(3_600_000)                           // Semantic cache TTL (ms)\n  .withErrorHandler((err, ctx) =\u003e {                      // Global error callback\n    console.error(\"Agent error:\", err.message);\n  })\n  .withFallbacks({                                       // Provider/model fallback chain\n    providers: [\"anthropic\", \"openai\"],\n    errorThreshold: 3,\n  })\n  .withLogging({ level: \"info\", format: \"json\", filePath: \"./agent.log\" }) // Structured logging\n  .withHealthCheck()                                     // Enable agent.health() probe\n  .withGateway({                                         // Persistent autonomous harness\n    heartbeat: { intervalMs: 1_800_000, policy: \"adaptive\" },\n    crons: [{ schedule: \"0 9 * * MON\", instruction: \"Weekly review\" }],\n    policies: { dailyTokenBudget: 50_000 },\n  })\n  .build();\n```\n\n### Conversational Chat\n\nUse `agent.chat()` for single-turn Q\u0026A or `agent.session()` for multi-turn conversations with adaptive routing -- direct LLM for simple questions, full ReAct loop for tool-capable queries:\n\n```typescript\n// Single-turn chat\nconst answer = await agent.chat(\"What's the status of the deployment?\");\n\n// Multi-turn session\nconst session = agent.session();\nawait session.chat(\"Summarize yesterday's logs\");\nawait session.chat(\"Which errors were most frequent?\");\n```\n\n### Streaming\n\nTokens arrive as they're generated via AsyncGenerator. Pass an `AbortSignal` to cancel mid-stream:\n\n```typescript\nconst controller = new AbortController();\n\nfor await (const event of agent.runStream(\"Analyze this dataset\", { signal: controller.signal })) {\n  if (event._tag === \"TextDelta\") process.stdout.write(event.text);\n  if (event._tag === \"IterationProgress\") console.log(`Step ${event.iteration}/${event.maxIterations}`);\n  if (event._tag === \"StreamCancelled\") console.log(\"Stream cancelled\");\n  if (event._tag === \"StreamCompleted\") {\n    console.log(\"\\nDone!\");\n    // event.toolSummary: Array\u003c{ toolName, calls, successRate }\u003e\n  }\n}\n\n// Cancel from elsewhere (e.g., HTTP request abort)\ncontroller.abort();\n```\n\n### Lifecycle Hooks\n\nIntercept any of the 10 execution phases with before, after, or error hooks:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withReasoning()\n  .withTools()\n  .withHook({\n    phase: \"think\",\n    timing: \"after\",\n    handler: (ctx) =\u003e {\n      console.log(`Step ${ctx.metadata.stepsCount}: ${ctx.metadata.strategyUsed}`);\n      return Effect.succeed(ctx);\n    },\n  })\n  .withHook({\n    phase: \"act\",\n    timing: \"after\",\n    handler: (ctx) =\u003e {\n      const lastTool = ctx.scratchpad.get(\"_last_tool_name\");\n      if (lastTool) console.log(`Tool called: ${lastTool}`);\n      return Effect.succeed(ctx);\n    },\n  })\n  .build();\n```\n\nAvailable phases: `bootstrap`, `guardrail`, `cost-route`, `strategy`, `think`, `act`, `observe`, `verify`, `memory-flush`, `complete`. Each supports `before`, `after`, and `on-error` timing.\n\n## Comparison\n\nHow Reactive Agents compares to other TypeScript agent frameworks on shipped, working features:\n\n| Capability                    | Reactive Agents | LangChain JS | Vercel AI SDK | Mastra |\n| ----------------------------- | :-------------: | :----------: | :-----------: | :----: |\n| Full type safety (Effect-TS)  | Yes             | --           | Partial       | Partial |\n| Composable layer architecture | 13 layers       | --           | --            | --     |\n| Reasoning strategies          | 5 + adaptive    | 1 (ReAct)    | --            | 1      |\n| Model-adaptive context        | 4 tiers         | --           | --            | --     |\n| Local model optimization      | Yes             | --           | --            | --     |\n| Execution lifecycle hooks     | 10 phases       | Callbacks    | Middleware     | --     |\n| Multi-agent orchestration     | A2A + workflows | Yes          | --            | Yes    |\n| Token streaming               | Yes             | Yes          | Yes           | Yes    |\n| Production guardrails         | Yes             | --           | --            | --     |\n| Cost tracking + budgets       | Yes             | --           | --            | --     |\n| Persistent gateway            | Yes             | --           | --            | --     |\n| Agent debrief + chat          | Yes             | --           | --            | --     |\n| Metrics dashboard             | Yes             | LangSmith    | --            | --     |\n| Test suite                    | 2,194 tests     | --           | --            | --     |\n\n## Use Cases\n\n- **Autonomous engineering agents** with tool execution and code generation\n- **Research and reporting workflows** with verifiable reasoning steps\n- **Scheduled background agents** using heartbeats, cron jobs, and webhooks\n- **Secure enterprise copilots** with RBAC, audit trails, and policy controls\n- **Hybrid local/cloud AI deployments** with adaptive context profiles\n- **Multi-agent teams** with A2A protocol and dynamic sub-agent delegation\n\n## Architecture\n\n```\nReactiveAgentBuilder\n  -\u003e createRuntime()\n    -\u003e Core Services     EventBus, AgentService, TaskService\n    -\u003e LLM Provider      Anthropic, OpenAI, Gemini, Ollama, LiteLLM, Test\n    -\u003e Memory            Working, Semantic, Episodic, Procedural\n    -\u003e Reasoning         ReAct, Reflexion, Plan-Execute, ToT, Adaptive\n    -\u003e Tools             Registry, Sandbox, MCP Client\n    -\u003e Guardrails        Injection, PII, Toxicity, Kill Switch, Behavioral Contracts\n    -\u003e Verification      Semantic Entropy, Fact Decomposition, NLI\n    -\u003e Cost              Complexity Router, Budget Enforcer, Cache\n    -\u003e Identity          Certificates, RBAC, Delegation, Audit\n    -\u003e Observability     Tracing, Metrics, Structured Logging\n    -\u003e Interaction       5 Modes, Checkpoints, Preference Learning\n    -\u003e Orchestration     Sequential, Parallel, Pipeline, Map-Reduce\n    -\u003e Prompts           Template Engine, Version Control\n    -\u003e Gateway           Heartbeats, Crons, Webhooks, Policy Engine\n    -\u003e ExecutionEngine   10-phase lifecycle with hooks\n```\n\nEvery layer is an Effect `Layer` -- composable, independently testable, and tree-shakeable.\n\n## 10-Phase Execution Engine\n\nEvery task flows through a deterministic lifecycle. Each phase calls its corresponding service when enabled:\n\n```\nBootstrap --\u003e Guardrail --\u003e Cost Route --\u003e Strategy Select\n                                              |\n                                    +--------------------+\n                                    | Think -\u003e Act -\u003e Observe | \u003c-- loop\n                                    +--------------------+\n                                              |\nVerify --\u003e Memory Flush --\u003e Cost Track --\u003e Audit --\u003e Complete\n```\n\n| Phase             | Service Called           | What It Does                                       |\n| ----------------- | ------------------------ | -------------------------------------------------- |\n| Bootstrap         | MemoryService            | Load context from semantic/episodic memory         |\n| Guardrail         | GuardrailService         | Block unsafe input before LLM sees it              |\n| Cost Route        | CostService              | Select optimal model tier by complexity            |\n| Strategy Select   | ReasoningService         | Pick reasoning strategy (or direct LLM)            |\n| Think/Act/Observe | LLMService + ToolService | Reasoning loop with real tool execution            |\n| Verify            | VerificationService      | Fact-check output (entropy, decomposition, NLI)    |\n| Memory Flush      | MemoryService            | Persist session + episodic memories                |\n| Cost Track        | CostService              | Record spend against budget                        |\n| Audit             | ObservabilityService     | Log audit trail (tokens, cost, strategy, duration) |\n| Complete          | --                       | Build final result with metadata                   |\n\nEvery phase supports `before`, `after`, and `on-error` lifecycle hooks. When observability is enabled, every phase emits trace spans and metrics.\n\n## 5 Reasoning Strategies\n\n| Strategy            | How It Works                             | Best For                      |\n| ------------------- | ---------------------------------------- | ----------------------------- |\n| **ReAct**           | Think -\u003e Act -\u003e Observe loop             | Tool use, step-by-step tasks  |\n| **Reflexion**       | Generate -\u003e Critique -\u003e Improve          | Quality-critical output       |\n| **Plan-Execute**    | Plan steps -\u003e Execute -\u003e Reflect -\u003e Refine | Structured multi-step work  |\n| **Tree-of-Thought** | Branch -\u003e Score -\u003e Prune -\u003e Synthesize   | Creative, open-ended problems |\n| **Adaptive**        | Analyze task -\u003e Auto-select best strategy | Mixed workloads              |\n\n```typescript\n// Auto-select the best strategy per task\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withReasoning({ defaultStrategy: \"adaptive\" })\n  .build();\n\n// Automatic strategy switching on loop detection\nconst agent2 = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withReasoning({\n    enableStrategySwitching: true,\n    maxStrategySwitches: 1,\n    fallbackStrategy: \"plan-execute-reflect\",\n  })\n  .build();\n```\n\n## Multi-Provider Support\n\n| Provider          | Models                        | Tool Calling | Streaming |\n| ----------------- | ----------------------------- | :----------: | :-------: |\n| **Anthropic**     | Claude Haiku, Sonnet, Opus    |      Yes     |    Yes    |\n| **OpenAI**        | GPT-4o, GPT-4o-mini           |      Yes     |    Yes    |\n| **Google Gemini** | Gemini Flash, Pro             |      Yes     |    Yes    |\n| **Ollama**        | Any local model               |     Yes      |    Yes    |\n| **LiteLLM**       | 40+ models via LiteLLM proxy  |      Yes     |    Yes    |\n| **Test**          | Mock (deterministic)          |      --      |    --     |\n\nSwitch providers with one line -- agent code stays the same.\n\n## Model-Adaptive Context\n\nOptimize prompt construction and context compaction for your model tier:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"ollama\")\n  .withModel(\"qwen3:4b\")\n  .withReasoning()\n  .withTools()\n  .withContextProfile({ tier: \"local\" }) // Lean prompts, aggressive compaction\n  .build();\n```\n\n| Tier         | Models                     | Context Strategy                                                       |\n| ------------ | -------------------------- | ---------------------------------------------------------------------- |\n| `\"local\"`    | Ollama small models (\u003c=14b) | Lean prompts, aggressive compaction after 6 steps, 800-char truncation |\n| `\"mid\"`      | Mid-range models            | Balanced prompts, moderate compaction                                  |\n| `\"large\"`    | Anthropic, OpenAI, Gemini  | Full context, standard compaction                                      |\n| `\"frontier\"` | Flagship models            | Maximum context, minimal compaction                                    |\n\n## Packages\n\n| Package                                                    | Description                                                                     |\n| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| [`@reactive-agents/core`](packages/core)                   | EventBus pub/sub, AgentService lifecycle, TaskService state machine, canonical types |\n| [`@reactive-agents/runtime`](packages/runtime)             | 10-phase ExecutionEngine, ReactiveAgentBuilder, `createRuntime()` layer composer |\n| [`@reactive-agents/llm-provider`](packages/llm-provider)   | Unified LLM interface for Anthropic, OpenAI, Gemini, Ollama, LiteLLM, and Test providers |\n| [`@reactive-agents/memory`](packages/memory)               | 4-layer memory (working, semantic, episodic, procedural) on bun:sqlite; ExperienceStore cross-agent learning; background consolidation + decay |\n| [`@reactive-agents/reasoning`](packages/reasoning)         | 5 strategies (ReAct, Reflexion, Plan-Execute, ToT, Adaptive) with composable kernel architecture |\n| [`@reactive-agents/tools`](packages/tools)                 | Tool registry with sandboxed execution, MCP client, agent-as-tool adapter, dynamic sub-agent spawning |\n| [`@reactive-agents/guardrails`](packages/guardrails)       | Pre-LLM safety: injection detection, PII filtering, toxicity blocking          |\n| [`@reactive-agents/verification`](packages/verification)   | Post-LLM quality: semantic entropy, fact decomposition, NLI hallucination detection |\n| [`@reactive-agents/cost`](packages/cost)                   | 27-signal complexity routing, per-execution budget enforcement, semantic cache   |\n| [`@reactive-agents/identity`](packages/identity)           | Ed25519 agent certificates, RBAC policies, delegation chains, audit logging     |\n| [`@reactive-agents/observability`](packages/observability) | Distributed tracing (OTLP), MetricsCollector, structured logging, console + JSON exporters |\n| [`@reactive-agents/interaction`](packages/interaction)     | 5 autonomy modes, checkpoint/resume, approval gates, preference learning        |\n| [`@reactive-agents/orchestration`](packages/orchestration) | Multi-agent workflows: sequential, parallel, pipeline, map-reduce with A2A support |\n| [`@reactive-agents/prompts`](packages/prompts)             | Version-controlled template engine with variable interpolation and prompt library |\n| [`@reactive-agents/eval`](packages/eval)                   | Evaluation framework: LLM-as-judge scoring, EvalStore persistence, comparison reports |\n| [`@reactive-agents/a2a`](packages/a2a)                     | A2A protocol: Agent Cards, JSON-RPC 2.0 server/client, SSE streaming            |\n| [`@reactive-agents/gateway`](packages/gateway)             | Persistent autonomous harness: adaptive heartbeats, cron scheduling, webhook ingestion, composable policy engine |\n| [`@reactive-agents/testing`](packages/testing)             | Mock services (LLM, tools, EventBus), assertion helpers, deterministic test fixtures |\n| [`@reactive-agents/benchmarks`](packages/benchmarks)       | Benchmark suite: 20 tasks x 5 tiers, overhead measurement, report generation    |\n| [`@reactive-agents/health`](packages/health)               | Health checks and readiness probes for production deployments                    |\n| [`@reactive-agents/reactive-intelligence`](packages/reactive-intelligence) | Metacognitive layer: entropy sensor (5 sources), reactive controller (early-stop, compression, strategy switch), learning engine (calibration, bandit, skill synthesis), telemetry client |\n\n## Observability \u0026 Metrics Dashboard\n\nWhen observability is enabled, the agent displays a professional metrics dashboard after each execution:\n\n```\n+-------------------------------------------------------------+\n| Agent Execution Summary                                      |\n+-------------------------------------------------------------+\n| Status:    Success      Duration: 13.9s   Steps: 7          |\n| Tokens:    1,963        Cost: ~$0.003     Model: claude-3.5 |\n+-------------------------------------------------------------+\n\nExecution Timeline\n|- [bootstrap]       100ms    ok\n|- [think]        10,001ms    warn  (7 iter, 72% of time)\n|- [act]           1,000ms    ok    (2 tools)\n|- [complete]         28ms    ok\n\nTool Execution (2 called)\n|- file-write    ok  3 calls, 450ms avg\n|- web-search    ok  2 calls, 280ms avg\n```\n\n- Per-phase execution timing and bottleneck identification\n- Tool call summary (success/error counts, average duration)\n- Smart alerts and optimization tips\n- Cost estimation in USD\n- EventBus-driven collection (no manual instrumentation)\n\nEnable with:\n\n```typescript\n.withObservability({ verbosity: \"normal\", live: true })\n```\n\n## CLI (`rax`)\n\n```bash\nrax init my-project --template full              # Scaffold a project\nrax create agent researcher --recipe researcher   # Generate an agent from recipe\nrax create agent my-agent --interactive           # Interactive scaffolding (readline prompts)\nrax run \"Explain quantum computing\" --provider anthropic  # Run an agent\n```\n\n## Register Custom Tools\n\nTools are registered at build time or via `ToolService.register()`. Built-in tools (web search, file I/O, HTTP, code execution, scratchpad, spawn-agent) are available automatically when the relevant builder methods are enabled.\n\nUse the `ToolBuilder` fluent API to define tools without raw schema objects:\n\n```typescript\nimport { ReactiveAgents } from \"reactive-agents\";\nimport { ToolBuilder } from \"@reactive-agents/tools\";\nimport { Effect } from \"effect\";\n\nconst webSearchTool = ToolBuilder.create(\"web_search\")\n  .description(\"Search the web for current information\")\n  .param(\"query\", \"string\", \"Search query\", { required: true })\n  .riskLevel(\"low\")\n  .timeout(10_000)\n  .handler((args) =\u003e Effect.succeed(`Results for: ${args.query}`))\n  .build();\n\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withReasoning()\n  .withTools({ tools: [webSearchTool] })\n  .build();\n```\n\nOr use raw schema objects directly:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withReasoning()\n  .withTools({\n    tools: [\n      {\n        definition: {\n          name: \"web_search\",\n          description: \"Search the web for current information\",\n          parameters: [\n            { name: \"query\", type: \"string\", description: \"Search query\", required: true },\n          ],\n          riskLevel: \"low\",\n          timeoutMs: 10_000,\n          requiresApproval: false,\n          source: \"function\",\n        },\n        handler: (args) =\u003e Effect.succeed(`Results for: ${args.query}`),\n      },\n    ],\n  })\n  .build();\n```\n\n### Dynamic Sub-Agent Spawning\n\nUse `.withDynamicSubAgents()` to let the model spawn ad-hoc sub-agents at runtime without pre-configuring named agent tools. This registers the built-in `spawn-agent` tool, which the model can invoke freely:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withProvider(\"anthropic\")\n  .withModel(\"claude-sonnet-4-6\")\n  .withTools()\n  .withDynamicSubAgents({ maxIterations: 5 })\n  .build();\n```\n\nSub-agents receive a clean context window, inherit the parent's provider and model by default, and are depth-limited to `MAX_RECURSION_DEPTH = 3`.\n\n| Approach                         | When to use                                            |\n| -------------------------------- | ------------------------------------------------------ |\n| `.withAgentTool(\"name\", config)` | Named, purpose-built sub-agent with a specific role    |\n| `.withDynamicSubAgents()`        | Ad-hoc delegation at model's discretion, unknown tasks |\n\n## Testing\n\nBuilt-in test scenario support for deterministic, offline tests:\n\n```typescript\nconst agent = await ReactiveAgents.create()\n  .withTestScenario([\n    { match: \"capital of France\", text: \"Paris is the capital of France.\" },\n  ])\n  .build();\n\nconst result = await agent.run(\"What is the capital of France?\");\n// result.output -\u003e \"Paris is the capital of France.\"\n```\n\nThe `@reactive-agents/testing` package includes streaming assertions and pre-built scenario fixtures:\n\n```typescript\nimport { expectStream, createGuardrailBlockScenario, createBudgetExhaustedScenario } from \"@reactive-agents/testing\";\n\n// Stream assertions\nconst stream = agent.runStream(\"Write a haiku\");\nawait expectStream(stream)\n  .toEmitTextDeltas()\n  .toComplete()\n  .toEmitEvents([\"TextDelta\", \"StreamCompleted\"]);\n\n// Pre-built scenario fixtures\nconst scenario = createGuardrailBlockScenario(); // agent + prompt that triggers guardrail\nconst budget = createBudgetExhaustedScenario();  // agent + prompt that exhausts budget\nconst maxIter = createMaxIterationsScenario();   // agent + prompt that hits max iterations\n```\n\n## FAQ\n\n### Which models and providers are supported?\n\nReactive Agents supports 6 providers: Anthropic, OpenAI, Google Gemini, Ollama (local models), LiteLLM (40+ models via proxy), and a Test provider for deterministic offline testing via `withTestScenario()`.\n\n### Is this framework production-ready?\n\nYes -- it includes guardrails, budget controls, auditability, observability, Ed25519 identity, and composable service layers for testable deployments. 2,194 tests across 288 files.\n\n### Can I run fully local agents?\n\nYes -- use Ollama with local models plus context profiles tuned for local inference. The `\"local\"` tier optimizes prompts and compaction for small models (\u003c=14b parameters).\n\n### How does this compare to LangChain or Vercel AI SDK?\n\nSee the [comparison table](#comparison). The key differences are: full Effect-TS type safety, composable layers instead of a monolithic runtime, 5 reasoning strategies with adaptive selection, and model-adaptive context profiles that help local models perform far beyond naive prompting.\n\n## Development\n\n```bash\nbun install              # Install dependencies\nbun test                 # Run full test suite (2,194 tests, 288 files)\nbun run build            # Build all packages (22 packages, ESM + DTS)\n```\n\n## Environment Variables\n\n```bash\nANTHROPIC_API_KEY=sk-ant-...          # Anthropic Claude\nOPENAI_API_KEY=sk-...                 # OpenAI GPT-4o\nGOOGLE_API_KEY=...                    # Google Gemini\nEMBEDDING_PROVIDER=openai             # For vector memory\nEMBEDDING_MODEL=text-embedding-3-small\nLLM_DEFAULT_MODEL=claude-sonnet-4-20250514\n```\n\n## Documentation\n\nFull documentation at **[docs.reactiveagents.dev](https://docs.reactiveagents.dev/)**\n\n- [Getting Started](https://docs.reactiveagents.dev/guides/quickstart/) -- Build an agent in 5 minutes\n- [Reasoning Strategies](https://docs.reactiveagents.dev/guides/reasoning/) -- All 5 strategies explained\n- [Architecture](https://docs.reactiveagents.dev/concepts/architecture/) -- Layer system deep dive\n- [Cookbook](https://docs.reactiveagents.dev/cookbook/testing-agents/) -- Testing, multi-agent patterns, production deployment\n\n## Getting Help\n\n- **Discord** -- [Join the community](https://discord.gg/498xEG5A) for questions, discussions, and support\n- **GitHub Issues** -- [Report bugs or request features](https://github.com/tylerjrbuell/reactive-agents-ts/issues)\n- **GitHub Discussions** -- [Ask questions and share ideas](https://github.com/tylerjrbuell/reactive-agents-ts/discussions)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylerjrbuell%2Freactive-agents-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftylerjrbuell%2Freactive-agents-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylerjrbuell%2Freactive-agents-ts/lists"}