Agent创建

字数统计:1.5k 字

阅读时长:5 分钟

本文档介绍如何使用 create_agent 创建临时 Agent，用于处理特定的 AI 任务。

概述

create_agent 函数允许插件开发者创建自定义的 AI Agent，可以配置特定的模型和系统提示词，用于处理特定的任务场景。

入口函数

from gsuid_core.ai_core.gs_agent import create_agent

函数签名

def create_agent(
    model_name: Optional[str] = None,
    system_prompt: Optional[str] = None,
) -> GsCoreAIAgent

参数说明

参数	类型	必填	说明
model_name	str	否	模型名称，默认使用配置中的 model_name
system_prompt	str	否	系统提示词，控制 AI 行为

GsCoreAIAgent.run() 方法

async def run(
    self,
    user_message: Union[str, Sequence[UserContent]],
    bot: Optional[Bot] = None,
    ev: Optional[Event] = None,
    rag_context: Optional[str] = None,
) -> str

参数说明

参数	类型	必填	说明
user_message	str	是	用户输入消息
bot	Bot	否	Bot 对象，用于发送消息
ev	Event	否	事件对象
rag_context	str	否	额外的 RAG 上下文

返回值

返回 AI 响应字符串。

基础示例

创建简单 Agent

from gsuid_core.ai_core.gs_agent import create_agent

# 创建自定义 Agent
agent = create_agent(
    system_prompt="""
你是一个翻译助手，负责将中文翻译成英文。
只翻译用户输入的内容，不要添加任何解释。
""",
)

# 在异步函数中使用
async def translate_text(text: str) -> str:
    result = await agent.run(text)
    return result

# 使用结果
result = await translate_text("你好，世界！")
print(result)  # Hello, world!

指定模型创建 Agent

from gsuid_core.ai_core.gs_agent import create_agent

# 使用特定模型创建 Agent
agent = create_agent(
    model_name="gpt-4",
    system_prompt="""
你是一个代码审查助手，负责审查 Python 代码。
指出代码中的问题和改进建议。
""",
)

async def review_code(code: str) -> str:
    result = await agent.run(f"请审查以下代码:\n```python\n{code}\n```")
    return result

高级用法

带上下文的 Agent

from gsuid_core.ai_core.gs_agent import create_agent
from gsuid_core.models import Bot, Event

# 创建 Agent
agent = create_agent(
    system_prompt="""
你是一个游戏助手，帮助玩家查询游戏信息。
""",
)

async def query_with_context(
    bot: Bot,
    ev: Event,
    query: str,
) -> str:
    # 传入 bot 和 ev，Agent 可以使用相关工具
    result = await agent.run(
        user_message=query,
        bot=bot,
        ev=ev,
    )
    return result

带 RAG 上下文的 Agent

from gsuid_core.ai_core.gs_agent import create_agent
from gsuid_core.ai_core.buildin_tools import search_knowledge
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

# 创建 Agent
agent = create_agent(
    system_prompt="""
你是一个知识问答助手，基于提供的上下文回答用户问题。
""",
)

async def answer_with_rag(
    ctx: RunContext[ToolContext],
    question: str,
) -> str:
    # 先检索相关知识
    knowledge = await search_knowledge(
        ctx,
        query=question,
        limit=3,
    )
    
    # 使用检索到的知识作为上下文
    result = await agent.run(
        user_message=question,
        bot=ctx.deps.bot,
        ev=ctx.deps.ev,
        rag_context=knowledge,  # 传入检索到的知识
    )
    return result

应用场景

场景一：翻译助手

from gsuid_core.ai_core.gs_agent import create_agent

class TranslationService:
    def __init__(self):
        self.zh_to_en_agent = create_agent(
            model_name="gpt-3.5-turbo",
            system_prompt="""
你是一个专业的中英翻译助手。
将中文翻译成自然流畅的英文，保持原文的语气和风格。
只输出翻译结果，不添加解释。
""",
        )
        self.en_to_zh_agent = create_agent(
            model_name="gpt-3.5-turbo",
            system_prompt="""
你是一个专业的英中翻译助手。
将英文翻译成自然流畅的中文，保持原文的语气和风格。
只输出翻译结果，不添加解释。
""",
        )
    
    async def translate(self, text: str, direction: str = "zh_to_en") -> str:
        if direction == "zh_to_en":
            return await self.zh_to_en_agent.run(text)
        else:
            return await self.en_to_zh_agent.run(text)

