> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/a2a/a2a-flowise-node.md).
# Flowise A2A 노드로 서브에이전트 호출
A2A(Agent-to-Agent)는 독립적으로 배포된 워크플로우를 에이전트로 공개하고, 다른 워크플로우가 프로토콜로 작업을 위임하는 기능입니다. `Agent` 노드는 모델이 대상을 동적으로 선택하고, `A2A Agent` 노드는 그래프에 지정한 대상을 항상 실행합니다.
* 워크플로우 배포 시 Agent Card 자동 생성
* Agent 노드의 동적 선택과 A2A Agent 노드의 결정론적 실행
* 독립 작업 병렬 실행과 의존 작업 순차 실행
* 같은 A2A Task를 이용한 멀티턴 대화
* 사용자 확인 요청(HITL)과 진행 상황 중계
* 내부 에이전트와 외부 A2A URL 지원
## 1. MCP와 A2A의 차이
| 구분 | MCP Tool | A2A Sub-agent |
| ------ | --------------- | ----------------------------------------------- |
| 목적 | 단일 기능 실행 | 자율 에이전트에 작업 위임 |
| 상태 | 일반적으로 무상태 | Task ID와 Context ID로 상태 유지 |
| 실행 | Flowise Tool 실행 | A2A Runtime의 `message/send` 또는 `message/stream` |
| 사용자 확인 | 호출 전 정적 승인 | 실행 중 `input-required` 처리 |
| 적합한 예 | 환율 조회, 단순 계산 | 문서 조사, 상담, 승인 포함 업무 |
Agent 노드에서는 **Tools**와 \*\*서브에이전트(A2A)\*\*를 별도 항목으로 설정합니다. 모델 선택에는 같은 function-calling 형식을 사용하지만, 실제 실행·상태·SSE·화면 표시는 서로 분리됩니다.
## 2. 워크플로우를 A2A 에이전트로 공개
1. 워크플로우 상세의 **A2A 에이전트** 탭을 엽니다.
2. **A2A 에이전트로 노출**을 켭니다.
3. 이름, 설명, Capabilities를 입력합니다. 이름을 비우면 워크플로우 이름을 사용합니다.
4. 워크플로우를 배포합니다.
배포 시 Agent Card가 생성되며 **도구 > A2A 에이전트**에서 확인할 수 있습니다. MCP 도구가 활성화된 워크플로우는 관련 정보가 Agent Card의 skills에 추가됩니다.
> 설정 저장만으로는 Agent Card가 생성되지 않습니다. 이미 배포된 워크플로우에서 A2A 노출을 새로 켰다면 다시 배포하세요.
## 3. Agent 노드에 서브에이전트 연결
마스터 워크플로우는 다음처럼 구성합니다.
```
Start → Agent
```
Agent 노드의 \*\*서브에이전트(A2A)\*\*에서 행을 추가하고 호출 대상을 선택합니다.
| 설정 | 설명 |
| ------------------ | ------------------------------------------- |
| 에이전트 소스 | `GenOS 내부(에이전트)` 또는 `외부 URL` 선택 |
| 서브에이전트 | 내부에 배포된 A2A 에이전트 선택 |
| 외부 에이전트 URL | 외부 Agent Card와 JSON-RPC 엔드포인트가 있는 기준 URL 입력 |
| 사용자 확인 요청 전달(HITL) | `input-required` 요청을 마스터 채팅의 확인 화면으로 전달 |
| 진행 상황 실시간 중계 | 서브에이전트의 상태와 중간 결과를 마스터 채팅에 중계 |
Agent 노드의 서브에이전트 설정
선택하지 않은 행은 실행 시 무시됩니다. 이름, 설명, skills는 Agent Card에서 읽으며 별도로 입력하지 않습니다.
### 3.1 공통 옵션
| 설정 | 설명 |
| --------------- | --------------------------------------------- |
| 서브에이전트 동시 호출 수 | 같은 모델 응답에 포함된 A2A 호출의 최대 동시 실행 수. `1`이면 순차 실행 |
| 서브에이전트 시스템 프롬프트 | 마스터 모델의 서브에이전트 선택, 순차·병렬 판단, 중복 호출 방지 규칙 |
| 서브에이전트 설명 프롬프트 | 각 서브에이전트에 전달할 `message` 작성 규칙 |
두 프롬프트는 노드에서 직접 수정할 수 있으며 비우면 해당 프롬프트를 추가하지 않습니다.
### 3.2 프롬프트 조립 위치
**서브에이전트 시스템 프롬프트**는 Agent 노드에 설정한 System 메시지 뒤에 별도의 System 메시지로 추가됩니다. 유효한 A2A 서브에이전트가 하나 이상 있을 때만 마스터 모델에 전달됩니다.
```
Agent System 메시지
→ 서브에이전트 시스템 프롬프트
→ 대화 기록과 현재 사용자 메시지
```
**서브에이전트 설명 프롬프트**는 Agent Card에서 읽은 설명과 skills 뒤에 붙습니다. 완성된 설명은 function-calling description으로 마스터 모델에 전달됩니다.
```
Agent Card 설명 + skills
→ 서브에이전트 설명 프롬프트
→ function description
```
두 프롬프트 모두 마스터 모델의 판단에만 사용됩니다. 실제 서브에이전트에는 마스터가 생성한 `message` 인자만 전송됩니다.
## 4. 호출 방식
마스터 모델은 사용자 요청, Agent Card, 프롬프트를 보고 호출 여부와 대상을 결정합니다.
* 이미 답할 수 있거나 관련 에이전트가 없으면 호출하지 않습니다.
* 앞 호출 결과가 다음 입력에 필요하면 결과를 받은 다음 모델 라운드에서 호출합니다.
* 서로 독립적인 호출을 같은 모델 응답에 생성하면 동시 호출 상한 안에서 병렬 실행합니다.
* 모든 호출 결과는 원래 tool-call 순서로 모델 대화에 다시 추가됩니다.
예를 들어 문서에서 필드 수를 찾은 뒤 그 숫자를 계산에 사용해야 한다면 `문서 에이전트 → 계산 에이전트` 순서로 실행됩니다. 문서 검색과 독립적인 계산은 `(문서 에이전트, 계산 에이전트)`로 병렬 실행할 수 있습니다.
## 5. A2A Agent 노드로 순서 고정
모델이 대상을 고르게 하지 않고 반드시 특정 에이전트를 실행하려면 **A2A Agent** 노드를 사용합니다.
```
Start → A2A Agent(문서 검색) → A2A Agent(계산)
```
두 A2A Agent 노드를 순서대로 연결한 워크플로우
각 노드는 대상 하나를 정확히 한 번 호출합니다. 여러 에이전트의 실행 순서는 연결한 그래프가 결정합니다. 두 번째 노드의 **메시지**를 비우면 첫 번째 노드의 응답을 그대로 입력으로 사용하고, 직전 출력이 없으면 원 질문을 사용합니다.
| 설정 | 설명 |
| ------------------ | -------------------------------------- |
| 에이전트 소스 / 대상 에이전트 | 내부 Agent Card 하나 또는 외부 URL 하나 선택 |
| 메시지 | 직접 보낼 요청. 비우면 직전 출력, 최초 질문 순으로 자동 선택 |
| 진행 상황 실시간 중계 | 상태·메시지·아티팩트·내부 Tool 관측을 A2A 전용 SSE로 중계 |
| 사용자 확인 요청 전달(HITL) | 사용자 입력이나 승인 요청을 Flowise 확인 화면으로 전달 |
| 인증 정보 / 추가 헤더 | 내부 Auth Key 또는 외부 인증 정보와 추가 헤더 설정 |
| 제한 시간 / 프로토콜 호환 모드 | 호출 제한 시간과 프로토콜 호환 방식 설정 |
이 노드는 function calling을 사용하지 않으므로 모델의 Tool call 지원 여부와 관계없이 동작합니다. 다중 대상, 병렬 모드, 동적 대상 변수는 노드 옵션으로 제공하지 않습니다. 병렬 또는 조건 분기는 AgentFlow 그래프로 구성합니다.
### 5.1 메시지 입력 규칙
**메시지**는 선택한 A2A 에이전트에 전송되는 실제 요청 본문입니다. 다음 순서에서 처음 확인되는 값을 사용합니다.
```
메시지에 직접 입력한 값
→ 직전 노드의 응답(output.content)
→ 최초 사용자 질문
```
* `Start → A2A Agent`에서 메시지를 비우면 최초 사용자 질문을 전달합니다.
* `Start → A2A Agent 1 → A2A Agent 2`에서 2번 노드의 메시지를 비우면 1번 에이전트의 응답을 전달합니다.
* 메시지를 직접 입력하면 직전 노드 응답과 최초 질문보다 우선합니다.
* Flowise 변수를 사용하면 변수가 해석된 결과가 메시지로 전달됩니다.
A2A Agent의 대상과 메시지 전달 규칙
직전 결과를 다음 단계가 그대로 이해하기 어려운 경우에는 메시지에 대상, 작업, 출력 형식을 구체적으로 입력하거나 별도의 변환 노드를 연결하세요.
## 6. 멀티턴과 사용자 확인
Agent 노드는 서브에이전트가 반환한 Task ID와 Context ID를 Flowise 세션의 `state.a2a`에 저장합니다. 같은 세션의 후속 요청은 저장된 상태를 사용해 대화를 이어갑니다.
서브에이전트가 `input-required` 또는 `auth-required`를 반환하면 다음처럼 처리합니다.
* **HITL 켬**: 마스터 실행을 `STOPPED`로 저장하고 사용자에게 확인 UI를 표시합니다. 사용자 응답을 받으면 저장된 Task로 재개합니다.
* **HITL 끔**: 중단하지 않고 결과를 마스터 모델에 전달해 모델이 다음 행동을 결정합니다.
현재 지원하는 HITL 컴포넌트는 다음과 같습니다.
| 컴포넌트 | 화면 |
| --------------- | --------------------- |
| `confirm` | 진행 또는 거절 버튼 |
| `single-select` | 하나만 선택하는 radio button |
| `multi-select` | 여러 개를 선택하는 checkbox |
HITL을 켜면 서브에이전트에 사용자 입력 요청 Tool이 자동으로 제공됩니다. 선택형 컴포넌트에는 마지막 항목으로 `직접 입력`이 추가되며, 입력란은 최대 다섯 줄까지 늘어납니다. 요청·응답 형식과 화면 예시는 A2A HITL UI Extension v1을 참조하세요.
## 7. Relay와 관찰성
진행 상황 실시간 중계를 켜면 서브에이전트의 상태, 메시지, 아티팩트와 내부 Tool 관측 이벤트가 `agentId`와 함께 A2A 전용 SSE로 전달됩니다. 채팅과 실행 상세에서는 일반 Tool과 별도의 **A2A Agents** 항목으로 표시됩니다.
마스터 요청의 W3C `traceparent`와 GenOS subject header는 A2A 요청에도 전달됩니다. Langfuse에서는 마스터 모델, A2A gateway, 서브 워크플로우 실행을 같은 trace에서 확인할 수 있습니다.
## 8. 인증과 외부 에이전트
| 경로 | 인증 |
| ----------------------------- | -------------------------------------- |
| 외부 클라이언트 → GenOS A2A 에이전트 | 워크플로우 Auth Key 필요 |
| GenOS 내부 Agent → 내부 Sub-agent | 내부 mesh 호출로 처리 |
| Agent Card discovery | 인증 불필요 |
| 외부 URL Sub-agent | 외부 에이전트 정책에 따름 |
| A2A Agent 노드의 외부 URL | Genos A2A API Credential 또는 Headers 사용 |
외부 URL은 Agent Card discovery가 가능한 기준 URL을 입력합니다. 프로토콜 버전은 카드에서 자동 판별하며 GenOS 내부 대상은 v0.3 호환 모드로 실행됩니다.
## 9. 문제 해결
**Sub-agent 목록이 비어 있습니다.**
대상 워크플로우의 A2A 노출을 켜고 다시 배포했는지, 현재 워크스페이스에서 해당 리소스에 접근할 수 있는지 확인하세요.
**저장한 설정과 배포된 동작이 다릅니다.**
워크플로우 revision에 최신 Agent flowData가 포함됐는지 확인하고 새 revision을 배포하세요.
**불필요한 호출이나 상대 표현이 발생합니다.**
서브에이전트 시스템 프롬프트와 서브에이전트 설명 프롬프트를 업무에 맞게 조정하세요. 설명 프롬프트에는 서브에이전트가 이전 호출 결과를 볼 수 없으므로 필요한 실제 값을 `message`에 모두 포함해야 한다고 명시하는 것이 좋습니다.
**같은 요청의 두 서브에이전트가 병렬로 실행되지 않습니다.**
동시 호출 상한이 `2` 이상인지 확인하세요. 모델이 두 호출을 서로 다른 응답 라운드에 생성하면 의존 호출로 간주되어 순차 실행됩니다.
**Tool call을 지원하지 않는 모델을 사용합니다.**
Agent 노드의 동적 A2A 선택은 사용할 수 없습니다. 대상을 미리 지정한 `A2A Agent` 노드를 연결해 결정론적으로 실행하세요.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/a2a/a2a-flowise-node.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.