Skip to content

westenwang/english-assistant-network

BranchesTags

Repository files navigation

English Assistant Agent Network

A multi-agent system designed for English learning assistance, implementing scenario-based conversation, pronunciation analysis, and emotional support with分级筛选 and comprehensive language skill development.

Overview

This workspace contains everything you need to start an English learning assistant network with specialized agents. The system now supports分级筛选 (level-based filtering) from elementary to workplace English, and comprehensive training in listening, speaking, reading, and writing skills.

The network uses an event-driven architecture to coordinate multiple agents, each specializing in different aspects of English learning. The system is built on the OpenAgents framework and supports both YAML-based and Python-based agents.

Table of Contents

Features

1. 分级筛选 System (Level-based Filtering)

  • 小学级别 (Elementary): Basic vocabulary, simple sentence patterns, daily greetings
  • 初中级别 (Middle School): Basic grammar, common expressions, simple reading
  • 高中级别 (High School): Complex grammar, topic writing, listening comprehension
  • 大学级别 (College): Academic English, professional vocabulary, deep reading
  • 专升本级别 (Upgrade from College): Exam-specific training, vocabulary strengthening, question type practice
  • 职场级别 (Workplace): Business English, professional terminology, meeting communication

2. Comprehensive Language Skills Development

  • Listening Training: Provides分级 listening materials, real-time listening comprehension assessment
  • Speaking Training: ASR and pronunciation analysis, error correction and improvement suggestions
  • Reading Training: Graded reading material recommendations, vocabulary explanations and examples
  • Writing Training: Article structure guidance, grammar error detection, vocabulary enrichment suggestions

3. Event-Driven Architecture

  • Custom Events: Defined in the events directory using AsyncAPI 3.0.0 standard
  • Agent Communication: Agents communicate through well-defined events to coordinate tasks
  • Extensible Design: New agents and events can be added without disrupting existing functionality

4. Text Input Support

  • Supports pure text input mode for users without audio capabilities
  • Provides written feedback instead of voice feedback
  • Grammar and vocabulary error detection for text input

5. Specialized Support for Upgrade from College and Workplace

  • Upgrade from College Support:
    • Exam-specific question practice (cloze, reading comprehension, translation, writing)
    • Past exam simulation
    • Key grammar review
    • High-frequency vocabulary memorization
    • Learning progress tracking
  • Workplace English Support:
    • Business scenario conversations (meetings, negotiations, emails, phone calls)
    • Industry terminology learning
    • Business writing templates
    • Etiquette language training

Architecture

The system implements a multi-agent collaboration pattern where agents work together to provide comprehensive English learning assistance:

  1. User initiates an English practice session or uses Level Selector for evaluation
  2. Learning Assistant determines appropriate difficulty level
  3. Language Assistant provides reading and writing support
  4. Speech Coach analyzes pronunciation and provides feedback
  5. Analyst evaluates emotional state and learning progress
  6. Progress Tracker records learning history and generates reports
  7. Router compiles comprehensive report for the user

Multi-Agent Architecture Diagram

The following diagram illustrates how the agents interact with each other in the English Assistant Agent Network:

graph TB
    subgraph "User Interaction Layer"
        U[User Request]
    end
    
    subgraph "Coordinator Agents"
        R[Router Agent]
        LS[Level Selector Agent]
    end
    
    subgraph "Specialized Learning Agents"
        LA[Language Assistant]
        SA[Speech Coach]
        RA[Reading Assistant]
        WArit[Writing Assistant]
    end
    
    subgraph "Support Agents"
        WS[Web Searcher]
        A[Analyst]
        PT[Progress Tracker]
        LA2[Learning Assistant]
    end
    
    %% User flow
    U --> R
    U --> LS
    
    %% Coordination flow
    R --> LS
    LS --> LA2
    R --> LA2
    
    %% Reading workflow
    R --> RA
    RA --> WS
    RA --> A
    RA --> PT
    
    %% Writing workflow
    R --> WArit
    WArit --> A
    A --> PT
    
    %% Speaking workflow
    R --> SA
    SA --> A
    SA --> PT
    
    %% Language assistant workflow
    R --> LA
    LA --> A
    LA --> PT
    
    %% Event flows
    PT -.-> R
    A -.-> PT
    
    %% Styling
    classDef coordinator fill:#e1f5fe
    classDef specialized fill:#f3e5f5
    classDef support fill:#e8f5e8
    
    class R,LS coordinator
    class LA,SA,RA,WArit specialized
    class WS,A,PT,LA2 support
Loading

Agent Roles

The system includes specialized agents for different aspects of English learning:

Agent Type Description Primary Events
router YAML Coordinates English practice sessions and delegates tasks task.delegate, task.complete
web-searcher YAML Provides English learning resources and pronunciation analysis reading.request, reading.completed
analyst YAML Analyzes emotional state and tracks learning progress writing.reviewed, reading.completed
level_selector YAML Evaluates English level and recommends appropriate difficulty level.select, level.determined
language_assistant YAML Provides integrated reading and writing support reading.request, writing.submitted
learning_assistant YAML Manages learning progression and tracks user levels evaluate.level, level.progress
progress_tracker YAML Tracks user progress and provides personalized reports writing.analyzed, reading.analyzed
reading_assistant YAML Provides graded reading materials and comprehension exercises reading.request, reading.completed
speech_coach YAML Pronunciation and ASR specialist for speech analysis audio.received, text.received
writing_assistant YAML Offers writing guidance and feedback writing.submitted, writing.reviewed

