agent-ui

Descripción general

¿Qué es agent-ui?

agent-ui es un componente de tipo Agent para React y Next.js con todo incluido, proporcionado por ui.inference.sh. En lugar de construir desde cero una interfaz de chat con IA, instalas una UI de Agent lista para usar junto con una ruta proxy de API sencilla basada en @inferencesh/sdk.

El componente agrupa las piezas clave que normalmente necesitas para asistentes de IA modernos:

• Una interfaz de chat/agent lista para integrar
• Conexión en tiempo de ejecución con un backend de inferencia mediante una ruta proxy
• Compatibilidad con respuestas en streaming
• Espacio para herramientas, aprobaciones y flujos de agente más avanzados (a través de la configuración base de ui.inference.sh)

Si quieres lanzar asistentes de IA, copilotos SaaS o interfaces agenticas dentro de una app Next.js, agent-ui te da un punto de partida listo para producción con muy poco boilerplate.

¿Para quién está pensado agent-ui?

agent-ui está diseñado para:

• Desarrolladores frontend que quieren una UI de agente/chat pulida en una app React o Next.js sin diseñar componentes desde cero.
• Equipos de producto que integran copilotos o asistentes de IA en dashboards existentes, productos SaaS o herramientas internas.
• Ingenieros centrados en APIs que prefieren configurar una ruta proxy y variables de entorno en lugar de escribir a mano la lógica de peticiones en el cliente.

Te sentirás más cómodo con esta skill si ya:

• Usas Next.js (App Router) o un stack similar basado en React
• Estás familiarizado con variables de entorno y API keys
• Sabes configurar rutas y componentes en un código base TypeScript/React

¿Qué problemas resuelve agent-ui?

agent-ui te ayuda a evitar fricciones habituales al implementar funciones de IA:

• No necesitas una UI de chat a medida: te saltas construir listas de mensajes, cajas de entrada y estados de carga desde cero.
• Sin "fetch glue" ad hoc: la ruta proxy se gestiona con @inferencesh/sdk, así que no tienes que repetir lógica de streaming y manejo de errores.
• Configuración más sencilla: pasas un objeto agentConfig (referencia de modelo, descripción, system prompt) en lugar de propagar manualmente la configuración por la UI.

Esto convierte a agent-ui en una buena opción cuando quieres pasar rápido de “tenemos una API key” a “tenemos una UI de agente funcionando”.

¿Cuándo encaja bien agent-ui?

agent-ui es una buena opción cuando:

• Estás construyendo una app Next.js (especialmente con la estructura de directorios app/).
• Quieres una UI de agente preconstruida con aspecto moderno y basada en el ecosistema estilo shadcn.
• Te sientes cómodo configurando una ruta inference proxy y variables de entorno.

Puede que no sea la mejor opción si:

• No usas React/Next.js como stack de frontend.
• Necesitas una UI de chat completamente a medida, con patrones de interacción muy distintos a una interfaz de agente típica.
• No puedes exponer ni gestionar una INFERENCE_API_KEY en tu entorno.

Cómo usarlo

1. Instalación de la skill en tu workspace de agente

Para añadir la skill agent-ui en un workspace compatible con Agent Skills, instálala con la CLI de skills:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

Esto descarga los metadatos de la skill agent-ui desde el repositorio inferen-sh/skills. Tras la instalación, abre SKILL.md en la carpeta ui/agent-ui para seguir las instrucciones upstream.

2. Instalar el componente agent-ui en un proyecto Next.js

Dentro de tu app Next.js real (donde quieras renderizar la UI), instala el componente Agent desde ui.inference.sh usando el comando estilo shadcn indicado por la skill:

# Install the agent component
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# Add the SDK for the proxy route
npm install @inferencesh/sdk

Esto hace dos cosas:

• Importa el bloque Agent UI (componente React y wiring de UI relacionado) desde ui.inference.sh.
• Instala @inferencesh/sdk, que usarás para crear la ruta proxy de inferencia en tu app Next.js.

Puedes ejecutar estos comandos en cualquier proyecto Next.js existente (App Router). Asegúrate de tener Node.js, npm (u otro gestor de paquetes) y un entorno de desarrollo funcionando antes de ejecutarlos.

3. Configurar la ruta proxy de API en Next.js

agent-ui espera que tu frontend hable con una ruta proxy en el backend en lugar de llamar al servicio de inferencia directamente desde el navegador. La documentación de la skill proporciona una ruta mínima para Next.js basada en @inferencesh/sdk:

// app/api/inference/proxy/route.ts
import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Notas de implementación:

• Coloca este archivo en app/api/inference/proxy/route.ts en un proyecto Next.js con App Router.
• El helper route de @inferencesh/sdk/proxy/nextjs expone por ti los handlers HTTP (GET, POST, PUT), así que no necesitas lógica de routing personalizada.
• Este endpoint se convierte en el proxyUrl que pasarás al componente Agent.

Si usas una estructura de directorios distinta, mantén la ruta consistente y actualiza tu proxyUrl en consecuencia.

4. Definir la variable de entorno INFERENCE_API_KEY

A continuación, configura tu clave de inferencia en tu entorno local. Las instrucciones de la skill hacen referencia a la variable INFERENCE_API_KEY:

# .env.local
INFERENCE_API_KEY=inf_...

Pasos:

1. Crea o abre .env.local en la raíz de tu proyecto Next.js.
2. Añade tu API key real en lugar de inf_....
3. Reinicia tu servidor de desarrollo para que recoja los cambios de .env.local.

Asegúrate de mantener esta clave en secreto y de no hacer commit de .env.local al control de versiones.

