Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/danielgerlag/daemon


https://github.com/danielgerlag/daemon

Last synced: 8 months ago
JSON representation

Awesome Lists containing this project

README 

          
# AI Agent Daemon



A powerful CLI tool for running AI agents in the background with support for MCP (Model Context Protocol) tools, scheduled jobs, inter-agent collaboration, and advanced workflow patterns.



## Features



- **Background AI Agents**: Run AI agents as daemons with Azure OpenAI integration

- **Advanced Workflow Patterns**: Support for Reason+Act, Plan+Solve, Reflection, Reflexion, LLM-Compiler, ReWOO, STORM, and Reflection+Refinement patterns

- **MCP Tool Integration**: Support for both stdio command and HTTP-based MCP servers

- **Notification Handling**: React to notifications from MCP tools with custom workflow executions

- **Cron Job Scheduling**: Run workflows on schedule or at startup

- **Conversation API**: Optional HTTP endpoint for human or agent interaction

- **Agent Collaboration**: Communicate with other agent instances using A2A (Agent-to-Agent) protocol

- **Interactive Web UI**: Monitor agent activity with a modern web interface

- **History Tracking**: Persistent storage of conversations, tool invocations, and collaborations



## Installation



```bash

npm install

npm run build

```



For global installation:

```bash

npm install -g .

```



## Configuration



Create a YAML configuration file for your agent. See the `samples/` directory for detailed examples.



### Basic Configuration



```yaml

id: my-agent



# Named model configurations

models:

  main-model:

    kind: azure-openai

    endpoint: ${AZURE_OPENAI_ENDPOINT}

    apiKey: ${AZURE_OPENAI_API_KEY}

    deployment: ${AZURE_OPENAI_DEPLOYMENT}

    temperature: 0.7

    maxTokens: 1500



defaultModel: main-model



# Workflow configuration with pattern selection

workflow:

  kind: Reason+Act  # Options: Reason+Act, Plan+Solve, Reflection, Reflexion, LLM-Compiler, ReWOO, STORM, Reflection+Refinement

  model: main-model

  prompt: |

    Initialize the agent and perform startup tasks



# MCP servers (tools)

mcpServers:

  - name: my-tool

    kind: command

    command: node

    args: ["path/to/mcp-server.js"]

    on:

      event_type: 

        workflow:

          kind: Reason+Act

          model: main-model

          prompt: "Handle this notification: {{message}}"



# Cron jobs with workflow execution

cron:

  - job: periodic-task

    schedule: "0 */6 * * *"

    workflow:

      kind: Plan+Solve

      model: main-model

      prompt: "Run periodic maintenance tasks"

      maxPlanSteps: 5



endpoint: 127.0.0.1:9000



# A2A (Agent-to-Agent) collaboration

collaborators:

  - id: other-agent

    url: http://localhost:9001

```



### Environment Variables



Copy `.env.example` to `.env` and fill in your Azure OpenAI credentials:



```bash

cp .env.example .env

```



## Usage



### Basic Usage



```bash

# Run agent with configuration file

daemon config.yaml



# Run with verbose logging

daemon config.yaml --verbose



# For development (if not globally installed)

node dist/cli.js config.yaml --verbose

```



### Global Installation



```bash

npm install -g .

daemon config.yaml

```



## API Endpoints



If you configure an endpoint, the agent exposes these HTTP endpoints:



- `POST /api/conversation` - Send messages to the agent

- `GET /api/status` - Get agent status

- `GET /api/config` - Get agent configuration

- `GET /api/tools` - Get available tools

- `GET /api/mcp-servers` - Get MCP server information

- `GET /api/history` - Get conversation and activity history

- `GET /api/cron-jobs` - Get cron job status

- `GET /api/health` - Health check

- `GET /api/logs` - Get agent logs

- `GET /api/tool-invocations` - Get tool invocation history

- `GET /api/tool-invocations/:toolName` - Get history for specific tool

- `GET /api/tool-streams` - Get MCP tool stream data

- `GET /api/websocket` - WebSocket endpoint information

- `WS /hub` - WebSocket endpoint for real-time events



### Conversation API



```bash

curl -X POST http://localhost:9000/api/conversation \\

  -H "Content-Type: application/json" \\

  -d '{

    "type": "User",

    "clientId": "user-123",

    "message": "Hello, agent!"

  }'

```



## MCP Server Integration



The daemon supports both command-line and HTTP-based MCP servers:



### Command-based MCP Servers



```yaml

mcpServers:

  - name: fs-watcher

    kind: command

    command: npx

    args: ["@example/file-watcher-mcp"]

    env:

      NODE_ENV: production

    on:

      file_change: 

        workflow:

          kind: Reflection

          model: main-model

          prompt: "File {{filename}} was modified at {{path}}"

          reflectionInterval: 3

```



### HTTP-based MCP Servers



```yaml

mcpServers:

  - name: github-api

    kind: http

    url: https://api.githubcopilot.com/mcp/

    headers:

      Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"

```



### MCP Server Configuration Options



Each MCP server supports these configuration parameters:



- **`on`**: Notification handlers that execute workflows when the server sends notifications

- **`env`**: Environment variables for command-based servers

- **`headers`**: HTTP headers for HTTP-based servers



The agent automatically discovers tool schemas from MCP servers and includes them in the system prompt, so the LLM knows the exact parameter names and types required by each tool.



