FinchBot — A Lightweight, Flexible, Self-Extending AI Agent Framework

<img src="docs/image/image.png" alt="FinchBot Logo" width="600"> Built on LangChain v1.2 & LangGraph v1.0 with persistent memory, dynamic prompts, autonomous capability extension 🌐 Language: <a href="README.md">English</a> | <a href="README_CN.md">中文</a> <img src="https://img.shields.io/badge/Gitee-Gitee Officially_Recommended-red?logo=gitee&logoColor=white" alt="Gitee Recommended"> <a href="https://atomgit.com/xt765/FinchBot"> <img src="https://img.shields.io/badge/AtomGit-G--Star_Incubation_Project-silver?logo=git&logoColor=white" alt="AtomGit"> </a> <a href="https://blog.csdn.net/Yunyi_Chi"> <img src="https://img.shields.io/badge/CSDN-玄同765-orange?style=flat-square&logo=csdn" alt="CSDN Blog"> </a> <a href="https://github.com/xt765/FinchBot"> <img src="https://img.shields.io/badge/GitHub-FinchBot-black?style=flat-square&logo=github" alt="GitHub"> </a> <a href="https://gitee.com/xt765/FinchBot"> <img src="https://img.shields.io/badge/Gitee-FinchBot-red?style=flat-square&logo=gitee" alt="Gitee"> </a> <a href="https://gitcode.com/xt765/FinchBot"> <img src="https://img.shields.io/badge/GitCode-FinchBot-silver?style=flat-square&logo=gitcode" alt="GitCode"> </a> <img src="https://img.shields.io/badge/Python-3.13-blue?style=flat-square&logo=python" alt="Python"> <img src="https://img.shields.io/badge/Ruff-Formatter-orange?style=flat-square&logo=ruff" alt="Ruff"> <img src="https://img.shields.io/badge/Basedpyright-TypeCheck-purple?style=flat-square&logo=python" alt="Basedpyright"> <img src="https://img.shields.io/badge/Docker-Containerized-blue?style=flat-square&logo=docker" alt="Docker"> <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square&logo=open-source-initiative" alt="License">

FinchBot is an AI Agent framework that empowers agents with true autonomy, built on LangChain v1.2 and LangGraph v1.0. With fully async architecture, agents gain the ability to self-decide, self-extend, and self-evolve:

Capability Self-Extension — Agent can use built-in tools to configure MCP and create skills when hitting capability boundaries
Task Self-Scheduling — Agent can self-set background tasks and scheduled execution without blocking conversations
Memory Self-Management — Agent can self-remember, self-retrieve, and self-forget with Agentic RAG + Weighted RRF hybrid retrieval
Behavior Self-Evolution — Both Agent and users can self-modify prompts, continuously iterating and optimizing behavior

The Capability Boundary Problem

| What User Asks | Traditional AI Response | FinchBot Response | |:---|:---|:---| | "Analyze this database" | "I don't have database tools" | Self-configures SQLite MCP, then analyzes | | "Learn to do X" | "Wait for developer to add feature" | Self-creates skill via skill-creator | | "Monitor this for 24 hours" | "I can only respond when you ask" | Creates scheduled task, monitors autonomously | | "Process this large file" | Blocks conversation, user waits | Runs in background, user continues | | "Remember my preferences" | "I'll forget next conversation" | Persistent memory with Agentic RAG + Weighted RRF | | "Adjust your behavior" | "Prompts are fixed" | Dynamically modifies prompts, hot reload |

System Architecture

Core Philosophy: FinchBot agents don't just respond — they self-execute, self-plan, and self-extend.

Autonomy Pyramid

flowchart TB
    subgraph L4["Extension Layer - Self-Extend Capabilities"]
        E1["MCP Auto-Config"] ~~~ E2["Skill Creation"] ~~~ E3["Dynamic Loading"]
    end

    subgraph L3["Planning Layer - Self-Create Plans"]
        P1["Cron Tasks"] ~~~ P2["Heartbeat Monitor"] ~~~ P3["Auto Trigger"]
    end

    subgraph L2["Execution Layer - Self-Execute Tasks"]
        X1["Background Tasks"] ~~~ X2["Async Processing"] ~~~ X3["Non-Blocking"]
    end

    subgraph L1["Response Layer - Respond to Requests"]
        R1["Dialog System"] ~~~ R2["Tool Calls"] ~~~ R3["Context Memory"]
    end

    L4 --> L3 --> L2 --> L1

    style L1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    style L2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    style L3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    style L4 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17

| Layer | Capability | Implementation | User Value | |:---:|:---|:---|:---| | Response Layer | Respond to user requests | Dialog system + Tool calls | Basic interaction | | Execution Layer | Self-execute tasks | Background task system | Non-blocking dialog | | Planning Layer | Self-create plans | Scheduled tasks + Heartbeat | Automated execution | | Extension Layer | Self-extend capabilities | MCP config + Skill creation | Infinite extension |

