# OctoAgent_Interaction

**Repository Path**: octoagent/octoagent_interaction

## Basic Information

- **Project Name**: OctoAgent_Interaction
- **Description**: 自然语言交互模块（OctoAgent_interaction）
定位：OctoAgent 系统的“五官与语言中枢”，负责连接用户与系统内核。
功能：
多模态输入解析：接收用户文字、语音或文件，通过 LLM 提取意图与关键实体。
智能意图路由：将非结构化自然语言转化为结构化指令（JSON），决定转发给哪个功能模块。
技术价值：实现“对话即操作”，赋予系统零门槛的自然语言交互能力。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# octoagent（octoagent_interaction）自然语言交互模块

#### 介绍

自然语言交互模块（octoagent_interaction）
定位：OctoAgent 系统的“五官与语言中枢”，负责连接用户与系统内核。
功能：
多模态输入解析：接收用户文字、语音或文件，通过 LLM 提取意图与关键实体。
智能意图路由：将非结构化自然语言转化为结构化指令（JSON），决定转发给哪个功能模块。
技术价值：实现“对话即操作”，赋予系统零门槛的自然语言交互能力。

✨ 核心特性
🧠 意图解析：自动识别用户指令意图（如创建模块、查询数据、执行流程）。
🧩 实体提取：精准提取关键业务实体（如部门名称、岗位列表）。
🔄 多轮对话：支持上下文状态管理，处理信息缺失时的智能追问。
🛠️ 模型无关：支持 OpenAI、Azure 以及本地部署的 LLM（如 Llama 3, Qwen）。
⚡ 异步处理：基于 Python async/await，高效处理 LLM 请求。

#### 软件架构

软件架构说明
本模块采用 Python 标准的 src 布局，结构清晰，易于扩展：

octoagent_interaction/
├── src/
│   └── octoagent_interaction/
│       ├── __init__.py       # 入口函数 (entry_point)
│       ├── main.py           # 核心业务逻辑 (InteractionModule)
│       ├── parser.py         # 意图解析器
│       └── prompts.py        # 提示词模板管理
├── tests/
│   └── test_script.py       # 单元测试
├── pyproject.toml           # 项目配置与依赖
└── README.md

核心组件说明：
InteractionModule：主类，负责初始化 LLM 客户端并执行解析任务。
IntentParser：封装与 LLM 的交互逻辑，包含 JSON 清洗和错误重试机制。
Prompts：精心设计的 System Prompt，指导 LLM 输出符合规范的 JSON。
#### 安装教程

🚀 安装教程

1. 环境要求
Python 3.10+
已安装 OctoAgent Core (主程序)
2. 安装步骤
建议在 OctoAgent 主程序环境下安装：
# 1. 克隆仓库 (或直接在项目中使用)
git clone https://gitee.com/octoagent/octoagent_interaction.git
cd octoagent_interaction

# 2. 安装模块 (推荐可编辑模式)
pip install -e .
3. 验证安装
运行测试脚本验证模块是否正常工作：
python tests/test_script.py

如果输出 测试输出: 成功，则说明安装成功。

#### 使用说明
本模块作为插件运行，不直接作为服务启动。需由 OctoAgent 主程序加载后通过 API 调用。

1. 接口调用
请求地址：POST http://localhost:8000/v1/execute

请求体：
json
{
  "module_name": "interaction",
  "task_input": {
    "user_input": "创建一个设计部，包含设计总监岗位"
  }
}

2. 返回示例
模块将返回解析后的意图和实体数据，供主程序分发给后续模块（如 organization 模块）：
json
{
  "success": true,
  "message": "意图解析成功",
  "data": {
    "intent": "CREATE_MODULE",
    "entities": {
      "module_name": "设计部",
      "positions": ["设计总监"]
    },
    "confidence": 0.95,
    "missing_slots": []
  }
}

3. 处理信息缺失
当指令信息不全时，模块会自动返回追问信息：

输入：创建一个部门
返回：
json
{
  "success": true,
  "message": "需要补充信息",
  "action": "CLARIFICATION",
  "data": {
    "clarification_question": "您想创建的模块缺少以下信息：部门名称，请补充。"
  }
}

🔧 高级配置
您可以在 main.py 中替换 MockLLMClient 为真实的 LLM 客户端（如 OpenAI）：
python

# main.py 示例
from openai import AsyncOpenAI

class OpenAIClient:
    def __init__(self):
        self.client = AsyncOpenAI(api_key="YOUR_API_KEY")

    async def call(self, messages):
        response = await self.client.chat.completions.create(
            model="gpt-4",
            messages=messages
        )
        return response.choices[0].message.content



📜 开源协议
本项目采用 Apache License 2.0 协议开源。

OctoAgent Team
2026年3月24日

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)