Agent-Native — фреймворк, где агент и интерфейс работают через один слой действий

Типичное приложение с ИИ-агентом выглядит так: текстовое поле, куда человек пишет запрос, и агент, который что-то делает в ответ. Интерфейс тут почти не участвует — он просто показывает то, что агент решил вывести текстом. Agent-Native от Builder.io предлагает другой подход. В нём агент и человек работают с одним и тем же приложением, и то и другое работает через один слой действий.

Что это за проект

Agent-Native — открытый фреймворк на TypeScript. Он нужен, чтобы собрать приложение, в котором агент не просто отвечает на вопросы, а выполняет ту же работу, что и человек, только через инструменты вместо кликов мышью.

Главная идея простая. Любую возможность приложения описывают один раз как действие (action). Дальше это же действие доступно сразу во всех местах приложения:

• агент вызывает его как инструмент;
• React-компонент вызывает его из кода;
• HTTP-запрос обращается к нему по сети;
• клиенты по протоколам MCP и A2A получают его как серверный инструмент;
• CLI вызывает его из командной строки.

Логика одна, и проверки, и права доступа везде одни и те же. Дублировать код под два разных способа вызова не нужно.

Зачем агенту интерфейс

Кодинг-агентам уже нужна среда вокруг модели. В ней есть файлы, тесты, терминал и предпросмотр. Всё это показывает человеку, что агент умеет и что он только что сделал.

Для обычной работы с информацией такая среда тоже нужна. Интерфейс показывает, на что агент способен. Он же даёт человеку привычные способы посмотреть результат, поправить его, согласовать и отправить коллегам. Agent-Native как раз про это: агент живёт внутри приложения с интерфейсом, а не в пустом чате.

Как всё устроено

Фреймворк держится на трёх общих слоях.

Общие действия. Агент вызывает возможность как инструмент, интерфейс вызывает её из кода. Проверка входных данных, права доступа и сам код — везде одни и те же.

Общие данные. То, что сделал агент, сразу появляется в интерфейсе. То, что человек сделал руками, сразу доступно агенту. Не нужно заводить отдельную базу «для агента» и отдельную «для людей».

Общее состояние приложения. Агенту передаётся то, что сейчас происходит в интерфейсе: открытая страница, выбранная запись, активный вид. Агент видит то же, что видит человек, поэтому ему не нужно переспрашивать.

При этом агент не кликает по интерфейсу. Он работает через тот же слой действий, что и интерфейс. Разница тут принципиальная: клики по кнопкам перестают работать после каждой правки вёрстки, а вызов действия остаётся стабильным контрактом.

Пример одного действия

Каждая возможность лежит в отдельном файле. Вот как это выглядит:

import { defineAction } from "@agent-native/core/action";
import { z } from "zod";

export default defineAction({
  description: "Return a friendly greeting.",
  schema: z.object({
    name: z.string().default("world").describe("Name to greet"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

Схема задаётся через Zod. Из неё фреймворк сам понимает, какие параметры принимает инструмент. Агенту не нужно отдельно описывать сигнатуру — он её и так видит.

Агент получает действие hello как инструмент. React вызывает ту же самую функцию:

const { data } = useActionQuery("hello", { name: "Alex" });

Параллельно то же действие доступно по HTTP, через MCP, через A2A и из CLI.

Почему одного REST API мало

Обычный подход — сделать сервер с REST-методами, а агента подключить к нему через MCP-мост. Схема при этом живёт в одном месте, а реализация метода — в другом. Плюс отдельно нужно описать агенту, какие методы вызывать и с какими параметрами.

Здесь всё это сведено в один файл. Функция defineAction возвращает описание, из которого фреймворк собирает и инструмент для агента, и обработчик для HTTP, и запись для CLI. Разработчик пишет тело функции один раз. Всё остальное — обвязка, которую фреймворк делает сам.

Второе отличие — права доступа. Они описаны прямо в действии, поэтому агент и человек проходят одну и ту же проверку. Значит, агенту нельзя случайно дать больше прав, чем есть у человека на экране.

Что уже есть в комплекте

Помимо самого слоя действий, в фреймворке заложены готовые части:

• Чат с агентом. Человек может поручить работу, задать вопрос и посмотреть результат в том же интерфейсе, где он работает.
• Аутентификация и права доступа. Можно ограничить, кто видит общую работу, а кто может её менять.
• Навыки и память. Агенту можно дать готовую экспертизу и постоянный контекст между сессиями.
• Автоматизации. Работа агента запускается по расписанию или по событию.
• Команды агентов. Задачу можно передать узкому агенту-специалисту — в том же рабочем пространстве или соседнему подключённому агенту.
• База данных. На сервере — обычная PostgreSQL, локально — PGlite. Хостить можно на любом хостинге, который поддерживает Nitro.

Любопытная деталь: в репозитории лежит навык /visual-edit для Claude Code. Он правит работающее приложение визуально, на холсте, а не через текстовые промпты.

Визуальное редактирование вместо промптов

Обычный цикл работы с ИИ по правке интерфейса выглядит так: описать словами «сдвинь кнопку вправо на восемь пикселей», получить правку, попросить что-то ещё. На каждое такое действие уходит отдельный запрос.

Навык /visual-edit работает иначе:

/visual-edit the onboarding flow, plus home at every breakpoint

Человек открывает экран онбординга рядом с главной страницей, на разных размерах окна — десктоп, планшет, телефон. Цвет кнопки и отступы он поправляет прямо мышью. Когда правки собраны, он один раз просит Клода перенести их в исходный код.

Подробная инструкция лежит в гайде по Visual Edit.

Примеры приложений из репозитория

В репозитории лежит галерея готовых агентов. С них можно начать, а можно взять как образец:

Полная галерея доступна на сайте проекта.

Документация, сообщество, лицензия

• Документация и гайд по быстрому старту.
• Discord проекта — там задают вопросы и делятся тем, что получилось собрать.
• Инструкция по локальной разработке — в DEVELOPMENT.md.
• Лицензия — MIT.

Фреймворк не привязывает вас к своему облаку. Свою языковую модель, SQL-базу, инструменты и инфраструктуру вы приносите сами. Всё, что вы собрали, остаётся у вас.

Быстрый старт

npx --yes @agent-native/core@latest create my-agent --standalone --template chat

Команда создаёт новый проект. Флаг --standalone просит запустить всё локально, без внешнего сервиса, а --template chat берёт за основу готовый шаблон с чатом. Дальше следуйте гайду по быстрому старту.