agent-ui

Überblick

Was ist agent-ui?

agent-ui ist eine "batteries included" Agent-Komponente für React und Next.js, bereitgestellt von ui.inference.sh. Statt ein AI-Chat-Interface komplett selbst zu bauen, installierst du ein fertiges Agent-UI zusammen mit einer einfachen API-Proxy-Route auf Basis von @inferencesh/sdk.

Die Komponente bündelt die Kernbausteine, die du typischerweise für moderne AI-Assistenten brauchst:

• Ein sofort nutzbares Chat-/Agent-Interface
• Runtime-Anbindung an ein Inference-Backend über eine Proxy-Route
• Unterstützung für Streaming-Responses
• Platz für Tools, Freigaben und komplexere Agent-Flows (über das zugrunde liegende ui.inference.sh-Setup)

Wenn du AI-Assistenten, SaaS-Copilots oder agentische UIs in einer Next.js-App ausliefern möchtest, bietet dir agent-ui einen produktionsreifen Startpunkt mit minimalem Boilerplate.

Für wen ist agent-ui gedacht?

agent-ui ist ausgelegt für:

• Frontend-Entwickler:innen, die in einer React- oder Next.js-App ein polished Agent-/Chat-UI möchten, ohne Komponenten von Grund auf zu designen.
• Produktteams, die AI-Copilots oder Assistenten in bestehende Dashboards, SaaS-Produkte oder interne Tools integrieren.
• API-orientierte Engineers, die lieber eine Proxy-Route und Umgebungsvariablen konfigurieren, statt Client-seitige Request-Logik von Hand zu schreiben.

Am wohlsten fühlst du dich mit diesem Skill, wenn du bereits:

• Next.js (App Router) oder einen ähnlichen React-Stack verwendest
• Mit Environment Variables und API-Keys vertraut bist
• Weißt, wie man Routen und Komponenten in einer TypeScript/React-Codebasis konfiguriert

Welche Probleme löst agent-ui?

agent-ui hilft dir, typische Reibungspunkte bei der Implementierung von AI-Features zu vermeiden:

• Kein eigenes Chat-UI nötig – du sparst dir den Aufbau von Nachrichtenlisten, Eingabefeldern und Ladezuständen.
• Kein ad-hoc fetch-Glue-Code – die Proxy-Route wird über @inferencesh/sdk gehandhabt, sodass du Streaming- und Error-Handling-Logik nicht ständig wiederholen musst.
• Einfachere Konfiguration – du übergibst ein agentConfig Objekt (Model-Ref, Beschreibung, System Prompt), statt Konfigurationswerte manuell durchs UI zu schleusen.

So wird agent-ui zu einer sehr guten Wahl, wenn du schnell von „wir haben einen API-Key“ zu „wir haben ein funktionierendes Agent-UI“ kommen möchtest.

Wann ist agent-ui eine gute Wahl?

agent-ui passt besonders gut, wenn:

• Du eine Next.js-App baust (insbesondere mit der app/-Verzeichnisstruktur).
• Du ein vorgefertigtes Agent-UI willst, das modern aussieht und im shadcn-ähnlichen Ökosystem gebaut ist.
• Du dich wohlfühlst damit, eine Inference-Proxy-Route und Environment Variables zu konfigurieren.

Es ist möglicherweise nicht ideal, wenn:

• Du React/Next.js nicht als Frontend-Stack verwendest.
• Du ein komplett individuell designtes Chat-UI mit maßgeschneiderten Interaktionsmustern brauchst, die stark von einer typischen Agent-Oberfläche abweichen.
• Du keinen INFERENCE_API_KEY in deiner Umgebung setzen oder verwalten kannst.

Verwendung

1. Skill-Installation in deinem Agent-Workspace

Um den agent-ui Skill in einen Agent Skills–kompatiblen Workspace einzubinden, installiere ihn über die Skills-CLI:

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

Damit wird die agent-ui Skill-Metadaten aus dem inferen-sh/skills Repository geladen. Nach der Installation öffne SKILL.md im Ordner ui/agent-ui, um die Upstream-Anleitung zu lesen.

2. Die agent-ui Komponente in ein Next.js-Projekt installieren

