Agentify Components

Agentify Components

一个为 React 组件添加语义元数据的框架，让 AI 系统和自动化工具能够“感知 Agent”。

概述

Agentify Components 解决了如何让 AI Agent 理解 UI 组件的问题。当 AI 助手与 Web 应用交互时，通常缺乏有关组件用途、交互方式以及处理的数据的上下文。

此框架通过装饰器为组件添加语义层，用于：

1. 注册组件元数据 - 定义组件的用途和行为
2. 提供标准化架构 - 为不同类型的组件创建一致的元数据结构
3. 生成配置文件 - 在构建时创建 MCP 服务

🚀 注意： 此框架侧重于组件元数据，而非行为修改。它让 AI 系统能够“自描述”组件，而不会改变组件功能。

安装

npm install @anvosio/agentify-components

路线图

目前，此工具只能生成 MCP 服务。接下来最重要的里程碑之一，是支持构建本地工具，并将其与您已经在构建的其他工具一起传递给大模型。

这样，您既可以拥有前端工具，也可以拥有后端工具。

尚未完成！最后更新于 2025 年 3 月 14 日

核心概念

组件类型

Agentify 目前支持三种主要的组件类型：（以下内容已移除，目前仅限于 API 和导航行为）

• 搜索栏 - 用于具有导航或 API 行为的搜索输入
• 表单 - 用于带有字段级元数据的数据收集
• 按钮 - 用于具有导航、API 或 UI 交互行为的操作

模型上下文协议（MCP）

模型上下文协议（MCP）是由 Anthropic 开发的一项开放标准，用于将 AI 模型与外部数据源和工具连接起来。它采用客户端-服务架构，使 AI 助手能够访问 Google Drive、Slack 或数据库等各类系统中的实时数据，从而利用最新上下文提升响应质量134。MCP 通过提供安全且标准化连接的通用协议来简化集成，并以可复用的 MCP 服务取代自定义 API 连接器。

框架架构

该框架由四个主要部分组成：

1. 装饰器（@AgentConfig） - 为组件添加元数据，包括通用字段和特定于协议的配置
2. 转换器 - 将通用元数据转换为特定于协议的格式（例如，目前支持 MCP 等协议，未来还会扩展到其他协议）
3. 生成器 - 根据转换后的配置生成服务文件内容，并针对各个协议进行定制
4. CLI 工具 - 处理组件，根据目标协议应用相应的转换器和生成器，并输出服务文件

这种架构确保了灵活性——开发者只需定义一次组件，即可通过按需添加新的转换器和生成器来支持多种协议。

用法

特定类型组件的 Agent 化示例（需要更新）

将搜索栏 Agent 化

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// Add semantic metadata using decorator
@AgentConfig({
  type: 'search',
  behavior: {
    type: 'api',
    endpoint: '/api/products/search',
    method: 'GET',
    queryParam: 'term'
  },
  description: 'Search for products in the catalog',
 
})
export class ProductSearch extends React.Component {
  render() {
    return (
      <input 
        type="search" 
        onChange={(e) => this.props.onSearch?.(e.target.value)}
        placeholder="Search..." 
      />
    );
  }
}

将表单 Agent 化

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// Add semantic metadata using decorator
@AgentConfig({
  type: 'form',
  behavior: {
    type: 'api',
    endpoint: '/api/auth/login',
    method: 'POST'
  },
  fields: [
    { name: 'username', type: 'text', required: true },
    { name: 'password', type: 'password', required: true }
  ],
  purpose: 'user-authentication',
  description: 'User login form for account access'
})
export class LoginForm extends React.Component {
  render() {
    return (
      <form onSubmit={this.props.onSubmit}>
        {/* Form fields */}
        <input type="text" name="username" />
        <input type="password" name="password" />
        <button type="submit">Login</button>
      </form>
    );
  }
}

