로디 · 문서

08/ 08

상담 Agent 3 · 답변에 맞는 화면

Owen Lee · 이원빈완성 원고

Screen Agent의 선택이 실제 화면 변경으로 이어지는 과정

로디는 고령층이 복지·법률 정보를 묻고 다음 행동을 정하도록 돕는 상담 서비스입니다. “어디에 문의하면 될까요?”에 기관 이름과 주소만 길게 답하면, 사용자는 다시 연락처를 찾아야 합니다. 방문 전에 준비할 일을 들어도 각 항목을 기억하기는 어렵습니다. 그래서 조건을 입력할 양식, 연락할 기관, 준비할 일의 목록을 상담 화면에 보여주려 했습니다.

상담 답변을 작성하는 Main과, 답변에 맞는 화면을 고르는 Screen의 책임을 나눴습니다. Screen은 답변과 조회 결과에서 표시할 내용을 고릅니다. 제품 코드는 전달받은 데이터를 검사하고 미리 구현한 화면에 넣습니다. 상담 Agent 1에서 설명한 역할 분리 중, 이 글은 화면을 고른 판단이 사용자의 다음 행동으로 이어지는 과정을 다룹니다.

1. 상담에 필요한 화면들

사용자가 “받을 수 있는 지원이 있는지, 어디에 물어보면 되는지 알고 싶습니다”라고 묻지만 거주 지역은 아직 말하지 않은 장면을 생각해 보겠습니다. Main이 지역을 더 확인해야 한다고 답했다면, 지금 필요한 화면은 기관 목록보다 지역을 입력할 양식입니다.

설명용 상담 · 지역을 확인한 뒤 안내를 이어가기

실제 실행 기록이 아닌 설명용 재구성입니다. 기관·정책 조건을 가정하지 않고, 첫 질문에서 다음 입력까지 연결합니다.
상담 단계전달할 내용과 목적
사용자 질문“받을 수 있는 지원이 있는지, 어디에 물어보면 되는지 알고 싶습니다.”
Main 답변“안내에 필요한 거주 지역을 먼저 확인하겠습니다. 살고 계신 시·군·구를 알려주세요.”
Screen의 선택조건 입력 화면에 빈 거주지 필드를 보여줍니다. 아직 확인하지 않은 기관이나 연락처는 채우지 않습니다.
음성 안내Speech Text가 지역을 알려 달라는 다음 행동을 발화문에 남깁니다.
사용자의 다음 행동지역을 입력하고 ‘입력 정보 반영’을 누르면, 입력값을 담은 새 상담 요청을 보냅니다.

복지 상담에서 반복되는 장면을 조건 확인, 기관 안내, 근거 확인, 신청·방문 준비로 나눴습니다. 각 장면에 필요한 화면을 미리 구현하고, Screen이 답변에 맞는 화면과 표시할 내용을 선택하게 했습니다. 이 화면 단위를 surface라고 부릅니다.

상담 시작에는 시작 화면, 조건이 부족하면 입력 양식, 연락하거나 방문할 곳은 기관 화면, 출처 확인은 근거 문서, 신청과 방문 준비는 체크리스트를 선택합니다. 각 화면은 제품 코드에 미리 구현돼 있습니다.
다섯 surface의 역할을 나타낸 개념도입니다. 실제 서비스 화면 캡처가 아니며, 화면 배치와 버튼 동작은 frontend가 관리합니다.원본 크기로 보기
화면사용하는 상황화면에 담는 정보
시작 화면 · default상담 시작 또는 별도의 결과 화면이 필요 없을 때제목, 안내 문장, 현재 상태
조건 입력 · profile-intake거주 지역이나 상담 조건을 더 알아야 할 때질문할 항목, 입력 필드, 선택지
기관 안내 · institution-results어디에 연락하거나 방문할지 안내할 때기관 후보, 위치, 연락처, 선택한 기관
근거 문서 · evidence-documents답변의 출처나 관련 규정을 확인할 때문서 제목, 링크, 발췌 내용, 선택한 문서
준비 항목 · action-checklist신청이나 방문 전에 할 일을 정리할 때준비할 항목, 진행 상태, 다음 단계