In deiner eigentlichen Next.js-App (in der du das UI rendern willst) installierst du die Agent-Komponente von ui.inference.sh mit dem shadcn-ähnlichen Command aus dem 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

Das erledigt zwei Dinge:

• Es zieht den Agent UI Block (React-Komponente und dazugehörige UI-Verkabelung) von ui.inference.sh.
• Es installiert @inferencesh/sdk, das du zum Aufbau der Inference-Proxy-Route in deiner Next.js-App verwendest.

Du kannst diese Commands in jedem bestehenden Next.js-Projekt mit App Router ausführen. Stelle sicher, dass Node.js, npm (oder ein anderer Package Manager) und eine funktionierende Dev-Umgebung eingerichtet sind, bevor du sie benutzt.

3. Die API-Proxy-Route in Next.js konfigurieren

agent-ui erwartet, dass dein Frontend mit einer Backend-Proxy-Route spricht, statt den Inference-Service direkt aus dem Browser aufzurufen. Die Skill-Dokumentation liefert eine minimale Next.js-Route auf Basis von @inferencesh/sdk:

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

Hinweise zur Implementierung:

• Lege diese Datei in app/api/inference/proxy/route.ts in einem Next.js App Router Projekt ab.
• Der route Helper aus @inferencesh/sdk/proxy/nextjs stellt dir die HTTP-Handler (GET, POST, PUT) bereit, sodass du keine eigene Routing-Logik schreiben musst.
• Dieser Endpunkt wird zu der proxyUrl, die du an die Agent Komponente übergibst.

Wenn du eine andere Verzeichnisstruktur nutzt, halte den Pfad konsistent und passe deine proxyUrl entsprechend an.

4. Die INFERENCE_API_KEY Environment Variable setzen

Als Nächstes konfigurierst du deinen Inference API-Key in deiner lokalen Umgebung. Die Skill-Anleitung verweist auf eine Variable INFERENCE_API_KEY:

# .env.local
INFERENCE_API_KEY=inf_...

Vorgehen:

1. Erstelle oder öffne .env.local im Root deines Next.js-Projekts.
2. Trage deinen echten API-Key anstelle von inf_... ein.
3. Starte deinen Dev-Server neu, damit Änderungen an .env.local übernommen werden.

Achte darauf, diesen Key geheim zu halten und .env.local nie ins Version Control zu committen.

5. Die Agent-Komponente in einer Page rendern

Sobald Komponente und Proxy-Route eingerichtet sind, kannst du das Agent-UI in jeder Next.js-Page rendern. Der Skill enthält ein kompaktes Beispiel:

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

Wichtige Punkte:

• proxyUrl: Zeigt auf die API-Proxy-Route, die du erstellt hast (/api/inference/proxy). Darüber sendet und empfängt das Agent-UI Nachrichten.
• agentConfig: Ein Objekt, das den zugrunde liegenden Agent konfiguriert, inklusive:
  • core_app.ref: Referenz auf das im Backend verwendete Modell oder die App.
  • description: Eine gut lesbare Beschreibung des Assistenten.
  • system_prompt: Ein kurzer System Prompt, der das Verhalten steuert.

Du kannst diese Page-Datei z. B. in app/agent/page.tsx oder in jeder bestehenden Route deiner App anlegen bzw. anpassen.

6. agent-ui anpassen und erweitern

In SKILL.md des Skills sind Features wie Tools, Approvals und Widgets (über ui.inference.sh) erwähnt. Um diese auszuschöpfen, kannst du schrittweise:

• agentConfig mit anderen Model-Refs, Beschreibungen und System Prompts anpassen.
• Die installierten Agent Block-Dateien unter @/registry/blocks/agent/agent ansehen, um zu verstehen, wie das UI aufgebaut ist und welche Props unterstützt werden.
• Das Agent-UI in spezifische App-Flows integrieren (zum Beispiel ein Support-Dashboard, einen Onboarding-Copilot oder einen internen Operations-Assistenten).

Da agent-ui als React-Komponente ausgeliefert wird, kannst du sie in Layouts, Modals oder Tabs einbetten oder deine eigene Navigation und Authentifizierung darum herum bauen.

7. Wichtige Dateien nach der Installation