将按钮 Agent 化

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// Add semantic metadata using decorator
@AgentConfig({
  type: 'button',
  behavior: {
    type: 'navigation',
    href: '/checkout'
  },
  label: 'Proceed to Checkout',
  description: 'Navigate to checkout page to complete purchase'
})
export class CheckoutButton extends React.Component {
  render() {
    return (
      <button onClick={this.props.onClick}>
        {this.props.children}
      </button>
    );
  }
}

通用组件 Agent 化示例

@anvos/agentify-components 包提供了多种方式，可为 React 组件添加 Agent 配置：

示例 1：使用 HOC 的函数组件

对于函数组件，可以使用 withAgentConfig 高阶组件，为组件包装 Agent 配置：

import { withAgentConfig } from '@anvos/agentify-components';

export const LoginButton = withAgentConfig({
  type: 'button',
  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },
  label: 'Login Button',
  selector: '#login-btn',
  description: 'Submits login form via API'
})(() => {
  return <button id="login-btn">Login</button>;
});

示例 2：直接赋值属性的函数组件

或者，您也可以创建函数组件，并直接为其指定 agentConfig 属性：

import { AgentComponent } from '@anvos/agentify-components';

export const LoginButton2: AgentComponent = () => {
  return <button id="login-btn">Login</button>;
};

LoginButton2.agentConfig = {
  type: 'button',
  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },
  label: 'Login Button',
  description: 'Submits login form via API'
};

示例 3：带装饰器的类组件

对于类组件，可以直接使用 @AgentConfig 装饰器：

import { AgentConfig } from '@anvos/agentify-components';

@AgentConfig({
  type: 'button',
  behavior: { type: 'navigation', href: '/home' },
  label: 'Home Button',
  description: 'Navigates to the home page'
})
class HomeButton extends React.Component {
  render() {
    return <button id="home-btn">Home</button>;
  }
}

export { HomeButton };

何时使用各方法

• HOC 模式（示例 1）：适用于需要为现有函数组件应用 Agent 配置，或希望将组件与其配置分开维护的情况。
• 直接赋值属性（示例 2）：适用于函数组件的最简单方法，在同一文件中定义和配置组件时很有用。
• 装饰器模式（示例 3）：类组件最优雅的选择，通过 TypeScript 装饰器提供简洁的语法。

MCP 工具架构类型映射

生成 MCP 服务时，会使用以下 JSON Schema 到 Zod 类型的映射：

JSON Schema 类型	Zod Schema 类型
string	z.string()
number	z.number()
boolean	z.boolean()
array	z.array(z.string())
object	z.object({})
integer	z.number()
float	z.number()
date	z.date()
datetime	z.date()
time	z.date()

将组件元数据转换为 MCP 服务工具所需格式时会使用这些映射。

生成 MCP 服务

在项目根目录中添加 generate.ts 文件，并加入以下代码：

import { generateMCPServer } from '@anvos/agentify-components';
import * as components from './components/ButtonExample';

const componentList = Object.values(components);

console.log(componentList);
generateMCPServer(componentList, './mcpServer');

现在，将以下脚本添加到 package.json：

"scripts": {
  "build:mcp": "ts-node ./generate.ts",
  "deploy:mcp": "echo 'STILL WORKING ON IT'"
}

这将扫描你的代码库，查找经过 Agent 化的组件，并在 /mcpServer 目录中生成 MCP 服务。

要部署 MCP 服务：

npm run deploy:mcp

这会将 MCP 服务部署到 GitHub 上的 Anvos 社区 MCP 服务，方便用户访问。你的配置将通过一个唯一 URL 提供，你可以将其分享给支持 MCP 协议的 AI 系统和工具。

我还打算进一步改进，让客户端只接收所需的工具，而不是整个 MCP 服务，因为这可以避免 MCP 客户端被不必要的工具塞满。

组件配置选项

各组件类型的详细配置选项，请参阅设置指南。

文档

• 设置指南 - 详细说明和配置选项
• 产品需求文档 - 完整的项目规范和路线图

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。