Section 1왜 에이전트 애플리케이션은 다른가
전통적 웹 앱은 로딩 스피너를 보여준 뒤 완전한 결과를 한꺼번에 표시한다. 에이전트 애플리케이션은 길게 이어지는 텍스트 생성을 수반하며, 그 사이에 시간이 걸리는 툴 호출이 교차로 끼어든다.
| 차별점 | 요구 |
|---|---|
| 장시간 실행 | 몇 초가 아닌 몇 분·몇 시간. 사용자는 진행 상황을 확인해야 한다 |
| 점진적 출력 | 텍스트·코드·이미지·오디오가 청크 단위로 흘러나온다 |
| 조율 가시성 | 여러 에이전트의 대화와 핸드오프를 볼 수 있어야 한다 |
| 양방향 통신 | 에이전트가 작업 도중 명확화·승인을 요청할 수 있다 |
from picoagents.webui import serve # React 기반 완성된 UI를 갖춘 웹 서버를 띄운다 serve(entities=[weather_agent], port=8070)
Section 2두 가지 구성 요소
기술 선택과 무관하게, 모든 에이전트 웹 애플리케이션은 함께 작동하는 두 주요 구성 요소를 가진다.
서버에서 실행되는 모든 것 — 에이전트 로직, API 엔드포인트, 통신 프로토콜. 에이전트 실행 로직은 사용자에게 어떻게 노출되든 무관하게 순수 에이전트 구현에만 집중한다. 같은 코드가 명령줄·웹·모바일·Slack 봇에서 동일하게 실행된다. API·통신 구성 요소는 웹 서버와 UI 사이의 프로토콜을 구현한다.
에이전트 응답을 렌더링하고 사용자 입력을 받는다. 이벤트를 렌더링하는 법은 알지만 에이전트의 내부 사정은 이해할 필요가 없다 — 그저 백엔드 API를 소비한다.
두 구성 요소는 독립적으로 교체 가능하다 — 바닐라 JS로 시작했다가 React로 업그레이드(동일 백엔드), FastAPI에서 Express로 전환(동일 프론트엔드), 같은 에이전트를 웹·모바일·CLI에서 사용(서로 다른 프론트엔드).
Section 3스트리밍 — SSE vs WebSocket
@app.post("/chat/stream") async def chat_stream(request: ChatRequest): async def event_generator(): async for event in weather_agent.run_stream(request.message): yield f"data: {event.model_dump_json()}\n\n" return StreamingResponse(event_generator(), media_type="text/event-stream")
FastAPI — 비동기 네이티브 설계가 스트리밍 패턴을 깔끔하게 처리한다. Pydantic 자동 직렬화, 내장 API 문서. 서버-전송 이벤트(SSE) — 단순한 HTTP 연결로 서버→클라이언트 단방향 스트리밍. 진행 업데이트·토큰 스트리밍·툴 실행 가시성에 정확히 필요한 것. 웹소켓은 좀처럼 필요 없는 양방향 복잡성을 더하고, HTTP 폴링은 실시간 업데이트에 비효율적이다.
Section 4UX 원칙을 작동하는 코드로
8장은 3.4절의 UX 설계 원칙이 어떻게 작동하는 코드로 변환되는지 보여준다. PicoAgents WebUI는 세 원칙을 구체적 인터페이스 패턴으로 구현한다.
- 관측 가능성 — 실시간 이벤트 스트림이 에이전트 진행 상황을 보여준다. 디버그 패널이 관찰 가능한 이벤트 스트림을 표시한다.
- 역량 발견 — 클릭하여 시작할 수 있는 프리셋 예시 과업.
- 중단 가능성 — "정지" 버튼이 실행 중인 에이전트를 도중에 멈춘다. 시스템은 대화 상태를 세션 단위로 유지해 컨텍스트를 잃지 않고 재개할 수 있다.
Section 5구축의 두 접근법
| 접근 | 특징 | 적합 |
|---|---|---|
| Python 네이티브 (Streamlit·Chainlit) | Python만으로 백엔드·프론트엔드 정의. 프레임워크가 HTTP·스트리밍·렌더링 처리 | 빠른 프로토타이핑, 내부 도구 |
| 처음부터 구축 | 완전한 통제 — 직접 API 엔드포인트, 원하는 프론트엔드 기술 | 맞춤형 UX가 필수인 프로덕션 앱 |
Streamlit은 풍부한 데이터 시각화 — 분석 대시보드에 적합. Chainlit은 대화형 AI 특화 — 챗봇 스타일에 이상적. 장점은 프론트엔드 전문성 불필요·빠른 프로토타이핑·낮은 유지보수, 한계는 제한된 커스터마이즈·복잡한 상호작용의 성능 문제.