agent-ui

Vue d’ensemble

Qu’est-ce qu’agent-ui ?

agent-ui est un composant Agent « batteries incluses » pour React et Next.js fourni par ui.inference.sh. Plutôt que de construire une interface de chat IA à la main depuis zéro, vous installez une interface Agent prête à l’emploi, accompagnée d’une simple route API proxy pilotée par @inferencesh/sdk.

Le composant regroupe les éléments essentiels dont on a généralement besoin pour des assistants IA modernes :

• Une interface de chat/agent plug-and-play
• Le câblage runtime vers un backend d’inférence via une route proxy
• La prise en charge du streaming de réponses
• De la marge pour des outils, validations et des flux d’agents plus avancés (via la stack sous-jacente ui.inference.sh)

Si vous voulez intégrer des assistants IA, des copilotes SaaS ou des interfaces agentiques dans une application Next.js, agent-ui vous offre une base prête pour la production avec un minimum de boilerplate.

À qui s’adresse agent-ui ?

agent-ui est conçu pour :

• Les développeurs frontend qui veulent une interface agent/chat soignée dans une app React ou Next.js sans concevoir les composants eux‑mêmes.
• Les équipes produit qui intègrent des copilotes ou assistants IA dans des dashboards existants, des produits SaaS ou des outils internes.
• Les ingénieurs orientés API qui préfèrent configurer une route proxy et des variables d’environnement plutôt que d’écrire à la main toute la logique de requêtes côté client.

Vous serez particulièrement à l’aise avec cette skill si vous :

• Utilisez déjà Next.js (App Router) ou une stack React similaire
• Êtes familier avec les variables d’environnement et les clés d’API
• Savez configurer des routes et composants dans un codebase TypeScript/React

Quels problèmes agent-ui résout-il ?

agent-ui vous aide à éviter plusieurs points de friction fréquents lors de l’implémentation de fonctionnalités IA :

• Aucune UI de chat custom à coder – vous évitez de construire de zéro les listes de messages, champs de saisie et états de chargement.
• Pas de « glue » fetch ad hoc – la route proxy est gérée via @inferencesh/sdk, ce qui vous évite de réécrire la logique de streaming et de gestion d’erreurs.
• Configuration simplifiée – vous passez un objet agentConfig (référence de modèle, description, system prompt) plutôt que de propager manuellement la config dans toute l’UI.

Cela fait d’agent-ui un très bon choix si vous voulez passer rapidement de « nous avons une clé d’API » à « nous avons une interface d’agent opérationnelle ».

Quand agent-ui est-il adapté ?

agent-ui est particulièrement adapté lorsque :

• Vous développez une application Next.js (notamment avec la structure de répertoires app/).
• Vous souhaitez une interface d’agent préconstruite au look moderne, basée sur l’écosystème shadcn.
• Vous êtes à l’aise pour configurer une route inference proxy et des variables d’environnement.

Ce n’est peut-être pas le meilleur choix si :

• Vous n’utilisez pas React/Next.js pour votre frontend.
• Vous avez besoin d’une UI de chat entièrement sur‑mesure avec des interactions très éloignées d’une interface d’agent classique.
• Vous ne pouvez pas exposer ou gérer une variable INFERENCE_API_KEY dans votre environnement.

Comment l’utiliser

1. Installation de la skill dans votre workspace d’agents

Pour ajouter la skill agent-ui dans un workspace compatible Agent Skills, installez-la via le CLI skills :

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

Cette commande récupère les métadonnées de la skill agent-ui depuis le dépôt inferen-sh/skills. Après l’installation, ouvrez SKILL.md dans le dossier ui/agent-ui pour suivre la documentation amont.

2. Installer le composant agent-ui dans un projet Next.js

Dans votre application Next.js (là où vous voulez rendre l’UI), installez le composant Agent depuis ui.inference.sh à l’aide de la commande au format shadcn mentionnée par la skill :

# Installer le composant agent
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# Ajouter le SDK pour la route proxy
npm install @inferencesh/sdk

Cela fait deux choses :

• Importe le bloc Agent UI (composant React et câblage UI associé) depuis ui.inference.sh.
• Installe @inferencesh/sdk, que vous utiliserez pour créer la route proxy d’inférence dans votre app Next.js.

Vous pouvez exécuter ces commandes dans n’importe quel projet Next.js existant (App Router). Assurez-vous de disposer de Node.js, npm (ou un autre gestionnaire de paquets) et d’un environnement de développement fonctionnel avant de les lancer.

3. Configurer la route API proxy dans Next.js

agent-ui s’attend à ce que votre frontend communique avec une route backend proxy, plutôt que d’appeler le service d’inférence directement depuis le navigateur. La documentation de la skill fournit une route Next.js minimale basée sur @inferencesh/sdk :

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

Points d’implémentation :

• Placez ce fichier dans app/api/inference/proxy/route.ts dans un projet Next.js App Router.
• Le helper route de @inferencesh/sdk/proxy/nextjs expose pour vous les handlers HTTP (GET, POST, PUT), vous évitant d’écrire votre propre logique de routing.
• Ce point de terminaison devient le proxyUrl que vous passerez au composant Agent.

Si vous utilisez une autre structure de dossiers, gardez un chemin cohérent et mettez à jour votre proxyUrl en conséquence.

4. Définir la variable d’environnement INFERENCE_API_KEY

Configurez ensuite votre clé d’API d’inférence dans votre environnement local. Les instructions de la skill font référence à la variable INFERENCE_API_KEY :

# .env.local
INFERENCE_API_KEY=inf_...

Étapes :