지역을 확인하고 기관을 조회한 뒤에는 기관 화면이 필요해집니다. 이후 사용자가 준비물을 묻는다면 체크리스트로 넘어갑니다. 같은 상담에서도 지금 해결할 일이 달라지므로, 답변의 길이보다 사용자가 다음에 무엇을 할지를 화면 선택의 기준으로 삼았습니다.

화면 배치와 버튼 동작은 frontend가 관리합니다. Agent가 매번 HTML이나 JSX를 작성하도록 두면, 답변에 필요한 정보를 고르는 일 외에 배치와 동작까지 검증해야 합니다. 로디에서는 이미 구현한 화면에 정해진 형식의 데이터를 넣도록 범위를 잡았습니다. 새로운 화면이 필요해지면 frontend와 tool의 입력 형식을 함께 추가합니다.

2. Screen에 전달하는 답변과 현재 화면

Screen에는 Main의 최종 답변, 이번 turn의 사용자 질문·tool 호출·반환 결과, 질문을 보낸 시점의 화면 정보를 전달합니다. 최종 답변은 무엇을 안내할지 정하는 기준이고, 조회 결과는 화면에 넣을 세부 정보의 근거입니다. Main이 기관 이름만 짧게 답했더라도 확인한 주소와 링크는 조회 결과에서 가져올 수 있습니다.

앞의 지역 확인 예시에서는 아직 조회한 기관 정보가 없습니다. Screen이 채워야 할 것은 빈 지역 입력칸이며, 다음 단계에 쓸 기관을 미리 만들어 넣는 일이 아닙니다. 반대로 기관을 안내하는 turn이라면 그 turn의 조회 결과에서 후보와 연락처를 확인합니다. 과거 모든 tool 기록을 다시 읽히는 방식은 아닙니다.

현재 화면 정보는 브라우저의 화면 전체를 복사한 값이 아니라, 요청 시점에 추린 snapshot입니다. 화면 종류와 제목, 선택한 기관·문서의 ID, 후보 수 등을 담습니다. “이곳으로 가려면 무엇을 준비해야 하나요?”라는 질문에서 선택한 기관을 참고할 수 있지만, 요청을 보낸 뒤 바뀐 선택까지 진행 중인 요청에 자동 반영되지는 않습니다.

조건 입력 화면의 snapshot은 입력 필드에 대해서는 필드 수와 채워진 필드 수만 담습니다. 실제 입력값은 사용자가 화면의 반영 버튼을 눌렀을 때 별도 경로로 전송합니다. frontend가 각 필드의 이름과 값을 상담 문장으로 만들고, 이를 다음 사용자 질문으로 보냅니다. 따라서 화면 상태의 요약과 사용자가 제출한 조건을 구분해서 읽어야 합니다.

Screen이 화면을 고르며 만든 하위 대화는 다음 Main 상담 이력에 합치지 않습니다. 화면 변경 command는 화면 상태로, 실행 과정은 별도 trace로 전달합니다. 다음 상담이 화면 제어용 문장을 사용자의 질문이나 상담 답변으로 다시 읽지 않게 한 경계입니다.

3. 어떤 화면을 고를까

Screen의 instruction에는 사용자 요청을 기준으로 화면을 고르는 순서를 적었습니다. 준비물과 절차가 중심이면 체크리스트, 위치와 방문이 중심이면 기관 안내, 출처 확인이 목적이면 근거 문서를 선택합니다. 아직 조건이 부족해 Main이 추가 질문을 하고 있다면 조건 입력 화면을 사용합니다.

답변에 등장한 모든 화면을 바로 여는 것은 사용자의 흐름을 끊을 수 있습니다. Main이 “필요하시면 관련 문서도 보여드릴게요”라고 제안만 했다면 화면을 바로 바꾸지 않도록 했습니다. 사용자가 다음 질문에서 동의하거나 요청했을 때 문서를 보여줍니다. 이미 같은 목적의 화면을 보고 있고 새 정보가 거의 없다면 현재 화면을 유지하도록 했습니다.

한 turn에서는 화면 tool을 최대 하나만 사용하도록 안내합니다. 여러 종류의 정보가 있더라도 이번 답변에서 사용자가 먼저 확인할 화면을 고르게 하려는 기준입니다. 현재 이 제한은 instruction에 있으며, 호출 개수를 1개로 막는 별도 counter는 없습니다. 서로 다른 ID의 화면 변경 요청이 여러 개 오면 각각 적용될 수 있습니다.