Example workflow execution with tools:

```json

{"tool": "file-watcher", "method": "subscribe_file_watch", "arguments": {"directory": "/path", "watchId": "my-watch", "recursive": true}}

```



## Workflow Patterns



The daemon supports multiple advanced workflow patterns:



### Reason+Act

Simple reasoning and action execution pattern.



```yaml

workflow:

  kind: Reason+Act

  model: main-model

  prompt: "Analyze and take action on the given task"

```



### Plan+Solve

Systematic planning followed by step-by-step execution.



```yaml

workflow:

  kind: Plan+Solve

  model: main-model

  prompt: "Create a plan and solve this complex problem"

  maxPlanSteps: 8

  planningPrompt: "Create a detailed plan for: ${TASK}"

```



### Reflection

Periodic self-reflection during task execution.



```yaml

workflow:

  kind: Reflection

  model: main-model

  prompt: "Execute the task with periodic reflection"

  reflectionInterval: 3

  reflectionModel: reflection-model

  reflectionPrompt: "Reflect on the progress and adjust if needed"

```



### Reflexion

Self-correction through reflexive analysis.



```yaml

workflow:

  kind: Reflexion

  model: main-model

  prompt: "Execute with self-correction capabilities"

  maxReflexions: 5

  reflexionPrompt: "Analyze errors and provide corrections"

```



### LLM-Compiler

Multi-step compilation and optimization of responses.



```yaml

workflow:

  kind: LLM-Compiler

  model: main-model

  prompt: "Compile and optimize the solution"

  maxCompilationSteps: 3

  enableRecompilation: true

```



### ReWOO

Reasoning Without Observation pattern for complex problem solving.



```yaml

workflow:

  kind: ReWOO

  model: main-model

  prompt: "Solve using reasoning without observation"

  maxReasoningSteps: 5

```



### STORM

Synthesis of Topic Outline through Retrieval and Multi-perspective question asking.



```yaml

workflow:

  kind: STORM

  model: main-model

  prompt: "Research and synthesize comprehensive information"

  maxPerspectives: 4

  researchDepth: 3

```



## Agent Collaboration (A2A Protocol)



Agents can communicate with each other using the standardized Agent-to-Agent (A2A) protocol:



```yaml

collaborators:

  - id: agent-2

    url: http://localhost:9001

```



The system automatically:

- Converts legacy collaboration to A2A protocol

- Generates agent cards at `/.well-known/agent-card.json`

- Enables standardized message exchange

- Supports task delegation and coordination



The agent can collaborate by responding with JSON:



```json

{"collaborate": "agent-2", "message": "Please help with this task"}

```



### A2A Features

- **Agent Discovery**: Automatic capability discovery through agent cards

- **Standardized Messaging**: Consistent message format across all agents

- **Task Management**: Built-in support for complex, multi-agent tasks

- **Error Handling**: Standardized error responses and retry mechanisms



See `examples/a2a-collaboration-example.md` for detailed A2A setup examples.



## Cron Jobs



Schedule workflows to run automatically:



```yaml

cron:

  - job: daily-summary

    schedule: "0 9 * * *"  # Daily at 9 AM

    workflow:

      kind: Plan+Solve

      model: main-model

      prompt: "Generate a daily summary report"

      maxPlanSteps: 5

    

  - job: startup-task

    on-startup: true

    schedule: "0 */6 * * *"  # Every 6 hours

    workflow:

      kind: Reflection

      model: main-model

      prompt: "Perform maintenance checks"

      reflectionInterval: 2

```



## History and Monitoring



All agent activity is automatically tracked:



- **Conversations**: User/agent message exchanges

- **Tool Invocations**: MCP server calls and results

- **Collaborations**: Inter-agent communications via A2A protocol

- **Workflow Executions**: Detailed execution logs for all workflow patterns

- **Cron Jobs**: Scheduled task execution history



History is stored in `~/.ai-agent-daemon/{agent-id}-history.json`



## Web UI



The daemon includes a modern web interface for monitoring agent activity:



- **Real-time Dashboard**: Live agent status and activity

- **Conversation History**: Browse and search conversation logs

- **Tool Monitoring**: Track MCP server invocations and performance

- **Collaboration Tracking**: Monitor A2A protocol communications

- **Workflow Visualization**: View workflow execution patterns

- **Cron Job Management**: Monitor scheduled tasks



Access the web UI at `http://localhost:{port}` when an endpoint is configured.



## Examples



See the `samples/` directory for complete configuration examples including:



- **Basic Agents**: Simple Reason+Act and Plan+Solve configurations

- **Workflow Patterns**: Examples for all supported workflow types

- **GitHub Integration**: Issue monitoring and management with collaboration

- **Financial Trading**: Complex reflection-based trading analysis

- **File System Monitoring**: Notification-driven file watching

- **Multi-Agent Collaboration**: A2A protocol examples



Also see `examples/a2a-collaboration-example.md` for detailed multi-agent setup guides.



## Development



```bash

# Install dependencies

npm install



# Development mode with auto-reload (backend only)

npm run dev config.yaml



# Build for production (both backend and frontend)

npm run build



# Build only backend

npm run build:backend



# Build only frontend

npm run build:frontend



# Development mode with frontend hot reload

npm run dev:frontend



# Run built version

npm start config.yaml



# Run tests

npm test

```



## License



MIT