Show HN: Concierge - 에이전트형 웹 인터페이스 (Agentic Web Interfaces) 구축을 위한 프레임워크

Model Context Protocol (MCP)는 AI 에이전트를 도구 (tools)에 연결하는 표준화된 방식입니다. Concierge는 모든 요청에 대해 모든 도구의 평면적인 목록을 노출하는 대신, 관련 있는 것들만 점진적으로 공개합니다. Concierge는 결정론적 결과 (deterministic results)와 신뢰할 수 있는 도구 호출 (tool invocation)을 보장합니다.

참고

Concierge는 Python 3.9 이상을 요구합니다. 더 빠른 의존성 해결 (dependency resolution)을 위해 uv를 사용하여 설치하는 것을 권장하지만, pip도 동일하게 잘 작동합니다.

pip install concierge-sdk

새 프로젝트 스캐폴딩 (Scaffold):

concierge init my-store # 바로 실행 가능한 프로젝트 생성
cd my-store # 프로젝트 디렉토리 진입
python main.py # MCP 서버 시작

또는 기존 MCP 서버를 래핑 (wrap) 하세요. 단 두 줄이면 충분하며, 그 외에는 아무것도 바뀌지 않습니다:

# 이전
from mcp.server.fastmcp import FastMCP
app = FastMCP("my-server")
...

팁

Concierge는 MCP 프로토콜 레벨에서 작동합니다. 이는 현재 워크플로 (workflow) 단계에 따라 tools/list에 의해 반환되는 도구를 동적으로 변경합니다. 에이전트와 클라이언트는 Concierge의 존재를 알 필요가 없으며, 각 시점에서 더 적고 더 관련성 높은 도구들을 보게 될 뿐입니다.

from concierge import Concierge
from mcp.server.fastmcp import FastMCP
app = Concierge(FastMCP("my-server"))
...

참고

'Wrap and go' 방식은 즉시 점진적인 도구 공개를 제공합니다. 전체 워크플로 제어가 필요할 때는 코드 변경 없이 app.stages와 app.transitions를 추가하기만 하면 됩니다.

모든 것을 한꺼번에 노출하는 대신, 관련된 도구들을 함께 그룹화하세요. 현재 단계의 도구들만 에이전트에게 보입니다:

app.stages = {
"browse": ["search_products", "view_product"],
"cart": ["add_to_cart", "remove_from_cart", "view_cart"],
...

어떤 단계가 어떤 단계를 따를 수 있는지 제어하세요. 에이전트는 당신이 허용한 경로를 따라서만 앞으로(또는 뒤로) 이동합니다:

app.transitions = {
"browse": ["cart"], # cart로만 이동 가능
"cart": ["browse", "checkout"], # 뒤로 가거나 진행 가능
...

단계 간 상태 공유 (Share state between steps)

LLM을 거쳐 다시 돌아오는 과정(round-tripping) 없이 워크플로 단계 간에 데이터를 전달하세요. 상태 (State)는 세션 범위 (session-scoped)이며 분산된 복제본 (distributed replicas) 간에도 작동합니다:

# "browse" 단계에서 - 선택 사항 저장
app.set_state("selected_product", {"id": "p1", "name": "Laptop"})
# "cart" 단계에서 직접 가져오기
...

시맨틱 검색 (Semantic Search)으로 확장하기

수백 개의 도구 (tools)가 있을 때, 시맨틱 검색 (semantic search)을 활성화하여 전체 API를 두 개의 메타 도구 (meta-tools) 뒤로 압축할 수 있습니다:

from concierge import Concierge, Config, ProviderType
app = Concierge("large-api", config=Config(
provider_type=ProviderType.SEARCH,
...

얼마나 많은 도구를 등록하든 상관없이, 에이전트 (agent)는 오직 다음만을 보게 됩니다:

search_tools(query: str) → 설명을 통해 도구 찾기
call_tool(tool_name: str, args: dict) → 발견된 도구 실행

Concierge는 여러 전송 방식 (transports)을 지원합니다. 웹 배포를 위해서는 스트리밍 가능한 HTTP (streamable HTTP)를 사용하세요:

# 스트리밍 가능한 HTTP (웹 권장)
http_app = app.streamable_http_app()
# 또는 stdio를 통해 실행 (기본값, CLI 기반 클라이언트용)
...

팁 (Tip)

위의 모든 것들, 즉 단계 (stages), 전이 (transitions), 상태 (state), 시맨틱 검색 (semantic search)은 모두 선택 사항이며 독립적입니다. 어떤 조합이든 사용하세요. 단순하게 시작하고 워크플로 (workflow)가 성장함에 따라 구조를 추가해 나가세요.

점진적 공개 (Progressive Disclosure): 지금 당장 중요한 도구만 노출합니다. 컨텍스트 내의 도구가 적을수록 혼란이 줄어들고 비용이 낮아집니다. |
강제된 도구 순서 (Enforced Tool Ordering): 어떤 도구가 어떤 도구를 해제할지 정의합니다. 에이전트는 자신의 추측이 아닌 사용자의 비즈니스 로직 (business logic)을 따릅니다. |
공유 상태 (Shared State): 워크플로 (workflow) 단계 간에 데이터를 서버 측에서 전달합니다. LLM을 통한 도구 호출 체이닝 (tool-call chaining)이나 프롬프트에 데이터를 다시 주입할 필요가 없습니다. |
시맨틱 검색 (Semantic Search): 대규모 API (100개 이상의 도구)의 경우, 두 개의 메타 도구 (meta-tools) 뒤로 모든 것을 압축합니다. 에이전트는 설명을 통해 검색한 후 호출합니다. |
프로토콜 호환 (Protocol Compatible): 모든 MCP 서버를 래핑 (wrap)합니다. 기존의 @app.tool() 데코레이터, 리소스, 프롬프트가 변경 없이 작동합니다. |
세션 격리 (Session Isolation): 각 대화는 고유한 워크플로 상태를 가집니다. 원자적 (atomic)이고 일관되며, 분산된 복제본 (distributed replicas) 전반에서 작동합니다. |
다중 전송 (Multiple Transports): stdio, 스트리밍 가능한 HTTP, 또는 SSE를 통해 실행할 수 있습니다. 서버리스 (serverless), 컨테이너 (containers), 베어 메탈 (bare metal) 등 어디든 배포 가능합니다. |
스캐폴딩 CLI (Scaffolding CLI): concierge init은 도구, 단계 (stages), 전이 (transitions)가 연결되어 즉시 실행 가능한 프로젝트를 생성합니다. |

30줄 미만으로 완성하는 전체 이커머스 (e-commerce) 워크플로:

from concierge import Concierge
app = Concierge("shopping")
@app.tool()
...

에이전트는 browse에서 시작합니다.

그 후 cart로 이동할 수 있으며, 그다음 checkout으로 이동할 수 있습니다. browse에서 checkout을 직접 호출할 수는 없습니다. Concierge는 프롬프트 엔지니어링 (prompt engineering) 없이 프로토콜 레벨에서 이를 강제합니다.

전체 가이드, API 레퍼런스, 배포 패턴은 docs.getconcierge.app에서 확인할 수 있습니다.

• Discord: 질문하기, 제작 중인 내용 공유하기, 도움 받기.
• Issues: 버그 보고 또는 기능 요청.
• Discussions: 긴 형식의 토론 및 RFC.

우리는 에이전트형 웹 (agentic web)을 구축하고 있습니다. 함께하세요.