또한 기관 주소와 전화번호, 링크, 실제 좌표는 Main의 답변이나 확인한 tool 결과에서 가져오도록 했습니다. 표시할 정보를 새로 만들어 채우는 작업과, 이미 조회한 정보를 화면에 배치하는 작업을 구분한 기준입니다. 입력 형식의 검증과 함께 출처가 맞는지도 확인해야 합니다.

4. 선택한 화면을 tool로 전달하기

지역 입력 화면을 골랐다고 해서 브라우저가 바로 바뀌지는 않습니다. Screen은 조건 입력 화면용 tool에 제목과 안내 문장, 입력 필드, 버튼 문구를 전달합니다. 화면마다 필요한 필드를 schema로 정해, 모델이 표시할 데이터를 그 형식에 맞춰 구성하도록 했습니다.

tool이 호출되면 backend는 Python의 Pydantic schema로 입력을 검사합니다. 검사를 통과한 값에 command ID와 화면 변경 동작을 붙여 브라우저로 보냅니다. 일반 화면 전환에는 workspace.showSurface, 시작 화면에는 workspace.showDefault를 사용합니다.

앞의 상담 예시를 화면 변경 데이터로 옮기면 아래와 같습니다. 사용자에게 아직 듣지 못한 거주지는 빈 값으로 둡니다. 실제 전송에서는 이 command 바깥에 중복 처리를 위한 ID가 붙습니다.

설명용 예시 · 지역 입력 화면의 command

{
  "type": "workspace.showSurface",
  "surface": {
    "type": "profile-intake",
    "title": "거주 지역을 알려주세요",
    "description": "살고 계신 시·군·구를 입력해주세요.",
    "fields": [{
      "id": "residence",
      "kind": "text",
      "label": "거주지",
      "value": "",
      "placeholder": "시·군·구"
    }],
    "suggestedQuestions": [],
    "primaryActionLabel": "입력 정보 반영"
  }
}

Agent에 노출한 tool 이름과 frontend의 command 이름은 따로 두었습니다. Agent는 화면별 parameter를 채우고, frontend는 공통 화면 변경 동작과 화면별 데이터를 받습니다. 표시할 데이터와 실제로 실행할 동작을 각각 검사할 수 있는 경계입니다.

이 예시는 전달 형식을 보여주는 재구성으로, 실제 상담에서 발행한 command나 화면 캡처가 아닙니다. schema 검사를 통과해도 지역을 더 물어야 하는 판단이 맞는지, 사용자가 실제로 입력칸을 봤는지는 별도로 확인해야 합니다.

5. 브라우저에서 화면을 바꾸는 과정

Screen이 고른 화면과 데이터를 Pydantic으로 검사한 뒤 command를 발행합니다. BFF에서 Zod로 검증하고 브라우저가 같은 ID의 중복 요청을 건너뜁니다. 기본값을 보충해 reducer로 UI state를 교체하면 미리 구현한 React 화면이 렌더링됩니다.
Backend → BFF → 브라우저의 처리 흐름입니다. 데이터 형식 검사, 같은 command의 중복 방지, 실제 화면 반영을 각각 다른 단계에서 처리합니다.원본 크기로 보기

Backend와 브라우저 사이의 BFF는 frontend에 전달할 데이터를 검사하는 서버 계층입니다. BFF는 도착한 command를 Zod schema로 다시 검사합니다. 지역 입력 화면에 필요한 필드가 맞으면 화면 변경 데이터로 전달하고, 맞지 않으면 화면에 적용하지 않고 오류 trace를 남깁니다.

브라우저는 처리한 command ID를 기억합니다. 같은 ID로 지역 입력 요청이 다시 도착하면 한 번 더 적용하지 않습니다. 새로운 요청에는 frontend가 관리하는 기본 상태를 보충하고, 화면 상태를 갱신하는 reducer에 전달합니다. 상태가 조건 입력 화면으로 바뀌면 React가 미리 구현한 입력 양식을 표시합니다.

이 과정에서 schema는 데이터의 모양을, command ID는 같은 event의 반복을 확인합니다. 서로 다른 ID로 같은 내용이 도착하거나, 형식은 맞지만 상담과 무관한 화면이 선택되는 경우는 답변과 화면 데이터를 함께 비교해야 찾을 수 있습니다.

