Effective Agent

Overview

Effective Agent is a TypeScript application framework for building robust, scalable, concurrent, and maintainable AI agents and agent-based systems. It is designed to reduce the complexity of developing sophisticated agents by providing a modular, Effect-TS-based architecture. The framework leverages the Effect system for composable asynchronous operations, strong type safety, and powerful dependency management.

At the heart of the application is the AgentRuntimeService, which serves as the central orchestration layer. It provides a unified interface for:

• Agent Management: Creating, terminating, and managing agent lifecycles with type-safe state handling
• Service Access: Providing configured AI services (ModelService, ProviderService, PolicyService) to applications
• Message Processing: Handling agent activities through prioritized mailboxes with streaming capabilities
• Runtime Orchestration: Coordinating service initialization while maintaining clean separation of concerns

Architecture Principles

Service Self-Configuration: Each domain service is responsible for loading its own configuration via ConfigurationService, eliminating circular dependencies and ensuring clean initialization.

Effect.Service Pattern: All services use the Effect.Service pattern for dependency injection, providing automatic layer management and type-safe service access.

Functional Design: Built on Effect-TS for composable, type-safe asynchronous operations with comprehensive error handling and recovery patterns.

Agent-Centric Runtime: Designed specifically for managing multi-capability AI agents with stateful execution and prioritized message processing.

Key Features

• Unified Service Interface: Access all AI services (models, providers, policies) through a single AgentRuntimeService
• Self-Configuring Services: Services load their own configurations, reducing coupling and improving maintainability
• Type-Safe Agent Management: Create and manage agents with full TypeScript type safety
• Advanced Error Recovery: Built-in circuit breakers, retries, and fallback strategies
• Performance Monitoring: Comprehensive metrics and health checking for all services
• Configuration Validation: Schema-based validation for all configuration files

---

Service Architecture

src/
├── ea-agent-runtime/   # Central agent orchestration service
├── services/
│   ├── ai/
│   │   ├── model/          # AI model definitions and capabilities
│   │   ├── policy/         # Usage policies and rate limiting
│   │   ├── provider/       # AI provider configurations and clients
│   │   ├── tool-registry/  # Central tool registry
│   │   └── tools/          # Tool execution and validation
│   ├── core/
│   │   ├── configuration/  # Configuration loading and validation
│   │   ├── health/         # Service health monitoring
│   │   ├── performance/    # Performance metrics
│   │   ├── test-utils/     # Testing utilities (effect-test-harness)
│   │   └── websocket/      # Real-time communication
│   ├── execution/
│   │   ├── orchestrator/   # Policy-enforced operation orchestration
│   │   └── resilience/     # Circuit breakers, retries, fallbacks
│   ├── capabilities/
│   │   └── skill/          # Modular agent skills
│   ├── input/              # Input validation and transformation
│   └── producers/          # Multi-modal output generation
│       ├── chat/           # AI chat completions
│       ├── embedding/      # Vector embeddings
│       ├── image/          # Image generation
│       ├── object/         # Structured object generation
│       ├── text/           # Text generation
│       └── transcription/  # Audio transcription
└── ea-cli/                 # Command-line interface

---

Core Services

AgentRuntimeService

The central orchestration layer providing:

• Agent Lifecycle Management: Create, terminate, and monitor agent execution
• Service Access: Unified interface to ModelService, ProviderService, PolicyService
• Message Handling: Prioritized mailbox processing with activity streaming
• State Management: Type-safe agent state with concurrent updates

// Get configured services through AgentRuntimeService
const runtime = yield* AgentRuntimeService;
const modelService = yield* runtime.getModelService();
const policyService = yield* runtime.getPolicyService();

// Create and manage agents
const agent = yield* runtime.create("agent-1", initialState);
yield* agent.send(activity);

AI Services

ModelService: Self-configures from models.json via environment variable MODELS_CONFIG_PATH

• Validates model availability and capabilities
• Provides model metadata and provider mappings
• Supports capability-based model selection

ProviderService: Self-configures from providers.json via environment variable PROVIDERS_CONFIG_PATH

• Manages AI provider clients and configurations
• Handles API key management and authentication
• Provides provider capability validation

PolicyService: Self-configures from policies.json via environment variable POLICY_CONFIG_PATH

• Enforces usage policies and rate limits
• Records policy outcomes for auditing
• Supports rule-based access control

Core Infrastructure

ConfigurationService: Central configuration management

• Loads and validates all configuration files
• Provides schema-based validation
• Supports environment-specific configurations

FileSystem: Cross-platform file operations

• Abstracts Node.js and Bun file systems via @effect/platform
• Provides Effect-based file operations
• Supports both sync and async operations

---

Getting Started

Prerequisites

• Bun v1.0+
• Node.js v18+ (for compatibility)
• TypeScript 5.8+

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/EffectiveAgent.git
   cd EffectiveAgent

2. Install dependencies:

   bun install

Configuration

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your API keys:
   # - ANTHROPIC_API_KEY
   # - OPENAI_API_KEY
   # - GROQ_API_KEY
   # (etc. for other providers)

4. Configure master settings:

   # The default configuration is located at:
   # configuration/config/master-config.json
   
   # Set the path via environment variable (optional):
   export MASTER_CONFIG_PATH=./configuration/config/master-config.json

5. Configure AI services:

   Configuration files are in configuration/config/:

   • models.json - AI model definitions and capabilities
   • providers.json - Provider configurations
   • policies.json - Usage policies and rate limits

   Edit these files to customize your AI service configurations.

Development

