agent-backend-development

开发智能体后端

本页面向需要在 Yuxi 中新增或维护 Agent 后端的贡献者。它只讲代码装配；配置字段、权限和运行时上下文分别见配置智能体和Agent 运行时上下文。

后端放在哪里

随服务发布的 Agent 后端放在：

backend/package/yuxi/agents/buildin/<your_agent>/
├── __init__.py
├── context.py
└── graph.py

buildin 包会遍历包含 __init__.py 的子目录，发现并注册其中的 BaseAgent 子类。__init__.py 需要导出该类。

最小实现

from langchain.agents import create_agent
from yuxi.agents import BaseAgent, BaseContext, load_chat_model
from yuxi.agents.context import prepare_agent_runtime_context


class MyAgent(BaseAgent):
    name = "我的智能体"
    description = "用于示例的智能体后端"
    context_schema = BaseContext

    async def get_graph(self, context=None, **kwargs):
        context = await prepare_agent_runtime_context(
            context or self.context_schema(),
            context_schema=self.context_schema,
        )
        return create_agent(
            model=load_chat_model(fully_specified_name=context.model),
            system_prompt=context.system_prompt,
            checkpointer=await self._get_checkpointer(),
        )

这个示例展示最小的 Context、模型、提示词和 PostgreSQL checkpoint 装配。真实后端还要根据需要接入文件 backend、工具、Skills、审批、Summary、用量和子智能体 middleware。

prepare_agent_runtime_context 会根据当前用户重新过滤资源，并在模型为空时补齐系统默认模型。不要在 get_graph() 中从浏览器输入、宿主机路径或数据库原始字段直接拼出可执行配置。

Context 和配置表单

需要让管理员或用户配置 Agent 行为时，在 context.py 扩展 BaseContext：

from dataclasses import dataclass, field
from yuxi.agents import BaseContext


@dataclass(kw_only=True)
class MyAgentContext(BaseContext):
    response_style: str = field(
        default="concise",
        metadata={
            "name": "回答风格",
            "description": "控制回答的详细程度",
            "type": "string",
            "options": ["concise", "detailed"],
        },
    )

metadata 会影响 Agent 详情接口和 AgentRuntimeConfigForm。不要只在前端添加一个字段，也不要把运行期 ID、worker 身份和权限快照暴露成可保存配置。

新增字段后，沿下面的链路检查：

context_schema
  → get_configurable_items()
  → Agent 详情接口
  → 前端配置表单
  → config_json.context
  → get_graph(context)