현재 showSurface는 화면 데이터 전체를 교체합니다. 기존 체크 항목이나 선택값의 일부만 수정하는 방식이 아니므로, 사용자가 조작한 내용을 새 화면에서도 유지하려면 새 payload에 반영해야 합니다. 짧은 snapshot으로 현재 상태를 전달하고 전체 화면을 교체하는 구성에서 확인해야 할 부분입니다.

명령 발행과 실제 표시는 다른 완료 시점입니다

화면 tool의 응답은 backend가 command를 발행했다는 확인입니다. 브라우저가 그 명령을 받아 화면을 표시했다고 회신하는 ACK는 현재 연결에 없습니다. Main 다음에 병행한 Screen과 Speech Text가 끝나면 음성 합성(TTS)을 시작하지만, 이 순서가 기다리는 것은 backend의 Screen 완료입니다. 사용자가 입력 양식을 보기 전에 음성이 시작하지 않는지 확인하려면 브라우저의 표시 시점과 첫 소리를 별도로 측정해야 합니다.

지도에 표시하는 두 종류의 좌표

기관 데이터에는 실제 지리 좌표인 coordinate.lat/lng와 도식 안의 위치를 정하는 x/y가 있습니다. x/y는 화면의 0~100 범위에서 점을 배치할 위치이며, 위도·경도 대신 사용할 수 없습니다.

Naver 지도 설정과 실제 좌표가 준비된 후보가 있으면 실제 지도를 사용하고, 조건을 충족하지 못하면 도식형 화면을 보여줍니다. 기관의 위치를 확인할 때는 어떤 방식으로 표시됐는지와 실제 좌표의 출처를 함께 봐야 합니다.

입력·로딩·말하기 표시

마이크를 듣는 중인지, 답변을 기다리는 중인지, 음성을 재생하는지는 frontend가 알고 있는 작업 상태로 표시합니다. 이 상태 전환까지 Screen의 tool 판단에 맡기지는 않았습니다. Screen은 상담 내용을 보여줄 화면을 고르고, frontend는 실제 입력과 재생 진행을 반영합니다.

말하기 animation은 음성을 buffer에 모으는 중에도 켜집니다. 화면과 실제 음성의 순서를 검증할 때는 이 표시만 보지 않고, 화면이 바뀐 시점과 audio 재생 event를 함께 기록해야 합니다.

6. 검증 · 화면 선택과 실제 반영을 나눠 확인하기

상담 답변은 맞는데 화면이 그대로라면 Main의 답변 다음부터 확인합니다. Screen 입력에 필요한 조회 결과가 들어갔는지, 화면 tool을 호출했는지, BFF 검사를 통과했는지, frontend가 이미 처리한 ID로 보지는 않았는지 순서대로 보면 멈춘 지점을 좁힐 수 있습니다.

상담 본문과 실행 기록은 구분해서 보여줍니다. Main의 답변은 사용자에게 전달하고, Screen과 Speech의 입력과 실행 결과는 trace drawer에서 확인합니다. 화면 변경 데이터는 UI state에, audio는 player에 전달합니다. 여러 출력이 같은 상담 요청에서 나오더라도 각각 어디로 이어졌는지 볼 수 있게 한 구성입니다.

현재 코드와 기존 실행 기록

기준 commit 8f6a074에는 wrapper·대화 분리·stream 변환·workspace tool을 다루는 테스트 17개가 있습니다. 기존 원고의 실행 기록은 16개 통과·1개 실패입니다. 이번 콘텐츠 검증에서는 원본 테스트를 다시 실행하지 않았으므로 새 통과 결과로 보지 않습니다.

화면 tool 관련 테스트 3개 중 두 개는 시작 화면과 조건 입력 화면의 command 발행을 검사합니다. 나머지 등록 목록 테스트는 현재 등록돼 있지 않은 workspace_show_access_summary를 기대하며, 기존 실패 기록과 이 불일치가 맞닿아 있습니다. 이 테스트들은 실제 모델의 화면 선택이나 브라우저 표시를 검증하지 않습니다.