Nach der Installation des agent-ui Skills in deinem skills-fähigen Workspace solltest du vor allem diese Datei öffnen:

• ui/agent-ui/SKILL.md – Upstream-Quickstart und Konfigurationsdetails.

Von dort aus kannst du die Anweisungen auf dein laufendes Next.js-Projekt übertragen und an deine Modelle und Backend-Constraints anpassen.

FAQ

Benötigt agent-ui zwingend Next.js oder kann ich es mit reinem React nutzen?

Das Setup-Walkthrough und das Proxy-Route-Beispiel im Skill sind speziell für Next.js geschrieben und nutzen die app/api-Routenkonvention sowie @inferencesh/sdk/proxy/nextjs. Das UI selbst basiert zwar auf React, aber der dokumentierte und unterstützte Weg in diesem Skill ist Next.js mit einer App Router–ähnlichen API-Route.

Wenn du reines React oder ein anderes Framework verwendest, müsstest du das Proxy-Verhalten selbst nachbauen und das Beispiel anpassen; dieser Integrationsweg ist in diesem Skill nicht dokumentiert.

Worin unterscheidet sich agent-ui vom Aufbau eines eigenen Chat-UIs?

Mit agent-ui:

• Installierst du eine vorkonfigurierte Agent-Komponente von ui.inference.sh.
• Bindest du sie über eine einzige Proxy-Route und eine Environment Variable an ein Inference-Backend an.

Du musst nicht:

• Eine Chat-Nachrichtenliste, Eingabefläche und Streaming-States designen und implementieren.
• Fetch-Calls für das Senden und Empfangen von Nachrichten von Hand schreiben.

Über agentConfig behältst du dennoch die volle Konfigurationskontrolle und kannst Model-Referenz, Beschreibung und System Prompt ändern, ohne das UI-Internal anzufassen.

Welche Rolle spielt @inferencesh/sdk in diesem Setup?

@inferencesh/sdk treibt die Server-seitige Proxy-Route an:

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

Mit diesem Helper kannst du:

• Einen einzigen Endpunkt (im Beispiel /api/inference/proxy) für dein Agent-UI bereitstellen.
• Protokolldetails und das Handling der HTTP-Methoden (GET, POST, PUT) an das SDK delegieren statt eigene Logik zu schreiben.

So wird die Inference-Integration leichter wartbar und anpassbar, ohne dass du das UI neu schreiben musst.

Wie ändere ich das Modell oder das Verhalten des Agents?

Du passt die agentConfig an, die du an die Agent Komponente übergibst. Zum Beispiel:

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

Um das Verhalten zu ändern, kannst du:

• core_app.ref auf ein anderes unterstütztes Modell oder eine andere App umstellen.
• Die description an die Rolle des Assistenten anpassen (z. B. „customer support copilot“).
• Den system_prompt verfeinern, um Tonalität und Aufgabenbereich zu steuern.

Konsultiere die Dokumentation deines Inference-Backends für gültige Werte und weitere Konfigurationsoptionen.

Ist agent-ui für den Produktivbetrieb geeignet?

Der agent-ui Skill stellt eine echte React/Next.js Agent-Komponente und ein Proxy-Route-Muster bereit, die auf produktionsähnliche Apps ausgerichtet sind. Ob deine Nutzung produktionsreif ist, hängt aber davon ab, wie du:

• API-Keys und Environment Variables verwaltest.
• Authentifizierung, Autorisierung und Rate Limiting rund um /api/inference/proxy implementierst.
• Traffic zu deinem Inference-Backend überwachst, loggst und absicherst.

Der Skill liefert einen soliden Ausgangspunkt, aber du solltest eigene Security-, Observability- und Error-Handling-Mechanismen ergänzen, bevor du live gehst.

Wo finde ich die Upstream-Dokumentation für agent-ui?

Nachdem du den Skill installiert hast mit:

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

öffne:

• ui/agent-ui/SKILL.md

Diese Datei wird im inferen-sh/skills Repository gepflegt und enthält den Upstream-Quickstart (Installationsbefehle, Proxy-Route-Snippet, Env-Konfiguration und Beispiel für die Komponentenverwendung) für die agent-ui Komponente.