DOCSEARCHbyAlgolia
Submit Docs

Nekro Agent

repository·main·Indexed 21 days ago

https://github.com/kromiose/nekro-agent

A highly extensible AI agent execution platform for intelligent chat and task automation. Version 2.3.3 features a secure code execution sandbox, a robust plugin system, and a multi-platform adapter architecture. Supported adapters include Bilibili Live (real-time danmaku and event processing), Discord (community operations and multi-server management), Email (multi-account IMAP/SMTP/OAuth integration), and Feishu (team collaboration and workspace integration).

Tokens
80.3K
Snippets
238
Records
368
Agent score
77%

What's inside nekro-agent

  1. Overview of the OneBot V11 Adapter

    main
    The OneBot V11 adapter is designed to integrate Nekro Agent into QQ group chats and private messages. It is the most versatile and easiest adapter to use if your primary interaction platform is QQ. It is ideal for scenarios requiring high-frequency interaction in Chinese-speaking environments, such as group assistants, personal companions, or automated notification systems.

  3. Overview of the Discord Adapter

    main

    The Discord Adapter is designed for deploying long-term online Agents within Discord communities. It is optimized for community operations, interest groups, and multi-server management. It allows an Agent to handle tasks such as Q&A, interaction, information distribution, and channel management assistance.

    Key Capabilities:

    • Receive and reply to messages in both server channels and Direct Messages (DMs).
    • Support for common interactions including images, files, message replies, and @mentions.
    • Ability to add reactions to messages to enhance real-time interaction.

    Ideal Use Cases:

    • Community Operations: Answering questions, guiding users, supplementing announcements, and maintaining order.
    • Interest Groups: Providing documentation, command entry points, and long-term interactive companionship.
    • Multi-Server Management: Reusing the same Agent capabilities across multiple Discord servers.
    • Private Support: Providing one-on-one supplemental communication via DMs.

  4. Overview of the Nekro Agent Sandbox Environment

    main
    The Nekro Agent Sandbox is a specialized execution environment designed for the Nekro Agent. It provides a pre-configured suite of tools for data processing, mathematical computation, document manipulation, and visualization, allowing the agent to perform complex analytical tasks within a controlled setting.

  5. Overview of the Email Adapter

    main

    The Email Adapter integrates email receiving, sending, synchronization, attachment handling, and content retrieval into Nekro Agent. It functions in two primary modes:

    1. New Mail Entry: Converts incoming emails into messages within independent chat sessions.
    2. Email Workbench: A centralized management interface for multiple email accounts, allowing users to view history, forward attachments, and troubleshoot receiving pipelines.

    Core Capabilities:

    • Multi-account Management: Configure individual settings for each account, including enabled status, receiving/sending toggles, and default sender identity.
    • Provider Support: Built-in support for QQ, 163, Gmail, and Outlook, plus support for custom IMAP/SMTP configurations.
    • OAuth Integration: Official OAuth login for Gmail and Outlook/Microsoft 365 to avoid manual password/app-password management.
    • Automated Polling: Periodically fetches inbox mail. Supports processing only unread emails and marking them as read after processing.
    • Sessionization: Each email account maps to a unique chat channel where email body, sender, subject, and attachments are injected into the Agent's context.
    • Tools & Utilities: Includes tools for summarizing recent emails, querying specific email content/attachments, and forwarding attachments to other chat channels.

  6. Use the WeChat OpenILink Adapter

    main

    The WeChat OpenILink adapter is a WeChat integration based on wechatbot-sdk. It provides a bridge for Nekro Agent to interact with WeChat via the iLink API.

    Core Capabilities (MVP)

    • Message Handling: Receives WeChat text messages and sends AI-generated text replies.
    • Media Support: Sends images, files, and voice messages.
    • Session Mapping: Supports basic session mapping for both group chats and private chats.

    Authentication and Login

    Authentication is performed using the QR code login capability from wechatbot-sdk.

    • Login Process: During startup, the adapter will output a QR code login URL to the console (it does not print an ASCII QR code).
    • Persistence: Once the scan is successful, credentials are saved to the path specified by CRED_PATH. Subsequent restarts will reuse these credentials automatically.

  7. Use the Feishu Adapter for team collaboration

    main

    The Feishu Adapter allows you to integrate Nekro Agent into the Feishu workspace. It enables the Agent to act as a participant in team chats, handling tasks such as answering questions, sending notifications, and assisting with collaboration. It is ideal for teams that use Feishu as their primary communication tool, providing a high-frequency entry point for AI interaction.

    Common Use Cases

    • Team Q&A: Answering questions regarding documents, policies, processes, or knowledge bases.
    • Collaboration Assistance: Supplementing discussions with materials, generating explanations, or following up on tasks.
    • Daily Notifications: Pushing system statuses, daily reports, or reminders to group chats or private messages.
    • Lightweight Office Assistant: Providing direct help to team members within the chat window.

  8. Use the WeChatPad adapter for WeChat integration

    main

    The WeChatPad adapter allows you to integrate Nekro Agents into WeChat private chats and group chats. It is designed for handling daily communication, reminders, notifications, and lightweight automated replies within a familiar social environment.

    Use Cases

    • Private Chat Assistant: Personal chat assistant, information organizer, or reminder entry point.
    • Group Chat Support: Answering questions, providing supplementary materials, or light interaction in small groups.
    • Business Outreach: Sending notifications to fixed targets, confirming messages, or synchronizing results.
    • Personal Workflow: Integrating WeChat messages into a unified session management system.

    Capabilities

    • Receive and reply to messages in both private and group chats.
    • Process common chat content such as text and images.
    • Integrate WeChat conversations into a unified Agent workflow.

  9. Understand the WeChat OpenILink instance lifecycle and states

    main

    Instances follow a state machine for their main lifecycle and the QR binding process.

    Main Lifecycle States:

    • pending: Created but not yet bound.
    • binding: QR code generation in progress.
    • online: Connected and capable of sending/receiving messages.
    • offline: Stopped or connection lost.
    • renewing: Temporary state during session renewal.
    • session_expired: Credentials expired; requires re-binding.
    • error: Runtime error (check last_error).
    • deleted: Soft-deleted (enabled=False).

    QR Binding Sub-states: Binding is successful only when the state reaches session_persisted and the main lifecycle moves to online. The sequence is: qr_generated → qr_scanned → login_confirmed → session_persisted.

  10. Use the SSE Adapter for custom client integration

    main

    The SSE (Server-Sent Events) Adapter is designed to integrate custom clients, web applications, or lightweight external programs into Nekro Agent. Unlike social platform adapters, the SSE adapter provides high flexibility for embedding Agent capabilities directly into your own interfaces, business processes, or internal tools.

    Ideal Use Cases

    • Custom Web Chat Interfaces: Building your own UI for interacting with the Agent.
    • Internal Business Systems: Bridging Agent capabilities into existing enterprise workflows.
    • Lightweight Clients: Creating console tools, experimental terminals, or lightweight external programs.
    • Multi-client Access: Allowing multiple external programs to access the same Agent capabilities simultaneously.

    Key Capabilities

    • Full Session Experience: Supports passing text, images, files, and user information to maintain context.
    • Message Control: Allows control over message acknowledgments, timeouts, and file transfer scopes.
    • Concurrent Access: Enables multiple external clients to send and receive messages at the same time.

  12. Understand the session renewal policy and failure recovery

    main

    The adapter automatically renews session credentials to prevent expiration.

    Default Behavior:

    • Triggers renewal DEFAULT_RENEW_BEFORE_MINUTES (default 60) before expiry.
    • Renewal can be overridden per instance via PATCH /instances/{key}/renew-policy.

    Renewal Process:

    1. Background task waits for next_renew_at.
    2. State changes to renewing and renew_once() is called.
    3. On success: Credentials and sync state are updated; state returns to online or offline.

    Failure Recovery:

    • If credentials expire: Main state becomes session_expired.
    • Other errors: Main state becomes error.
    • Retry Mechanism: The background task does not exit on failure; it uses exponential backoff (starting at 60s, max 30min) to retry until success or the instance is stopped.