frontend에는 같은 화면 component에 준비된 데이터를 넣는 /mocks 경로가 있습니다. 실제 상담 없이도 기관·문서·체크리스트 상태를 살펴볼 수 있습니다. 다만 이 경로가 실제 상담에서의 tool 호출과 화면 반영까지 자동 검증하는 것은 아닙니다. 확인한 저장소에는 그 전체 연결을 검사하는 browser E2E가 없습니다.

별도의 2026-06-26 테스트 PDF는 SKN28-4th-1Team을 대상으로 적고 있습니다. 보고서의 수동 화면 확인 결과는 현재 3rd 코드와 17개 테스트의 재실행 결과로 합치지 않았습니다. 자료별 범위와 누락된 원본 trace는 상담 Agent 1의 검증 구역에서 구분합니다.

다음 검증 계획 · 같은 상담을 끝까지 따라가기

첫 질문부터 실제 화면 표시와 다음 요청까지 이어진 turn 자료는 아직 확보하지 못했습니다. 다음 검증에서는 Main 답변과 조회 결과, 화면 snapshot을 고정하고 아래 항목을 따로 판정할 계획입니다. 화면이 그대로 유지되는 것이 올바른 경우도 포함합니다.

미실행 검증 계획입니다. 실제 모델 호출이 필요한 비교는 모델·반복 수·API 비용 상한을 정한 뒤 별도 실행합니다.
검증 질문고정 조건과 남길 자료판정 기준
화면 선택이 맞는가지역 미확인·기관 안내·준비물 요청별로 질문, Main 답변, 조회 결과, snapshot과 선택 화면을 묶습니다.답변의 중심 내용에 맞는 화면 하나를 고르고, 확인되지 않은 정보를 채우지 않는지 봅니다.
형식 오류를 거르는가같은 입력 양식에서 필수 필드가 빠진 command와 정상 command를 비교하고 BFF trace를 남깁니다.잘못된 command는 화면에 적용되지 않고 정상 데이터는 전달되는지 확인합니다.
한 명령을 한 번 반영하는가같은 ID 재전송과 다른 ID 재전송을 구분하고 화면 상태 전후를 기록합니다.같은 ID는 건너뛰는지 봅니다. 다른 ID의 같은 내용은 별도 요청으로 처리되는 한계도 기록합니다.
다음 상담으로 이어지는가입력 전후 화면, 반영 버튼으로 보낸 질문, 다음 Main 입력을 연결합니다.사용자가 입력한 지역이 다음 요청에 포함되는지, 갱신 과정에서 입력값을 잃지 않는지 확인합니다.
화면을 보며 안내를 듣는가Screen과 Speech의 완료 순서를 달리하고 command 발행·실제 표시·첫 음성 시점을 기록합니다.backend 완료와 browser 표시를 구분해 순서를 비교합니다. 말하기 animation은 첫 음성의 대체 지표로 쓰지 않습니다.

화면 선택이 적절한지, 데이터가 유효한지, 사용자가 실제 화면을 보고 다음 요청을 보냈는지는 서로 다른 확인 항목입니다. 이 연결을 검증한 뒤에야 화면 안내가 상담 행동을 돕는지 평가할 수 있습니다.

답변 모델의 품질·비용·응답 시간에 관한 기존 자료는 상담 Agent 1의 모델 평가 구역에서 확인할 수 있습니다. 이 자료와 화면·음성 전달의 검증은 서로 다른 측정 대상을 다룹니다.

구현 코드와 검증

구현은 SKN28-3rd-1Team의 commit 8f6a074를 기준으로 확인했습니다. JSON은 전달 형태를 설명하기 위한 예시입니다.

화면 선택과 입력 정보: screen_control_agent/system_prompt.j2 · agent_wrappers/screen_control.py

화면 tool과 입력 검사: backend/src/tools/screen_control_workspace.py

BFF의 command 검사: workspace-command-schema.ts · backend-chat-stream-adapter.ts

화면 상태 반영: workspace_root/workspace-state.ts · use-chat-page-controller.ts

입력값을 다음 상담에 전달하는 경로: profile-intake-surface.tsx

지도와 상태별 화면: workspace-map.tsx · workspace-fixtures.ts

실행 기록과 테스트: agent-trace-drawer.tsx · test_screen_control_workspace_tools.py