# 使用
translator = TranslationService()
result = await translator.translate("你好，世界！", "zh_to_en")

场景二：代码生成助手

from gsuid_core.ai_core.gs_agent import create_agent

code_agent = create_agent(
    model_name="gpt-4",
    system_prompt="""
你是一个 Python 代码生成助手。
根据用户需求生成高质量、可运行的 Python 代码。
代码应包含必要的注释和错误处理。
""",
)

async def generate_code(description: str) -> str:
    prompt = f"""
请根据以下描述生成 Python 代码:

{description}

要求:
1. 代码完整可运行
2. 包含必要的注释
3. 添加错误处理
4. 使用类型注解
"""
    return await code_agent.run(prompt)

场景三：数据分析助手

from gsuid_core.ai_core.gs_agent import create_agent

analysis_agent = create_agent(
    system_prompt="""
你是一个数据分析助手。
分析提供的数据，给出关键洞察和建议。
使用中文回答，结构清晰。
""",
)

async def analyze_data(data: dict) -> str:
    import json
    data_str = json.dumps(data, ensure_ascii=False, indent=2)
    
    prompt = f"""
请分析以下数据:

```json
{data_str}

请提供:

1. 数据概览
2. 关键指标分析
3. 趋势和洞察
4. 建议 """ return await analysis_agent.run(prompt)

### 场景四：角色扮演助手

```python
from gsuid_core.ai_core.gs_agent import create_agent

character_agent = create_agent(
    model_name="claude-3-opus",
    system_prompt="""
你是《原神》中的角色 "派蒙"。

性格特点:
- 活泼可爱，有点话痨
- 喜欢美食，特别是甜甜花酿鸡
- 是旅行者的向导和伙伴
- 说话时会用 "诶嘿"、"哇" 等语气词
- 会称呼用户为 "旅行者"

请以派蒙的身份和语气与用户对话。
""",
)

async def chat_as_paimon(user_message: str) -> str:
    return await character_agent.run(user_message)

最佳实践

1. 系统提示词设计

# 好的系统提示词示例
good_prompt = """
你是一个专业的客服助手。

## 职责
1. 回答用户的产品咨询
2. 处理常见问题
3. 引导用户到正确的资源

## 限制
- 不提供医疗、法律建议
- 不透露内部系统信息
- 保持礼貌和专业

## 回复格式
1. 先确认用户问题
2. 提供解决方案
3. 询问是否还有其他问题
"""

agent = create_agent(system_prompt=good_prompt)

2. 错误处理

from gsuid_core.ai_core.gs_agent import create_agent

agent = create_agent()

async def safe_run(message: str) -> str:
    try:
        result = await agent.run(message)
        return result
    except Exception as e:
        # 记录错误
        logger.error(f"Agent run failed: {e}")
        # 返回友好的错误信息
        return "抱歉，处理您的请求时出现了问题，请稍后重试。"

3. 上下文管理

from gsuid_core.ai_core.gs_agent import create_agent
from gsuid_core.models import Bot, Event

class ContextAwareAgent:
    def __init__(self):
        self.agent = create_agent(
            system_prompt="你是一个游戏助手。",
        )
    
    async def process(
        self,
        message: str,
        bot: Bot,
        ev: Event,
    ) -> str:
        # 添加上下文信息
        context = f"""
用户ID: {ev.user_id}
群组ID: {ev.group_id}
平台: {ev.platform}

用户消息: {message}
"""
        return await self.agent.run(
            user_message=context,
            bot=bot,
            ev=ev,
        )

注意事项

1. 模型选择：根据任务复杂度选择合适的模型
2. 系统提示词：清晰定义 Agent 的角色和职责
3. 错误处理：始终添加异常处理
4. 成本控制：注意 token 消耗，避免不必要的调用
5. 上下文传递：需要时使用 bot 和 ev 参数

下一步

• 工具注册 - 学习如何注册 AI 工具
• 知识库注册 - 了解知识库的使用
• 完整示例 - 查看更多开发示例