OpenAI Agent Builder — 솔직하고 완전한 가이드 (AgentKit, ChatKit, MCP, Widgets, State 패턴, 그리고 현실적인 한계)
TL;DR
- Agent Builder는 블록을 잇는 drag‑and‑drop 스타일의 시각 편집기입니다. 가능성은 크지만 아직은 초기 버전의 거친 면이 보입니다.
- 핵심 강점은 State 유지와 Structured Output(JSON/Widget). 반면, 미드‑플로 입력 제약, Preview에서 위젯 비상호작용, 연동 인증 난이도가 발목을 잡습니다.
- AgentKit은 Agent Builder, Connector Registry, ChatKit을 묶은 방향성입니다. 작업물은 Agents SDK로 code export해 자체 인프라에서 돌릴 수 있습니다.
- 문서 품질은 들쑥날쑥합니다. 예시로 한 시점의 ChatKit Python SDK repo는 README가 비어 있었습니다.
- Production‑grade UX(버튼·폼·리스트·표·차트 등)를 원하면 ChatKit embed + backend로 widget event를 직접 처리해야 합니다.
1) Agent Builder가 뭔데 중요한가
Agent Builder는 blocks(agent, conditional, loop, guardrail 등)를 선으로 이어 flow를 구성하는 시각 도구입니다. Scratch를 연상시키죠. 블록을 연결하고, Preview로 실행해보고, 다시 손보는 식으로 빠르게 반복합니다. 여기에 MCP connector, State, JSON 출력, widget 렌더링까지 얹을 수 있습니다.
왜 중요할까요? 이제 가치는 모델이 말하는 내용을 넘어 무엇을 실행하는지로 이동 중입니다. tool call로 실제 시스템을 만지고, 정보를 모으고, 결과를 유용한 UI로 보여주는 agentic 흐름이 핵심입니다.
2) 무엇이 새로 나왔나: AgentKit·Connector Registry·ChatKit
최근 릴리스는 다음을 하나로 묶었습니다.
- AgentKit: Agent Builder, connector registry, ChatKit을 포괄하는 우산 개념.
- ChatKit: 대화에 widgets(forms, lists, tables, charts, calendar cards 등)을 쓰고, 임베딩도 가능한 레이어. custom widget 제작도 지원합니다.
- 문맥: 그 이전에도 Responses API와 Agents SDK가 있었습니다. AgentKit은 이를 대체하기보다 더 쉽게 만드는 층을 더합니다.
단, 일부 문서/레포 갭이 존재합니다. 준비 과정에서 ChatKit Python SDK 레포가 README 없이 공개된 시점이 있었고, 생태계의 초기성이 느껴졌습니다.
타임라인 메모: 공개 공지 기준 10월 6일 즈음(데모 촬영 시점 약 한 달 전). AgentKit·connectors·ChatKit을 묶어 agentic app 방향을 제시했습니다.
3) 가이드 데모: 아이디어 → 유튜브 아웃라인
가능한 것과 불편한 곳을 한 번에 보여주는 흐름을 복원해봅니다.
목표: 여러 agent가 협업해 바이럴 유튜브 제목을 뽑고, 사용자가 하나를 고르면, 그걸 바탕으로 아웃라인을 만들고, 피드백으로 수정합니다.
플로 개요:
- 입력: “OpenAI의 새 Agent Builder로 유튜브 영상을 만들고 싶다.”
- Agent A(Title Generator): 웹을 찾고, 10~20개의 제목을 JSON 리스트로 생성.
- Widget 표시: ChatKit 리스트 widget으로 보기 좋게 렌더.
- Approval: Approve vs Try again. 다시 뽑으면 A로 루프.
- 선택: Preview에선 클릭이 먹지 않으므로, 고른 제목을 텍스트로 붙여넣기.
- Agent B(Parse Title): 입력에서 제목만 추출해 state로 저장.
- Agent C(Outline Writer): 길이(예: 12~14분)·챕터·talking points·B‑roll 아이디어까지 포함한 아웃라인 작성.
현실 체크:
- Preview의 widget은 보기만 되고 상호작용 불가. “제목 선택”을 실제로 구현하려면 ChatKit embed + backend에서 widget event를 받아야 합니다.
- State가 관건. has_titles, chosen_title, outline 같은 flag를 저장해 다음 실행에서 다른 분기로 흘리세요.
- 경쟁 제품 중엔 state‑routing이 더 세련된 것도 있지만, 첫 버전치고는 쓸 만합니다.
4) State가 등뼈: Name‑Capture 패턴
Agent Builder는 Start 블록에서 state(string/list/object/boolean)를 선언합니다. Preview에선 중간에 새 텍스트를 끼워 넣기 어렵기 때문에, 재진입(re‑entry) 설계를 권합니다.
대표 패턴:
- State: name(string), name_found(boolean, 기본 false).
- Start에서 IF: name_found 확인.
- true면 메인 작업 agent로 라우팅.
- false면 Name Collection Agent로 이동.
- Name Collection Agent: “이름을 물어보고, 파싱해서 JSON으로 반환”이라는 instruction.
- Output: { name: string, name_found: boolean } 스키마.
- Set State: 반환값으로 name과 name_found: true 저장 후 End.
- 두 번째 메시지: 사용자가 질문하면 Start의 IF가 name_found === true를 보고 메인 agent로 보냅니다. 이제 이름으로 반겨줄 수 있죠.
이 재진입 구조 덕분에 “중간 입력 불가” 한계를 우회할 수 있고, 논리도 단단해집니다. 시각 편집기에서 가장 안정적인 패턴입니다.
5) Structured Output: JSON Schema와 Widgets
블록의 출력 형식은 Text, JSON, Widget을 지원합니다.
- JSON은 기계 친화적입니다. 예: name, name_found를 명시하면 아래 단계의 조건 분기가 쉬워집니다.
- Widget은 결과를 보기 좋게 보여줍니다. 표·카드·차트·폼·캘린더 등. 특히 ChatKit과 조합이 좋습니다.
Widget Builder 절차:
- Widget Builder 열기(날씨·날짜·리스트 등 갤러리 제공).
- AI로 위젯 생성: 예) “사용자 이름과 랜덤 팩트를 활기차게 보여주는 widget 만들어줘.”
- 생성된 widget에는 schema, light/dark 변형, code가 포함됩니다.
- widget을 다운로드해서 Agent Builder에 업로드.
- agent 출력 형식을 Widget으로 바꾸고, schema에 맞는 데이터를 전달.
Preview 결과: 위젯은 예쁘게 렌더됩니다. 다만 버튼/폼은 작동안 함—ChatKit embed + backend로 event를 처리해야 인터랙션이 살아납니다.
6) Tools·Connectors·MCP: 코드가 필요한 지점
Agent Builder는 tools와 MCP connectors를 참조할 수 있는데, 중요한 포인트가 있습니다.
- Tool Spec: 함수 스키마만 정의합니다(예: get_weather(zip: string)). 모델이 tool call을 내보낼 순 있지만, 런타임이 실행해주지 않습니다. 여러분의 backend가 콜을 가로채 실제 함수를 실행하고 결과를 돌려줘야 합니다.
- Client Tool: 개념은 유사하되 frontend 쪽에서 호출됩니다.
- MCP Connectors: Gmail, Google Calendar, Google Drive, PayPal 등. 하지만…
- Access token 발급이 수동이고 유효기간이 짧은 경우가 많습니다.
- UI 경로에선 OAuth 미지원. 보통 API key나 custom header가 필요합니다.
- 공개 MCP server 다수가 OAuth를 요구하므로 발이 묶일 수 있습니다.
- Custom MCP Server: HTTP MCP이며 API key/custom header 인증이면 연동 가능. OAuth flow는 여기서 불가.
결론: 연동은 가능하지만, 실서비스로 다듬으려면 직접 코드로 콜 실행·시크릿 관리·재시도 로직을 붙여야 합니다.
7) 검색·검색 증강: Vector Store와 File Search
Agent Builder의 File Search 블록은 OpenAI vector store에서만 동작합니다. 사용 흐름은 간단합니다.
- OpenAI 콘솔에서 vector store 생성.
- 파일 업로드 후 인덱싱.
- File Search 블록으로 RAG 질의.
커스텀 스토어·reranker·하이브리드 검색이 필요하면 Agents SDK로 가서 코드로 구현하세요.
8) 안전장치: Guardrails·Moderation·Fail‑Fast
Guardrails 블록은 입력을 **정화(sanitize)**하는 관문입니다.
- PII나 민감 패턴 제거.
- moderation/jailbreak 점검.
- 설정에 따른 hallucination 억제.
보통 **Start → Guardrail → (Pass면 계속 / Fail이면 End)**로 배선합니다. 위험한 입력이 tools에 닿기 전에 차단합니다.
9) Loops·Approval·Notes·토큰 비용
- User Approval: 버튼은 Approve/Reject 두 개만, 이름 변경 불가. 각 결과에 맞는 분기로 연결하세요.
- While Loop: 지원되지만 난도 높음. 탈출 조건을 명확히 하세요.
- Notes: 의사결정과 맥락을 남겨 협업 효율을 높입니다.
- 비용: Preview만으로도 토큰이 쑥쑥 나갑니다. Usage/Logs를 수시 확인하세요.
10) ChatKit 임베딩: 진짜 상호작용은 Backend에서
사이트에 ChatKit으로 agent를 embed할 수 있습니다. 장점은 다음과 같습니다.
- OpenAI 인프라에 agent를 호스팅.
- 대화 안에서 widgets로 풍부한 UI 제공.
- 단, 버튼 클릭/폼 제출/state 변화를 살리려면 backend에서 event를 받아 상태를 갱신하고 응답을 보내줘야 합니다.
개발 메모: 한 시점에 ChatKit Python SDK 레포가 README 없이 존재하기도 했습니다. 빠른 변화를 감안해 샘플 코드를 읽고 빈틈은 직접 glue code로 메우는 태도가 필요합니다.
11) Agents SDK로 코드 내보내기
시각 플로는 언제든 텍스트 표현으로 copy할 수 있습니다. agents·prompts·설정이 포함되고, 새 블록(예: Guardrail)을 추가하면 내보낸 코드도 즉시 반영됩니다.
Agents SDK로 실행하면:
- tool 실행, connectors, retrieval, observability를 온전히 소유합니다.
- Preview가 못 하는 미드‑플로 입력과 고급 로직도 구현할 수 있습니다.
- 배포/시크릿/스케일을 직접 통제합니다.
12) 평가와 Fine‑tuning: 성능을 측정하는 법
AgentKit에는 evaluation과 fine‑tuning 도구가 보입니다.
- dataset을 만들고 시나리오를 돌려 latency와 단계별 pass/fail을 측정.
- 모델을 grader로 써서 출력의 품질을 점수화하는 접근도 가능.
- 도메인에 맞춘 fine‑tuning 후, 동일 조건에서 재평가하세요.
13) 체감하는 한계들
- Preview의 widget 상호작용은 디스플레이 전용. 실전 UX는 embed + backend가 필수.
- Connectors 인증은 까다롭습니다. 수동 토큰·만료·UI 경로의 OAuth 부재 때문에 공개 MCP server 다수가 막힙니다.
- 미드‑플로 입력이 불가능합니다. 안전한 우회로는 re‑entry state 패턴.
- 문서 갭이 종종 보입니다. 실험·로그로 메우는 자세가 필요합니다.
그럼에도 Agent Builder는 stateful flow, structured output, guardrails, code export 등 핵심 구성요소를 갖췄습니다. 출발선으로 충분히 설득력 있습니다.
14) 베스트 프랙티스 & 디자인 패턴
1) State를 맨 앞에
has_titles, chosen_title, name_found 같은 flag를 Start에 두고, 첫 IF에서 분기해 재실행 시 정확한 경로를 보장하세요.
2) JSON Schema를 습관화
명시적 스키마가 조건문을 단순·견고하게 만듭니다.
3) Widget은 표현용, 로직은 아님
표·카드·차트는 렌더만. 상호작용은 ChatKit embed에서 처리.
4) Tool은 ‘계약’
Spec은 계약일 뿐. server handler로 실행을 이행하고, 로그와 타임아웃을 걸어 안정화하세요.
5) 입구를 지켜라
Guardrails를 Start 바로 뒤에. 실패면 즉시 End로 빠져 unsafe call을 차단.
6) 비용을 제어
프롬프트 다이어트, 중간 결과 캐시, reasoning depth 제한, Usage/Logs 모니터링.
7) 플로를 기록
Notes로 결정·가정·TODO를 남겨 팀 온보딩을 가볍게.
15) 튜토리얼: 데모를 그대로 재현하기
목표: “OpenAI Agent Builder” 주제로 제목을 브레인스토밍하고, 고른 제목으로 유튜브 아웃라인을 만드는 멀티‑agent 플로.
Step 1 — 새 agent 생성
Agent Builder → New Empty Agent
Step 2 — Start & state
has_titles: false, chosen_title: null, outline: null 추가.
Step 3 — Title Generator (Agent)
Instruction: OpenAI Agent Builder를 조사하고 CTR가 높은 다양한 제목을 제안하라. 결과는 JSON.
Output: JSON 배열 { title, angle, promise }.
선택: 최신성 위해 웹 검색 tool을 붙이고 backend에서 실제 실행.
Step 4 — Titles를 widget으로 표시
출력을 Widget으로 전환 → 리스트/그리드 widget 선택(또는 Widget Builder로 제작).
Preview에선 클릭만 되고 실제 선택은 불가.
Step 5 — Approval 게이트
User Approval 추가 → Approve는 진행, Reject는 Title Generator로 루프.
Step 6 — Preview용 선택 우회
사용자에게 선택한 제목을 텍스트로 붙여넣도록 안내.
**Agent(Parse Title)**로 { chosen_title } JSON을 뽑기.
Step 7 — State 설정 & 분기
chosen_title 저장, has_titles = true.
Step 8 — Outline Agent
Instruction: 12–14분 분량의 아웃라인. Hook, chapters, timestamps, talking points, B‑roll 아이디어 포함.
Output: Widget으로 렌더하면서 outline을 state에 저장해 이후 수정 루프 대비.
Step 9 — 수정 루프
User Approval: Approve → End. Reject → Revision Agent로 피드백 반영 후 outline 갱신.
Step 10 — 진짜 상호작용을 위해 embed
ChatKit embed로 위젯 클릭을 살리고, backend에서 이벤트와 tool call을 처리.
16) FAQ
Q. Preview에서 widget 클릭이 되나요?
A. 렌더만 됩니다. 버튼/폼은 작동안 합니다. ChatKit embed + backend가 필요합니다.
Q. Connectors는 OAuth를 지원하나요?
A. 관찰한 UI 경로에서는 OAuth 미지원. 보통 API key나 임시 access token이 필요합니다. 공개 MCP server 상당수가 OAuth를 요구해 제약이 있습니다.
Q. 미드‑플로 입력이 가능한가요?
A. Preview에선 불가. re‑entry state 패턴을 쓰거나 Agents SDK에서 직접 구현하세요.
Q. File Search는 OpenAI vector store에만 묶이나요?
A. 시각 블록 기준 그렇습니다. 다른 스토어는 Agents SDK로 구현하십시오.
Q. 비용은 어떻게 줄이나요?
A. 프롬프트 최소화, 중간 산출 캐시, reasoning depth 축소, Usage/Logs 모니터링이 기본입니다.
17) 마무리 생각
Agent Builder의 방향성은 분명합니다. Stateful, tool‑using agent가 보기 좋은 출력과 만납니다. 현실은 아직 초기—문서 공백, Preview 제약, Connector 인증 마찰이 남아 있죠. 하지만 backend를 기꺼이 손보는 팀이라면 오늘 당장도 빈칸을 메우고 인상적인 경험을 만들 수 있습니다.
더 넓게 보면, 여러 앱 위에 얹히는 통합 action layer(수백 개 앱을 안전하게 조작하고, Gmail/Notion/Slack/Salesforce/Calendar를 오케스트레이션하며, 선호를 기억하는 “AI 비서”)가 AgentKit의 canvas·widgets와 만나면 “똑똑한 대화”를 넘어 실제로 일을 끝내는 agent로 도약합니다.
지금은 이렇게 정리해봅니다: State를 먼저 설계하고, JSON schema로 출력 안정성을 확보하며, widgets로 표현을 다듬고, 필요하면 code export로 나아가 ChatKit embed로 상호작용을 완성하세요. Guardrails로 안전을 지키고, 실험하며 개선하면 다음 agent는 분명 더 나아질 겁니다.