1. Créez ou ouvrez .env.local à la racine de votre projet Next.js.
2. Remplacez inf_... par votre clé d’API réelle.
3. Redémarrez votre serveur de développement pour que les changements de .env.local soient pris en compte.

Veillez à garder cette clé secrète et à ne jamais committer .env.local dans votre contrôle de version.

5. Afficher le composant Agent dans une page

Une fois le composant et la route proxy en place, vous pouvez rendre l’interface Agent dans n’importe quelle page Next.js. La skill inclut un exemple concis :

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.',
      }}
    />
  );
}

Points clés à comprendre :

• proxyUrl : pointe vers la route API proxy que vous avez créée (/api/inference/proxy). C’est par là que l’Agent UI envoie et reçoit les messages.
• agentConfig : un objet qui configure l’agent sous-jacent, notamment :
  • core_app.ref : une référence au modèle ou à l’app utilisée côté backend.
  • description : une description lisible de l’assistant.
  • system_prompt : un court system prompt qui oriente son comportement.

Vous pouvez dupliquer ou adapter ce fichier de page dans app/agent/page.tsx ou sur n’importe quelle route existante de votre application.

6. Personnaliser et étendre agent-ui

Le fichier SKILL.md de la skill mentionne des fonctionnalités comme les tools, approvals et widgets (via ui.inference.sh). Pour en tirer parti, vous pouvez, de façon itérative :

• Ajuster agentConfig avec différentes références de modèles, descriptions et system prompts.
• Explorer les fichiers du bloc Agent installés sous @/registry/blocks/agent/agent pour voir comment l’UI est construite et quels props sont pris en charge.
• Intégrer l’Agent UI dans des parcours spécifiques de votre app (par exemple : dashboard de support, copilot d’onboarding ou assistant d’opérations internes).

Comme agent-ui est fourni sous forme de composant React, vous pouvez l’envelopper dans des layouts, modales ou onglets, et l’intégrer à vos propres schémas de navigation et d’authentification.

7. Fichiers à consulter après l’installation

Après avoir installé la skill agent-ui dans votre workspace compatible skills, le fichier principal à ouvrir est :

• ui/agent-ui/SKILL.md – guide de démarrage rapide et détails de configuration amont.

À partir de là, vous pouvez transposer les instructions dans votre projet Next.js en production et les adapter à vos modèles et contraintes backend.

FAQ

agent-ui nécessite-t-il Next.js ou puis-je l’utiliser avec du React « simple » ?

Le walkthrough d’installation de la skill et l’exemple de route proxy sont rédigés spécifiquement pour Next.js, en utilisant la convention de routes app/api et @inferencesh/sdk/proxy/nextjs. Même si l’UI elle-même est basée sur React, le chemin documenté et pris en charge dans cette skill cible Next.js avec des API routes au format App Router.

Si vous utilisez du React « simple » ou un autre framework, vous devrez reconstituer vous-même le comportement du proxy et adapter l’exemple ; cette intégration n’est pas documentée dans cette skill.

En quoi agent-ui est-il différent d’une UI de chat construite sur mesure ?

Avec agent-ui, vous :

• Installez un composant Agent préconstruit depuis ui.inference.sh.
• Le connectez à un backend d’inférence via une unique route proxy et une variable d’environnement.

Vous n’avez pas à :

• Concevoir et coder la liste des messages, la zone de saisie et les états de streaming.
• Écrire à la main les appels fetch pour envoyer et recevoir des messages.

Vous conservez toutefois le contrôle de la configuration via agentConfig, ce qui vous permet de modifier la référence de modèle, la description et le system prompt sans toucher à l’interne de l’UI.

Quel est le rôle de @inferencesh/sdk dans cette configuration ?

@inferencesh/sdk alimente la route proxy côté serveur :

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

En utilisant ce helper, vous :

• Exposez une unique endpoint (/api/inference/proxy dans l’exemple) pour la communication avec votre Agent UI.
• Déléguez à ce SDK les détails de protocole et la gestion des méthodes HTTP (GET, POST, PUT) au lieu d’écrire du code custom.

Cela simplifie la maintenance et l’évolution de votre intégration d’inférence sans devoir réécrire l’UI.

Comment changer le modèle ou le comportement de l’agent ?

Vous mettez à jour le agentConfig passé au composant Agent. Par exemple :

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

Pour modifier le comportement, vous pouvez :

• Remplacer core_app.ref par un autre modèle ou app compatible.
• Mettre à jour description pour refléter le rôle de l’assistant (par ex. « customer support copilot »).
• Affiner le system_prompt pour ajuster le ton et le périmètre des tâches.

Consultez la documentation de votre backend d’inférence pour connaître les valeurs valides et les options de configuration supplémentaires.

agent-ui convient-il à un usage en production ?

La skill agent-ui expose un vrai composant Agent React/Next.js et un pattern de route proxy pensé pour des apps proches de la production. Toutefois, la robustesse en production dépend de la façon dont vous :

• Gérez vos clés d’API et variables d’environnement.
• Ajoutez de l’authentification, de l’autorisation et du rate limiting autour de /api/inference/proxy.
• Surveillez, journalisez et sécurisez le trafic vers votre backend d’inférence.

La skill vous donne une base solide, mais vous devez y ajouter vos propres politiques de sécurité, d’observabilité et de gestion d’erreurs avant un déploiement live.

Où trouver la documentation amont d’agent-ui ?

Après avoir installé la skill via :

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

ouvrez :

• ui/agent-ui/SKILL.md

Ce fichier est maintenu dans le dépôt inferen-sh/skills et contient le quick start amont (commandes d’installation, snippet de route proxy, configuration des variables d’environnement et exemple d’utilisation du composant) pour le composant agent-ui.