Overall Architecture

flowchart TB
    classDef input fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17;
    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef task fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
    classDef infra fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef service fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#b71c1c;

    subgraph Input [Input Layer]
        direction LR
        CLI[CLI Interface<br/>Rich UI]:::input
        LB[LangBot<br/>12+ Platforms]:::input
        Webhook[Webhook<br/>FastAPI]:::input
    end

    subgraph Core [Core Layer - Agent Decision Engine]
        direction TB
        Agent[LangGraph Agent<br/>State Management · Loop Control]:::core
        subgraph CoreModules [Core Components]
            direction LR
            Context[ContextBuilder<br/>Context Building]:::core
            Streaming[ProgressReporter<br/>Streaming Output]:::core
        end
    end

    subgraph Capabilities [Capability Layer - Three-Tier Extension]
        direction LR
        BuiltIn[Built-in Tools<br/>19 Ready-to-Use]:::core
        MCP[MCP Extension<br/>Dynamic Config]:::core
        Skills[Skill System<br/>Self-Create]:::core
    end

    subgraph Task [Task Layer - Three-Tier Scheduling]
        direction LR
        BG[Background Tasks<br/>Async Execution]:::task
        Cron[Scheduled Tasks<br/>at/every/cron]:::task
        Heart[Heartbeat Monitor<br/>Self-Wakeup]:::task
    end

    subgraph Service [Service Layer - Unified Management]
        SM[ServiceManager<br/>Coordinate Services]:::service
    end

    subgraph Memory [Memory Layer - Dual Storage]
        direction LR
        SQLite[(SQLite<br/>Structured Storage)]:::infra
        Vector[(VectorStore<br/>Vector Retrie)]:::infra
    end

    subgraph LLM [Model Layer - Multi-Provider]
        direction LR
        OpenAI[OpenAI<br/>GPT-4o]:::infra
        Anthropic[Anthropic<br/>Claude]:::infra
        DeepSeek[DeepSeek<br/>Domestic]:::infra
    end

    CLI --> Agent
    LB <--> Webhook
    Webhook --> Agent

    Agent --> Context
    Agent --> Streaming
    Agent --> Capabilities
    Agent --> Task
    Agent <--> Memory
    Agent --> LLM

    Task --> Service
    Service --> SM

    Context --> Memory
    Memory --> SQLite
    Memory --> Vector

Data Flow

sequenceDiagram
    autonumber
    participant U as User
    participant C as Channel
    participant B as MessageBus
    participant F as AgentFactory
    participant A as Agent
    participant M as MemoryManager
    participant T as Tools
    participant L as LLM

    U->>C: Send Message
    C->>B: InboundMessage
    B->>F: Get/Create Agent
    F->>A: Return Compiled Agent
  
    Note over A: Build Context
    A->>M: Recall Relevant Memories
    M-->>A: Return Context
  
    A->>L: Send Request
    L-->>A: Stream Response
  
    alt Tool Call Needed
        A->>T: Execute Tool
        T-->>A: Return Result
        A->>L: Continue with Result
        L-->>A: Final Response
    end
  
    A->>M: Store New Memories
    A->>B: OutboundMessage
    B->>C: Route to Channel
    C->>U: Display Response

Safety Mechanisms

Agent autonomy doesn't mean agent anarchy. FinchBot implements multiple safety layers:

| Safety Mechanism | Status | What It Does | |:---|:---:|:---| | Path Restrictions | ✅ Implemented | File operations limited to workspace directory | | Shell Command Blacklist | ✅ Implemented | Blocks dangerous commands like rm -rf, format, shutdown | | Tool Registration | ✅ Implemented | Only registered tools can be executed |

Philosophy: Give agents the freedom to solve problems, but within well-defined boundaries.

Core Components

1. Capability Self-Extension: Built-in Tools + MCP Config + Skill Creation

FinchBot provides a three-layer capability extension mechanism, allowing agents to self-extend when hitting capability boundaries.

Three-Layer Extension Mechanism

flowchart LR
    classDef layer1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef layer2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef layer3 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17;

    L1[Layer 1<br/>Built-in Tools<br/>Ready to Use]:::layer1 --> L2[Layer 2<br/>MCP Config<br/>Agent Self-Config]:::layer2 --> L3[Layer 3<br/>Skill Creation<br/>Agent Self-Create]:::layer3

| Layer | Method | Autonomy | Description | |:---:|:---|:---:|:---| | Layer 1 | Built-in Tools | Ready to use | 19 built-in tools, no configuration needed | | Layer 2 | MCP Config | Agent self-config | Dynamically add external capabilities via configure_mcp | | Layer 3 | Skill Creation | Agent self-create | Create new skills via skill-creator |

Built-in Tools

| Category | Tool | Function |

FinchBot

Install / Use

README