6. Run tests:

   bun test
   
   # Run with coverage
   bun test --coverage
   
   # Run a specific test file
   bun test path/to/test.test.ts

7. Build the project:

   bun run build

8. Type checking:

   bun run typecheck

9. Lint code:

   bunx biome lint .

---

Quick Start Example

import { AgentRuntimeService } from "@/ea-agent-runtime";
import { Effect, Layer } from "effect";

// Basic agent creation and management
const program = Effect.gen(function* () {
  // Get the runtime service
  const runtime = yield* AgentRuntimeService;

  // Access configured AI services
  const modelService = yield* runtime.getModelService();
  const defaultModel = yield* modelService.getDefaultModelId();

  // Create an agent with initial state
  const agent = yield* runtime.create("my-agent", {
    status: "ready",
    model: defaultModel
  });

  // Send activities to the agent
  yield* agent.send({
    type: "user-message",
    content: "Hello, agent!"
  });

  // Monitor agent state
  const currentState = yield* agent.getState();
  console.log("Agent state:", currentState);

  return agent;
});

// Run with proper service dependencies
Effect.runPromise(program.pipe(
  Effect.provide(AgentRuntimeService.Default)
)).then(
  (agent) => console.log("Agent created successfully:", agent),
  (error) => console.error("Failed to create agent:", error)
);

---

Project Structure

EffectiveAgent/
├── src/
│   ├── ea-agent-runtime/    # Core agent runtime
│   ├── ea-cli/              # Command-line interface
│   ├── services/            # Modular service architecture
│   ├── examples/            # Usage examples
│   └── docs/                # Technical documentation
├── configuration/
│   └── config/              # Configuration files
├── architecture-explorer/   # Architecture visualization tool
└── tests/                   # Test files

---

Documentation

Core Documentation

• Agent Runtime Architecture - Runtime design and patterns
• Agent Runtime API - API reference
• Examples - Usage examples

Development Guides

• Service Pattern Guide - Effect.Service pattern
• Testing Strategy - Testing best practices
• Test Harness Utilities - Testing tools

Architecture

• System Architecture - Overall system design
• Technology Stack - Tech stack overview

---

Technology Stack

• Runtime: Bun & Node.js
• Language: TypeScript 5.8+
• Effect System: Effect-TS 3.16+
• AI SDK: Vercel AI SDK (via @effective-agent/ai-sdk)
• Testing: Vitest
• Linting: Biome
• AI Providers: Anthropic, OpenAI, Groq, Google, DeepSeek, xAI, Perplexity

---

Packages

@effective-agent/ai-sdk

A standalone Effect-TS communication layer for AI operations, providing type-safe wrappers around the Vercel AI SDK.

Key Features:

• Type-Safe AI Operations: Effect wrappers for generateText, generateObject, embedMany
• Message Transformation: Bidirectional conversion between EffectiveMessage and Vercel CoreMessage
• Schema Conversion: Utilities for Effect Schema ↔ Zod/Standard Schema
• Provider Factory: Create and manage AI provider instances (OpenAI, Anthropic, Google, etc.)
• Error Handling: Comprehensive error types with Effect integration

Remaining Legacy Code:

• Image and Transcription producers still use getProviderClient since image generation and transcription operations are not yet implemented in the ai-sdk package
• Deprecated method maintained for backward compatibility until these features are added to ai-sdk

Package Structure:

packages/effect-aisdk/
├── src/
│   ├── index.ts            # Main exports
│   ├── errors.ts           # AiSdk error types
│   ├── message.ts          # EffectiveMessage & Part schemas
│   ├── message-transformer.ts  # Message format conversion
│   ├── schema-converter.ts # Schema utilities
│   ├── provider-factory.ts # Provider creation
│   ├── ai-operations.ts    # generateText, generateObject, embedMany
│   ├── types.ts            # Core types (EffectiveResponse, etc.)
│   ├── input-types.ts      # Option types
│   └── result-types.ts     # Result types
├── package.json
└── tsconfig.json

Usage Example:

import {
  createProvider,
  getLanguageModel,
  generateTextWithModel,
  type EffectiveInput,
} from "@effective-agent/ai-sdk";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  // Create provider
  const provider = yield* createProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY!
  });

  // Get model
  const model = yield* getLanguageModel(provider, "gpt-4");

  // Generate text
  const input: EffectiveInput = {
    text: "Hello, AI!",
    messages: Chunk.empty()
  };

  const response = yield* generateTextWithModel(model, input);
  console.log(response.data.text);
});

---

Contributing

When contributing to EffectiveAgent:

1. Follow the Effect.Service pattern - All services must use the Effect.Service class pattern
2. Write tests - Use integration tests with real services (no mocks)
3. Update documentation - Keep docs in sync with code changes
4. Run linting - Ensure code passes Biome checks
5. Type safety - Avoid any, create proper types

See CLAUDE.md for detailed development guidelines.

Canonical models source (URL)

The project obtains canonical model metadata from a public JSON registry. By default the adapter fetches from:

https://models.dev/models.json

You can override the source URL using the environment variable MODELS_DEV_URL — useful for an internal mirror or testing:

export MODELS_DEV_URL=https://my-mirror.example/models.json

The runtime will fetch this JSON at service initialization (and the GitHub Action periodically updates packages/effect-aisdk/config/models.reg.json from the same URL). If the fetch fails, bootstrap will fail with a structured ModelsDevMissingError so CI can detect the condition programmatically and report it.

---

License

[Your License Here]

---

Support

For questions, issues, or contributions:

• GitHub Issues: Report an issue
• Documentation: See the src/docs/ directory
• Examples: See the src/examples/ directory