5. Renderizar el componente Agent en una página

Una vez que el componente y la ruta proxy estén configurados, puedes renderizar la UI de Agent en cualquier página de Next.js. La skill incluye un ejemplo conciso:

import { Agent } from "@/registry/blocks/agent/agent";

export default function Page() {
  return (
    <Agent
      proxyUrl="/api/inference/proxy"
      agentConfig={{
        core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
        description: 'a helpful ai assistant',
        system_prompt: 'you are helpful.',
      }}
    />
  );
}

Puntos clave a entender:

• proxyUrl: apunta a la ruta proxy de API que creaste (/api/inference/proxy). Así es como la UI de Agent envía y recibe mensajes.
• agentConfig: objeto que configura el agente subyacente, incluyendo:
  • core_app.ref: referencia al modelo o app usada en el backend.
  • description: descripción legible del asistente.
  • system_prompt: breve system prompt que orienta el comportamiento.

Puedes duplicar o adaptar este archivo de página en app/agent/page.tsx o en cualquier ruta existente de tu app.

6. Personalizar y ampliar agent-ui

El SKILL.md de la skill menciona funcionalidades como tools, approvals y widgets (a través de ui.inference.sh). Para aprovecharlas, puedes iterar de esta forma:

• Ajustar agentConfig con diferentes referencias de modelo, descripciones y system prompts.
• Explorar los archivos del bloque Agent instalados bajo @/registry/blocks/agent/agent para ver cómo está construida la UI y qué props admite.
• Integrar la UI de Agent en flujos específicos de tu app (por ejemplo, un panel de soporte, un copilot para onboarding o un asistente interno de operaciones).

Como agent-ui se entrega como un componente React, puedes envolverlo en layouts, modales o pestañas, o usar tu propia navegación y patrones de autenticación a su alrededor.

7. Archivos que revisar tras la instalación

Después de instalar la skill agent-ui en tu workspace compatible con skills, el archivo principal que debes abrir es:

• ui/agent-ui/SKILL.md – guía rápida upstream y detalles de configuración.

A partir de ahí, puedes trasladar las instrucciones a tu proyecto Next.js en producción y adaptarlas a tus propios modelos y restricciones de backend.

Preguntas frecuentes

¿agent-ui requiere Next.js o puedo usarlo con React puro?

El walkthrough de configuración de la skill y el ejemplo de ruta proxy están escritos específicamente para Next.js, usando la convención de ruta app/api y @inferencesh/sdk/proxy/nextjs. Aunque la UI en sí está basada en React, el camino documentado y soportado en esta skill es para Next.js con rutas de API al estilo App Router.

Si utilizas React puro u otro framework, tendrías que recrear por tu cuenta el comportamiento del proxy y adaptar el ejemplo; ese camino de integración no está documentado en esta skill.

¿En qué se diferencia agent-ui de crear una UI de chat a medida?

Con agent-ui tú:

• Instalas un componente Agent preconstruido desde ui.inference.sh.
• Lo conectas a un backend de inferencia mediante una única ruta proxy y una variable de entorno.

No tienes que:

• Diseñar y programar una lista de mensajes de chat, área de entrada y estados de streaming.
• Escribir a mano las llamadas fetch para enviar y recibir mensajes.

Sigues manteniendo control de la configuración a través de agentConfig, por lo que puedes cambiar la referencia de modelo, la descripción y el system prompt sin tocar la lógica interna de la UI.

¿Cuál es el papel de @inferencesh/sdk en esta configuración?

@inferencesh/sdk impulsa la ruta proxy del lado servidor:

import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Al usar este helper:

• Expones un único endpoint (/api/inference/proxy en el ejemplo) con el que se comunica tu UI de Agent.
• Delegas en el SDK los detalles de protocolo y el manejo de métodos HTTP (GET, POST, PUT) en lugar de escribir código personalizado.

Esto facilita mantener y modificar tu integración de inferencia sin reescribir la UI.

¿Cómo cambio el modelo o el comportamiento del agente?

Actualizas el agentConfig que pasas al componente Agent. Por ejemplo:

<Agent
  proxyUrl="/api/inference/proxy"
  agentConfig={{
    core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
    description: 'a helpful ai assistant',
    system_prompt: 'you are helpful.',
  }}
/>

Para cambiar el comportamiento puedes:

• Sustituir core_app.ref por otro modelo o app soportada.
• Actualizar la description para reflejar el rol del asistente (por ejemplo, “customer support copilot”).
• Afinar el system_prompt para ajustar el tono y los límites de las tareas.

Consulta la documentación de tu backend de inferencia para ver valores válidos y opciones de configuración adicionales.

¿agent-ui es adecuado para uso en producción?

La skill agent-ui expone un componente real de Agent para React/Next.js y un patrón de ruta proxy orientado a aplicaciones con enfoque productivo. Sin embargo, la preparación para producción depende de cómo:

• Gestiones las API keys y variables de entorno.
• Añadas autenticación, autorización y rate limiting alrededor de /api/inference/proxy.
• Monitorices, registres y protejas el tráfico hacia tu backend de inferencia.

La skill te da un punto de partida sólido, pero deberías añadir tus propias políticas de seguridad, observabilidad y manejo de errores antes de salir a producción.

¿Dónde puedo ver la documentación upstream de agent-ui?

Después de instalar la skill con:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

abre:

• ui/agent-ui/SKILL.md

Ese archivo se mantiene en el repositorio inferen-sh/skills y contiene el quick start upstream (comandos de instalación, snippet de la ruta proxy, configuración de entorno y ejemplo de uso del componente) para el componente agent-ui.