Quick Start

Prerequisites

  • OpenAgents CLI installed
  • Python 3.8+ (for Python-based agents)
  • OpenAI API key (for LLM-powered agents)

1. Start the Network

openagents network start .

2. Access Studio

Open your browser to:

3. Launch Agents

Choose one of the agents:

Router Agent (Scene Coordinator):

openagents agent start agents/router.yaml

Web Searcher Agent (Speech Coach):

openagents agent start agents/web_searcher.yaml

Language Assistant (Reading and Writing Support):

openagents agent start agents/language_assistant.yaml

All-in-One Launch:

# Level Selector - evaluates user's English level and recommends appropriate difficulty
openagents agent start agents/level_selector.yaml

# Speech Coach - provides ASR and pronunciation analysis
openagents agent start agents/speech_coach.yaml

# Reading Assistant - provides reading materials and comprehension exercises
openagents agent start agents/reading_assistant.yaml

# Writing Assistant - offers writing guidance and feedback
openagents agent start agents/writing_assistant.yaml

# Progress Tracker - tracks user progress and provides personalized reports
openagents agent start agents/progress_tracker.yaml

Note: LLM-powered agents require an OpenAI API key.

Network Configuration

The system provides two network configurations:

1. Full Network (network.yaml)

For comprehensive English learning with all features:

Required Agents:

Optional Agents:

2. Simplified Network (network_simple.yaml)

For reduced token consumption and faster response:

Required Agents:

To start the simplified network:

# Start the simplified network
openagents network start network_simple.yaml

# Launch minimal agents for core functionality
openagents agent start agents/router.yaml
openagents agent start agents/language_assistant.yaml
openagents agent start agents/learning_assistant.yaml

Configuration

Agent Groups & Authentication

This network has several agent groups configured:

Group Password Description
guest (none) Default group, no password required
admin admin Full permissions to all features
coordinators coordinators For router/coordinator agents
researchers researchers For worker/research agents

Logging in as Admin

To access admin features in Studio:

  1. Open http://localhost:8700/studio/
  2. Click on the group selector (or login)
  3. Select group: admin
  4. Enter password: admin

Admin Features

As an admin, you have full permissions including:

  • Access to all channels and messaging features
  • Create, edit, and delete forum topics
  • Manage wiki pages and approve edit proposals

Event System

The system uses a comprehensive event-driven architecture to coordinate agents. Key event categories include:

  • Common Events: Basic communication between agents (message.received, task.complete)
  • Level Events: Managing user English proficiency (level.select, level.determined)
  • Reading Events: Coordinating reading exercises (reading.request, reading.completed)
  • Writing Events: Managing writing tasks and feedback (writing.submitted, writing.reviewed)
  • Speech Events: Handling audio and text input (audio.received, text.received)
  • Practice Events: Tracking practice completion (practice.completed)

For a complete list of events and their definitions, see the events directory and the custom_events_summary.md documentation.

Usage Examples

This multi-agent system operates through an event-driven architecture. To interact with the system, you need to trigger appropriate events rather than sending direct chat messages. Here are some examples:

1. Request Reading Material

Event Trigger: Send a message that will trigger the reading.request event

  • Input: "请给我一篇中级难度的阅读文章"
  • Flow: Router → Language Assistant → Analyst
  • Output: You'll receive a reading passage with comprehension questions tailored to your level

2. Submit Writing for Feedback

Event Trigger: Send a message that will trigger the writing.submitted event

  • Input: "我想练习写作" followed by your writing piece
  • Flow: Router → Language Assistant → Analyst
  • Output: Detailed feedback on structure, grammar, vocabulary, and overall quality

3. Request Level Assessment

Event Trigger: Send a message that will trigger the evaluate.level event

  • Input: "我想测试我的英语水平"
  • Flow: Router → Learning Assistant
  • Output: Assessment of your current English level with recommendations for suitable learning materials

4. Practice Speaking (if audio support is available)

Event Trigger: Audio input that will trigger the audio.received event

  • Input: Speak into microphone
  • Flow: Router → Speech Coach → Analyst
  • Output: Pronunciation feedback and improvement suggestions

Important Notes:

  1. Event-Based Communication: Agents respond to specific events, not casual conversation. Use the examples above to trigger the desired functionality.

  2. System Initialization: After launching agents, wait for the project.notification.started event. Each agent typically sends a welcome message with its capabilities when the project starts.

  3. Response Delays: Some tasks (like searching for resources or detailed analysis) may take a few seconds to complete.

  4. Multi-Agent Collaboration: Complex tasks involve multiple agents working together, so responses may come in stages as different agents contribute to the final output.

Tools

The agents include specialized tools:

  • search_english_learning: Search for English learning resources on Chinese learning sites
  • fetch_english_article: Extract content from English learning webpages
  • search_english_forum: Find discussions in Chinese English learning communities
  • analyze_pronunciation: Evaluate user's pronunciation accuracy
  • transcribe_audio: Convert audio to text using Whisper API
  • check_pronunciation: Analyze pronunciation accuracy against reference text
  • find_errors: Identify grammar, vocabulary, and pronunciation errors
  • process_text_input: Process user's text input directly without audio processing

Contributing

To contribute to this project:

  1. Add new agents to the agents directory
  2. Define new events in the events directory
  3. Add tools in the tools directory
  4. Update documentation in the docs directory

About

一个专为英语学习辅助设计的多代理系统，实现了基于场景的对话、发音分析和情感支持，具有分级筛选功能和综合语言技能发展。

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages