Agent Skills Finder
I

agent-ui

작성자 inferen-sh

agent-ui는 ui.inference.sh에서 제공하는 React/Next.js용 올인원 Agent 컴포넌트입니다. 미리 만들어진 채팅·에이전트 UI와 SDK에 친화적인 proxy route를 함께 제공해, 프론트엔드나 스트리밍 로직을 직접 구현하지 않고도 AI assistant, SaaS copilot, agentic UI를 빠르게 연결할 수 있습니다.

Stars0
즐겨찾기0
댓글0
추가됨2026년 3월 27일
카테고리Frontend Development
설치 명령어
npx skills add https://github.com/inferen-sh/skills --skill agent-ui
ReactNextjsFrontendSdkAPITemplateAgent SDK
개요

개요

agent-ui란 무엇인가요?

agent-ui는 ui.inference.sh에서 제공하는 React와 Next.js용 올인원 Agent 컴포넌트입니다. AI 채팅 인터페이스를 처음부터 직접 만드는 대신, @inferencesh/sdk 기반의 간단한 API proxy route와 함께 바로 사용할 수 있는 Agent UI를 설치해 사용할 수 있습니다.

이 컴포넌트는 현대적인 AI assistant를 만들 때 보통 필요한 핵심 요소들을 함께 제공합니다:

  • 바로 가져다 쓸 수 있는 chat/agent 인터페이스
  • proxy route를 통한 inference 백엔드 런타임 연결
  • 스트리밍 응답 지원
  • 도구 호출, 승인 플로우 등 고급 agent 흐름을 위한 확장 가능성(ui.inference.sh 기반 설정 활용)

Next.js 앱 안에 AI assistant, SaaS copilot, agentic UI를 넣고 싶다면, agent-ui는 최소한의 보일러플레이트로 프로덕션에 가까운 출발점을 제공합니다.

agent-ui는 어떤 사람을 위한 것인가요?

agent-ui는 다음과 같은 분들을 위해 설계되었습니다:

  • 컴포넌트를 처음부터 디자인하지 않고도 React 또는 Next.js 앱에 완성도 높은 agent/chat UI를 넣고 싶은 프론트엔드 개발자
  • 기존 대시보드, SaaS 제품, 사내 도구 등에 AI copilot이나 assistant를 통합하려는 프로덕트 팀
  • 클라이언트 요청 로직을 직접 짜기보다는 proxy route와 환경 변수를 설정하는 방식을 선호하는 API 중심 엔지니어

다음에 해당한다면 이 스킬을 특히 편하게 사용할 수 있습니다:

  • Next.js(App Router) 또는 유사한 React 스택을 사용 중이다.
  • 환경 변수와 API 키 개념에 익숙하다.
  • TypeScript/React 코드베이스에서 라우트와 컴포넌트를 설정할 줄 안다.

agent-ui는 어떤 문제를 해결해 주나요?

agent-ui는 AI 기능 구현 시 자주 생기는 장벽을 줄여 줍니다:

  • 커스텀 채팅 UI가 필요 없음 – 메시지 리스트, 입력창, 로딩 상태 등을 처음부터 다시 만들 필요가 없습니다.
  • 임시방편 fetch 코드 제거 – proxy route가 @inferencesh/sdk로 처리되므로, 스트리밍과 에러 처리 로직을 매번 반복 작성하지 않아도 됩니다.
  • 간편한 설정 – UI 곳곳에 설정을 직접 흩뿌리는 대신, agentConfig 객체(모델 ref, 설명, system prompt)를 한 번에 넘겨서 구성할 수 있습니다.

이를 통해 "API 키는 준비됐는데"에서 "실제로 동작하는 agent UI가 있다"까지 빠르게 도달할 수 있습니다.

언제 agent-ui를 쓰는 것이 적합할까요?

agent-ui는 다음과 같은 상황에 특히 잘 맞습니다:

  • Next.js 앱을 만들고 있고(특히 app/ 디렉터리 구조를 사용할 때).
  • shadcn 스타일 생태계로 구현된 미리 만들어진 agent UI를 원할 때.
  • inference proxy route와 환경 변수 설정에 부담이 없을 때.

다음과 같은 경우에는 최적의 선택이 아닐 수 있습니다:

  • 프론트엔드 스택으로 React/Next.js를 사용하지 않을 때.
  • 일반적인 agent 인터페이스와 크게 다른, 완전히 커스텀 디자인의 채팅 UI와 상호작용 패턴이 필요한 경우.
  • 환경에서 INFERENCE_API_KEY를 노출하거나 관리할 수 없는 경우.

사용 방법

1. 에이전트 워크스페이스에 skill 설치하기

Agent Skills와 호환되는 워크스페이스에 agent-ui 스킬을 추가하려면, skills CLI로 설치합니다:

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

이 명령은 inferen-sh/skills 저장소에서 agent-ui 스킬 메타데이터를 가져옵니다. 설치 후, ui/agent-ui 폴더의 SKILL.md를 열어 upstream 사용 설명서를 확인하세요.

2. Next.js 프로젝트에 agent-ui 컴포넌트 설치

실제로 UI를 렌더링할 Next.js 앱 내부에서, 스킬에 명시된 shadcn 스타일 명령을 사용해 ui.inference.sh의 Agent 컴포넌트를 설치합니다:

# Agent 컴포넌트 설치
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# proxy route용 SDK 추가
npm install @inferencesh/sdk

이 작업을 통해 다음 두 가지가 이루어집니다:

  • ui.inference.sh에서 Agent UI 블록(React 컴포넌트 및 관련 UI 연결 코드)을 가져옵니다.
  • Next.js 앱에서 inference proxy route를 만들 때 사용할 @inferencesh/sdk를 설치합니다.

이 명령들은 어느 기존 Next.js(App Router) 프로젝트에서든 실행할 수 있습니다. 실행 전에 Node.js, npm(또는 다른 패키지 매니저), 동작 중인 개발 환경이 준비되어 있는지 확인하세요.

3. Next.js에서 API proxy route 설정

agent-ui는 브라우저에서 inference 서비스를 직접 호출하는 대신, 백엔드 proxy route를 통해 통신하도록 예상합니다. 스킬 문서에는 @inferencesh/sdk를 기반으로 한 최소한의 Next.js route 예제가 제공됩니다:

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

구현 팁:

  • 이 파일은 Next.js App Router 프로젝트의 app/api/inference/proxy/route.ts 경로에 두세요.
  • @inferencesh/sdk/proxy/nextjs의 route 헬퍼가 HTTP 핸들러(GET, POST, PUT)를 대신 노출해 주므로, 별도의 커스텀 라우팅 로직이 필요 없습니다.
  • 이 엔드포인트가 Agent 컴포넌트에 넘길 proxyUrl이 됩니다.

다른 디렉터리 구조를 사용한다면, 경로를 일관되게 유지하고 그에 맞게 proxyUrl을 업데이트하세요.

4. INFERENCE_API_KEY 환경 변수 설정

다음으로, 로컬 환경에 inference API 키를 설정해야 합니다. 스킬 설명에서는 INFERENCE_API_KEY 환경 변수를 사용합니다:

# .env.local
INFERENCE_API_KEY=inf_...

단계:

  1. Next.js 프로젝트 루트에 있는 .env.local 파일을 새로 만들거나 엽니다.
  2. inf_... 대신 실제 API 키를 입력합니다.
  3. .env.local 변경 사항이 반영되도록 개발 서버를 재시작합니다.

이 키는 반드시 비밀로 관리하고, .env.local은 버전 관리에 커밋하지 마세요.

5. 페이지에서 Agent 컴포넌트 렌더링

컴포넌트와 proxy route를 모두 준비했다면, 원하는 Next.js 페이지에서 Agent UI를 렌더링할 수 있습니다. 스킬에는 다음과 같은 간단한 예제가 포함되어 있습니다:

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

핵심 포인트:

  • proxyUrl: 앞에서 만든 API proxy route(/api/inference/proxy)를 가리킵니다. Agent UI가 이 URL을 통해 메시지를 주고받습니다.
  • agentConfig: 내부 agent 동작을 설정하는 객체로, 다음을 포함합니다:
    • core_app.ref: 백엔드에서 사용할 모델 또는 앱에 대한 참조.
    • description: assistant를 설명하는 사람 친화적인 설명.
    • system_prompt: agent의 행동을 조정하는 짧은 system prompt.

이 페이지 파일을 app/agent/page.tsx 또는 앱의 기존 어느 route에든 복사·응용해서 사용할 수 있습니다.

6. agent-ui 커스터마이즈 및 확장

스킬의 SKILL.md에는 ui.inference.sh를 통해 도구, 승인, 위젯 등의 기능을 사용할 수 있다고 안내되어 있습니다. 이를 활용하려면, 다음과 같이 점진적으로 확장할 수 있습니다:

  • agentConfig에서 모델 ref, description, system prompt를 바꿔가며 테스트합니다.
  • @/registry/blocks/agent/agent 아래에 설치된 Agent 블록 파일들을 살펴보며, UI가 어떻게 구성되어 있고 어떤 props를 지원하는지 확인합니다.
  • Agent UI를 특정 앱 플로우에 통합합니다(예: 고객 지원 대시보드, 온보딩 copilot, 사내 운영 assistant 등).

agent-ui는 React 컴포넌트 형태로 제공되므로, 레이아웃, 모달, 탭에 감싸거나, 자체 네비게이션 및 인증 패턴과 함께 사용할 수 있습니다.

7. 설치 후 확인해야 할 파일

skills 인식 워크스페이스에 agent-ui 스킬을 설치한 후, 가장 먼저 확인할 파일은 다음입니다:

  • ui/agent-ui/SKILL.md – upstream의 빠른 시작 가이드와 설정 방법이 정리되어 있습니다.

이 문서를 참고해 실제 Next.js 프로젝트에 설정을 옮겨 적용하고, 사용하는 모델과 백엔드 요구사항에 맞게 튜닝할 수 있습니다.

FAQ

agent-ui는 Next.js가 꼭 필요한가요, 아니면 순수 React에서도 쓸 수 있나요?

이 스킬의 설정 가이드와 proxy route 예제는 Next.js의 app/api route 규칙과 @inferencesh/sdk/proxy/nextjs를 기준으로 작성되어 있습니다. UI 자체는 React 기반이지만, 이 스킬에서 문서화되고 공식적으로 안내하는 경로는 App Router 스타일 API route를 사용하는 Next.js입니다.

순수 React나 다른 프레임워크를 사용할 경우, proxy 동작을 직접 구현하고 예제를 변형해야 하며, 이 통합 방식은 이 스킬에서 별도로 문서화되어 있지 않습니다.

agent-ui는 직접 채팅 UI를 만드는 것과 뭐가 다른가요?

agent-ui를 사용하면 다음과 같이 작업합니다:

  • ui.inference.sh에서 제공하는 미리 만들어진 Agent 컴포넌트를 설치합니다.
  • 단일 proxy route와 환경 변수만으로 inference 백엔드와 연결합니다.

반대로, 다음과 같은 일을 할 필요가 없습니다:

  • 채팅 메시지 리스트, 입력 영역, 스트리밍 상태 UI를 직접 디자인하고 코딩하기.
  • 메시지를 보내고 받기 위한 fetch 호출을 일일이 작성하기.

대신 agentConfig를 통해 구성 제어 권한은 유지되므로, UI 내부를 건드리지 않고도 모델 참조, 설명, system prompt를 자유롭게 변경할 수 있습니다.

이 설정에서 @inferencesh/sdk의 역할은 무엇인가요?

@inferencesh/sdk는 서버 사이드 proxy route를 담당합니다:

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

이 헬퍼를 사용하면:

  • Agent UI가 통신할 단일 엔드포인트(예: /api/inference/proxy)를 노출할 수 있습니다.
  • 프로토콜 세부사항과 HTTP 메서드 처리(GET, POST, PUT)를 SDK에 위임해, 직접 구현할 필요가 없습니다.

이를 통해 UI를 건드리지 않고도 inference 통합을 더 쉽게 유지·수정할 수 있습니다.

agent의 모델이나 동작은 어떻게 바꾸나요?

Agent 컴포넌트에 전달하는 agentConfig를 수정하면 됩니다. 예를 들어:

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

동작을 변경하려면:

  • core_app.ref를 다른 지원 모델이나 앱으로 교체합니다.
  • description을 assistant의 역할에 맞게 수정합니다(예: “customer support copilot”).
  • system_prompt를 다듬어 말투와 역할 범위를 세밀하게 조정합니다.

사용 중인 inference 백엔드 문서를 참고해 사용할 수 있는 값과 추가 설정 옵션을 확인하세요.

agent-ui는 프로덕션 환경에 사용해도 괜찮나요?

agent-ui 스킬은 실제 React/Next.js Agent 컴포넌트와 프로덕션 지향 앱에 적합한 proxy route 패턴을 제공합니다. 다만, 최종적인 프로덕션 준비 상태는 다음을 어떻게 구현하느냐에 따라 달라집니다:

  • API 키와 환경 변수를 어떻게 관리하는지.
  • /api/inference/proxy에 대한 인증, 인가, rate limiting을 어떻게 추가하는지.
  • inference 백엔드로 가는 트래픽을 어떻게 모니터링하고 로그를 수집하며 보안 설정을 하는지.

이 스킬은 탄탄한 출발점을 제공하지만, 실제 서비스 오픈 전에는 각자 환경에 맞는 보안, 관측 가능성(Observability), 에러 처리 정책을 추가해야 합니다.

agent-ui의 upstream 문서는 어디에서 볼 수 있나요?

다음 명령으로 스킬을 설치한 후:

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

다음 파일을 열어보세요:

  • ui/agent-ui/SKILL.md

이 파일은 inferen-sh/skills 저장소에서 유지·관리되며, agent-ui 컴포넌트에 대한 upstream 빠른 시작(설치 명령, proxy route 코드 조각, 환경 변수 설정, 컴포넌트 사용 예제)을 포함하고 있습니다.

평점 및 리뷰

아직 평점이 없습니다
리뷰 남기기
이 스킬의 평점과 리뷰를 남기려면 로그인하세요.
G
0/10000
최신 리뷰
저장 중...