mcp-ai-agent-sdk 1.0.0

AI Agent Python SDK - 让任何后台系统快速接入 AI Agent 能力

AI Agent Python SDK

让任何后台系统快速接入 AI 对话能力。

安装

pip install ai-agent-sdk

快速开始

from ai_agent_sdk import AIAgentClient

client = AIAgentClient(
    api_key="your-deepseek-api-key",
    db_config={
        "host": "localhost",
        "database": "mydb",
        "user": "root",
        "password": "xxx"
    }
)

# 对话
result = client.ask_and_execute("查询所有学生")
print(result["message"])  # AI 回复
print(result["data"])     # 查询结果

# 或启动 HTTP 服务
client.run_server(port=8000)

Docker 部署

Java/JavaScript 等其他语言可以通过 Docker 部署 Python SDK 服务：

# 1. 复制环境变量配置
cp .env.example .env
# 编辑 .env 填入你的配置

# 2. 启动服务
docker-compose up -d

# 服务启动后，其他语言通过 HTTP 调用
# POST http://localhost:8000/api/chat
# POST http://localhost:8000/api/chat/stream

环境变量

变量	说明	默认值
API_KEY	DeepSeek API Key	-
DB_HOST	数据库地址	localhost
DB_PORT	数据库端口	3306
DB_USER	数据库用户	root
DB_PASSWORD	数据库密码	-
DB_NAME	数据库名	-

功能特性

• ✅ 自然语言操作 - 用中文描述需求，AI 理解并生成操作
• ✅ 任何语言后台 - Java/PHP/Go/Node.js 等任何后台都能接入
• ✅ 简单易用 - 3 步即可接入
• ✅ 安全可靠 - 操作需确认后才执行

API 文档

初始化

from ai_agent_sdk import AIAgentClient

client = AIAgentClient(
    api_key="your_api_key",           # 必填，从平台获取
    base_url="https://wangyunge.top", # 可选，默认官方地址
    timeout=30                         # 可选，请求超时时间
)

注册 Schema

告诉 AI 你的后台系统有哪些实体：

client.register_schema(
    api_base_url="http://my-shop.com/api",
    entities=[
        {
            "name": "order",
            "description": "订单",
            "fields": [
                {"name": "id", "type": "number"},
                {"name": "customer", "type": "string"},
                {"name": "amount", "type": "number"},
                {"name": "status", "type": "string"}
            ],
            "operations": ["list", "get", "create", "update", "delete"]
        },
        {
            "name": "product",
            "description": "商品",
            "fields": [
                {"name": "id", "type": "number"},
                {"name": "name", "type": "string"},
                {"name": "price", "type": "number"}
            ]
        }
    ]
)

自然语言对话

# 发送指令
result = client.chat("查询所有订单")

print(result['message'])      # AI 回复
print(result['actions'])      # 建议的操作
print(result['conversation_id'])  # 对话 ID

# 简化版，只返回文本
answer = client.ask("查询所有订单")
print(answer)

执行操作

# 获取 AI 建议的操作
result = client.chat("查询所有订单")

# 确认后执行
if result['actions']:
    action_id = result['actions'][0]['id']
    exec_result = client.execute(action_id)
    print(exec_result)

多轮对话

# 第一轮
result1 = client.chat("查询订单")

# 第二轮（自动使用同一对话）
result2 = client.chat("只要今天的")

# 开始新对话
client.new_conversation()
result3 = client.chat("查询商品")

获取对话历史

history = client.get_conversation()
for msg in history['messages']:
    print(f"{msg['role']}: {msg['content']}")

异常处理

from ai_agent_sdk import (
    AIAgentClient,
    AIAgentError,
    AuthenticationError,
    RateLimitError
)

try:
    client = AIAgentClient("your_api_key")
    client.register_schema(...)
    result = client.chat("查询订单")
except AuthenticationError:
    print("API Key 无效")
except RateLimitError:
    print("请求频率超限")
except AIAgentError as e:
    print(f"错误: {e}")

使用场景

1. 后台管理系统

# 在你的 Flask/Django 后台中添加 AI 对话功能
@app.route('/api/ai/chat', methods=['POST'])
def ai_chat():
    message = request.json['message']
    result = client.chat(message)
    return jsonify(result)

2. 命令行工具

while True:
    query = input("请输入指令: ")
    if query == 'exit':
        break
    result = client.chat(query)
    print(result['message'])

3. 聊天机器人

# 微信/钉钉机器人
def on_message(message):
    result = client.chat(message)
    return result['message']

安全说明

1. API Key 保密 - 不要在前端代码中暴露
2. 操作确认 - AI 返回建议操作，需调用 execute 才执行
3. 权限控制 - 后台 API 应有自己的权限验证

获取帮助

• 官网: https://wangyunge.top
• 技术支持: [e-mail]

License

MIT License