开发智能体后端

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

后端放在哪里

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

text

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

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

最小实现

python

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：

python

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 身份和权限快照暴露成可保存配置。

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

text

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

中间件和工具

资源权限和默认资源选择在 Graph 创建前处理；模型提示注入、工具动态开放、文件结果处理、state 更新和观测才适合放入 middleware。内置 Agent 的工具可见性和执行注册分为两层：工具可以先进入 ToolNode，再由 Skill 激活状态决定是否让模型看到。

优先复用：

工具系统的注册和目标校验；
中间件的装配顺序；
Skills 管理的依赖和激活规则；
沙盒机制的文件和命令边界。

新 middleware 不要绕过 prepare_agent_runtime_context，也不要用 Prompt、前端隐藏或 schema omission 代替后端授权。

检查清单

BaseAgent 子类位于可被 agent_manager 发现的包中，并被 __init__.py 导出；
context_schema 的默认值、字段权限和选项能被前端正确渲染；
Graph 使用 Yuxi 的模型、工具、文件和 checkpoint 装配入口；
工具副作用在执行处验证用户、路径和资源；
LITE 模式不会因新增导入而初始化知识库、图谱或评估重运行时；
新的模型可见输入、状态、文件或协议有正向和负向测试；
相关 API、机制和用户文档已更新。

源码和测试

改变持久配置、权限、模型可见输入、Run 生命周期或文件边界时，先按 Yuxi Spec Loop 建立相应的决策和验证范围。

开发智能体后端 ​

后端放在哪里 ​

最小实现 ​

Context 和配置表单 ​

中间件和工具 ​

检查清单 ​

源码和测试 ​