노드 레퍼런스

노드 레퍼런스 (Node reference)

Agent Builder는 에이전트 워크플로를 구성하는 비주얼 캔버스예요. 워크플로는 노드와 연결로 이루어져 있고, 이 연결이 시퀀스와 흐름을 제어해요. 노드를 삽입하고 설정하며 연결해서 에이전트가 따라야 할 프로세스를 정의하면 돼요.

출처: 문서

본문

참고로 OpenAI는 Agent Builder를 단계적으로 폐지(deprecating)하고 있어요. 기존 사용자는 전환 기간 동안 계속 쓸 수 있고, 제품은 2026년 11월 30일에 종료될 예정이에요. ChatKit은 계속 사용할 수 있어요. 최신 일정은 폐지 페이지를 확인하세요.

아래에서 사용 가능한 모든 노드를 살펴보세요. 더 자세한 내용은 Agent Builder 가이드를 읽어 보세요.

핵심 노드 (Core nodes)

기본 구성 요소부터 시작해 볼게요. 모든 워크플로에는 start 노드와 agent 노드가 있어요.

Start

워크플로에 대한 입력을 정의해요. 채팅 워크플로에서 사용자 입력을 받을 때 start 노드는 두 가지를 처리해요.

• 사용자 입력을 대화 기록(conversation history)에 추가
• 이 입력의 텍스트 내용을 나타내는 input_as_text 노출

모든 채팅 start 노드는 입력 변수로 input_as_text를 가져요. 상태 변수(state variables)도 추가할 수 있어요.

Agent

지시 사항(instructions), 도구(tools), 모델 구성을 정의하거나 평가(evaluations)를 연결할 수 있어요.

각 에이전트는 범위를 명확하게 유지하는 게 중요해요. 숙제 도우미 예시를 보면, 한 에이전트는 사용자 질문을 지식 베이스에 더 적합하고 관련성 있게 다시 쓰는 역할을 하고, 다른 에이전트는 질문을 Q&A인지 사실 조회인지 분류하며, 또 다른 에이전트가 각 유형의 질문을 처리해요.

다른 모델 프롬프트처럼 모델 동작 지시 사항과 사용자 메시지를 추가할 수 있어요. 이전 단계의 출력을 파이프로 연결하고 싶다면 그 출력을 컨텍스트로 추가하면 돼요.

agent 노드는 원하는 만큼 많이 둘 수 있어요.

Note

워크플로에 대한 주석과 설명을 남기는 노드예요. 다른 노드와 달리 note는 흐름에서 아무것도 하지 않아요. 다만 여러분과 팀을 위한 유용한 설명일 뿐이죠.

도구 노드 (Tool nodes)

도구 노드를 사용하면 에이전트에 도구와 외부 서비스를 장착할 수 있어요. 데이터를 조회하고, 오용을 모니터링하며, 외부 서비스에 연결할 수 있답니다.

File search

OpenAI 플랫폼에서 만든 벡터 저장소(vector stores)에서 데이터를 조회해요. 벡터 저장소 ID로 검색하고, 모델이 검색해야 할 내용을 쿼리로 추가하게 돼요. 워크플로의 이전 노드 출력을 포함하려면 변수를 사용할 수 있어요.

벡터 저장소를 설정하고 지원되는 파일 유형을 보려면 file search 문서를 확인하세요.

OpenAI 호스팅 저장소 밖을 검색하려면 MCP를 대신 사용하세요.

Guardrails

개인 식별 정보(PII), 탈옥(jailbreaks), 환각(hallucinations) 등 원치 않는 입력을 위한 입력 모니터를 설정해요.

Guardrails는 기본적으로 pass/fail 방식이에요. 이전 노드의 출력을 테스트하고, 다음에 무슨 일이 일어날지를 정의하게 되죠. guardrails가 실패하면 워크플로를 끝내거나, 안전한 사용을 상기시키면서 이전 단계로 되돌아가는 것을 권장해요.

MCP

타사 도구와 서비스를 호출해요. OpenAI 커넥터나 타사 서버에 연결하거나, 자체 서버를 추가할 수 있어요. MCP 연결은 Gmail이나 Zapier 같은 다른 애플리케이션의 데이터를 읽거나 검색해야 하는 워크플로에서 유용해요.

Agent Builder에서 옵션을 찾아볼 수 있어요. MCP에 대해 더 알아보려면 MCP 문서를 확인하세요.

로직 노드 (Logic nodes)

로직 노드를 사용하면 사용자 지정 로직을 작성하고 제어 흐름을 정의할 수 있어요. 예를 들어 사용자 지정 조건으로 반복하거나, 작업을 계속하기 전에 사용자 승인을 요청하는 식이에요.

If/else

조건부 로직을 추가해요. Common Expression Language (CEL)를 사용해 사용자 지정 표현식을 만들 수 있어요. 분류된 입력을 어떻게 처리할지 정의할 때 유용해요.

예를 들어 에이전트가 입력을 Q&A로 분류하면 그 쿼리를 Q&A 에이전트로 보내 간단한 답변을 받는 식이에요. 열린 질문이면 관련 사실을 찾는 에이전트로 보내요. 그 외의 경우엔 워크플로를 종료합니다.

While

사용자 지정 조건에서 반복해요. Common Expression Language (CEL)를 사용해 사용자 지정 표현식을 만들 수 있어요. 조건이 여전히 참인지 확인할 때 유용해요.

Human approval

최종 사용자(end-user)의 승인을 받기 위해 대기해요. 에이전트가 작성한 작업이 나가기 전에 사람의 리뷰를 거치기를 원할 때 유용해요.

예를 들어 에이전트가 여러분을 대신해 이메일을 보내는 워크플로를 그려 볼게요. 이메일 위젯을 출력하는 agent 노드를 두고, 그 바로 다음에 human approval 노드를 배치해요. human approval 노드를 "이 이메일을 보내 드릴까요?"라고 묻도록 구성할 수 있고, 승인되면 Gmail에 연결하는 MCP 노드로 진행하게 됩니다.

데이터 노드 (Data nodes)

데이터 노드로 워크플로에서 데이터를 정의하고 조작할 수 있어요. 출력을 재구성하거나 워크플로 전체에서 쓰일 전역 변수를 정의하게 돼요.

Transform

출력을 재구성해요 (예: object → array). 스키마에 맞춰 타입을 강제하거나, 에이전트가 입력으로 읽고 이해하기 좋게 출력을 재구성할 때 유용해요.

Set state

워크플로 전체에서 사용할 전역 변수를 정의해요. 에이전트가 입력을 받고 새 무언가를 출력해서 워크플로 전반에서 계속 쓰고 싶을 때 유용해요. 그 출력을 새 전역 변수로 정의하면 됩니다.

더 알아보기 (Learn more)

관련 문서: Agent Builder 가이드, file search, MCP를 함께 보면 도움이 돼요.