A2A 멀티에이전트

01

무엇이 나오는가

이메일 주소가 올바른지 검사하는 함수를 만들어줘 — 이 한 줄을 넣고 받은 실행 결과입니다. 아래 코드와 비용은 그 실행에서 그대로 옮겼습니다.

[사람]      이메일 주소가 올바른지 검사하는 함수를 만들어줘
[검증자]    반려 · [docstring] docstring 이 없는 함수: test_valid_emails, …
[검증자]    통과
[실무자]    결과 제출
[관리자]    결과 제출

import re
import unittest

def is_valid_email(email: str) -> bool:
    """Determine whether the provided string is a valid email address."""
    if email is None:
        return False
    if not isinstance(email, str):
        return False
    local_part  = r"(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[…]+)*)"
    domain_part = r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?…)"
    regex = re.compile(rf"^{local_part}@{domain_part}$", re.IGNORECASE)
    if not regex.match(email):
        return False
    domain = email.split("@", 1)[1]
    if "." not in domain:              # 도메인에 점이 하나는 있어야 한다
        return False
    …

class TestIsValidEmail(unittest.TestCase):
    def test_valid_emails(self):
        """Test that a variety of valid emails are recognized."""
        valid_emails = ["simple@example.com", "x@example.com",
                        "user.name+tag+sorting@example.com", …]   # 9개
        for email in valid_emails:
            with self.subTest(email=email):
                self.assertTrue(is_valid_email(email))

    def test_invalid_emails(self):                                 # 12개
        invalid_emails = ["plainaddress", "@missinglocal.org",
                          "john..doe@example.com", "A@b@c@example.com", …]
        …

────────────────────────────────────────────────────────
  재작업 1회 · 검증 2회 · 호출 5회 · 토큰 4431/2278 · 비용 1.59원

02

A2A 프로토콜

A2A 는 에이전트끼리 일을 주고받기 위한 공개 표준입니다. 이 시스템이 쓰는 것은 셋입니다 — SendMessage(일을 맡긴다), GetTask(진행을 묻는다), 그리고 부르기 전에 상대가 무엇을 할 수 있는지 확인하는 Agent Card 입니다. 이 셋만 지키면 서로의 속을 몰라도 함께 일할 수 있습니다.

이 시스템이 표준의 어디까지 지키나

표준 문서는 a2a-protocol.org 에 있습니다. Google Codelab 은 구버전(v0.3)이고 현행은 v1.0 입니다. 둘은 메서드 이름과 Agent Card 경로가 달라 섞으면 통신이 되지 않습니다 — 그래서 서버가 양쪽을 다 받습니다.

03

계층 격리

에이전트 하나의 영향 범위를 최소화하는 구조입니다. A2A 표준에는 에이전트끼리의 통신을 제한하는 기능이 없습니다. 그래서 부르는 쪽과 받는 쪽 양쪽에서 막았습니다.

통신 허용표

직접 확인하는 법

에이전트를 띄운 상태에서, 관리자인 척하고 검증자를 직접 불러 보십시오.

curl -X POST http://127.0.0.1:8003/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"t1","method":"SendMessage","params":{"message":
      {"role":"ROLE_USER","content":[{"text":"검사해줘"}],"messageId":"m1",
       "metadata":{"issued_by":"manager"}}}}'

── 실제 응답 ──
{"jsonrpc": "2.0", "id": "t1", "error": {"code": -32010,
 "message": "'reviewer' 는 'manager' 의 요청을 받지 않는다. 허용: ['worker']"}}

04

검증과 재작업

검증자는 실무자보다 상위 권한입니다. 반려를 실무자가 요약하거나 눌러버릴 수 없고, 상태를 통과로 올릴 수도 없습니다. 재작업 횟수는 관리자가 예산으로 내려보내는 것이 아니라 실무자가 자기 횟수만 셉니다.

검증자가 하는 일 — 세 단계

실행 검사의 격리 범위

별도 인터프리터 · -I(환경변수와 사용자 설정 무시) · 임시 디렉토리 · 시간 제한 5초. 네트워크와 파일 시스템까지는 막지 않습니다 — 그것은 컨테이너의 몫이라 상용 단계에서 붙입니다. 검사 항목과 시간 제한은 검증자 설정에서 조절하고, require_tests 를 켜면 테스트가 없는 산출물을 반려합니다.

판정 서명 — 실무자가 바꿀 수 없게

두 가지 제약이 여기서 만납니다 — 검증자가 상위 권한이라는 것과 관리자는 검증자를 부를 수 없다는 것입니다. 둘을 같이 지키면 빈 자리가 하나 생깁니다. 판정은 실무자를 거쳐 올라오는데, 격리 때문에 관리자가 검증자에게 "정말 당신이 이렇게 판정했습니까" 하고 물어볼 길이 없습니다.

지금까지 이 자리를 지킨 것은 "실무자는 편집 없이 그대로 첨부한다"는 약속뿐이었습니다. 약속은 우리 코드가 지키는 것이지 강제되는 것이 아닙니다 — 타사 에이전트가 실무자 자리에 들어오면 그대로 무너집니다.

표준 라이브러리만 씁니다. 키가 비어 있으면 아무 일도 하지 않습니다 — 지금까지와 완전히 같습니다(로컬 데모 기본값). 켜는 것은 배치가 정하고, 상용에서는 채웁니다. 켠 뒤에는 서명이 없는 판정도 사유가 되어, 떼어내는 것으로 검사를 피할 수 없습니다.

05

전문 실무자

실무자를 종류별로 둘 수 있습니다. 자바 실무자, HTML 실무자처럼요. 관리자는 이름을 코드에 갖고 있지 않고 Agent Card 를 읽어 맞는 상대를 고릅니다. 종류를 늘리는 일은 설정 파일 하나 + 관리자 목록 한 줄로 끝나고, 에이전트 코드는 한 줄도 달라지지 않습니다.

설정 한 장이 실무자의 역할을 정합니다

# 자바 실무자 — 카드에 java 를 내건다
skills:
  - id: implement.java
    name: 자바 메서드 구현
    description: 자바로 코드와 JUnit 테스트를 작성한다
    tags: [java]
    examples:
      - '두 수를 더하는 add 메서드를 작성하라'

# 나에게만 주는 지시 — 산출물이 역할을 실제로 지키게 한다
instruction: '반드시 자바(Java)로 작성한다. public class 와 JUnit 테스트를 포함한다.'

tags 가 관리자가 보는 자리입니다. examples 는 상대가 카드만 보고 우리를 부를 수 있게 하는 자리이고, 검증 항목이 이 예시를 그대로 보내 실제로 되는지 확인합니다 — 동작하지 않는 예시는 넣을 수 없습니다.

개발이 아닌 일도 같은 구조로 돕니다

에이전트가 무엇을 하는 사람인지도 설정이 정합니다. 코드는 그릇이고, 무엇을 담을지는 설정이 정합니다. 그래서 같은 코드로 개발팀이 아닌 팀도 세울 수 있습니다.

역할을 바꾸는 일은 설정 파일을 더하거나 지우고 관리자 목록에서 한 줄 고치는 것으로 끝납니다. DBA·설계자 같은 자문 역할도 같은 방법으로 세웁니다 — 설정 예시를 매뉴얼에 실었습니다. 상담처럼 기계로 검사할 수 없는 일은 검증 루프를 아예 끄는 것도 설정 한 줄입니다 — 다만 그때는 기계가 대신 봐 줄 수 없다는 점을 알고 쓰셔야 합니다.

06

분배와 집계

한 지시를 여러 실무자에게 분배하고 결과를 종합합니다. 실무자 쪽과 검증자 쪽 양쪽 모두 여럿을 수용하며, 집계 규칙은 서로 다릅니다.

배치를 골라 띄웁니다 — 코드를 고치지 않습니다

동봉한 배치는 셋입니다 — 1x1x1(3) · roles(5) · 1x3x123(10). 배치를 바꾸는 데 코드를 고치지 않습니다. 명령에 이름만 줍니다.

a2a sets                       쓸 수 있는 배치 보기 — 로컬과 서버를 한 화면에
a2a run --list --set 1x3x123   띄우지 않고 무엇이 뜰지만 본다
a2a start --set 1x3x123        10 노드로 기동 — 화면까지 함께 뜬다

포트 블록이 갈려 있어 셋을 동시에 띄울 수도 있습니다. 이름·포트 충돌은 기동하기 전에 잡습니다. 실무자를 하나 더 늘리시려면 설정 파일을 복사해 이름과 포트만 바꾸고, 부르는 쪽 목록에 한 줄 더하면 됩니다.

07

전달 방식

세 가지 전달 방식을 같은 규격으로 추상화했고, 세 가지를 동시에 쓸 수 있습니다. 어느 구간에 무엇을 쓸지는 설정 한 줄이 정합니다.

08

기록과 이어하기

결과물과 과정을 기록으로 남겨 재사용합니다. 실행이 파일로 남고, 같은 대화에서 추가 지시를 하면 지난 산출물이 실려 갑니다. 서버를 재시작한 뒤에도 그렇습니다.

데이터베이스를 쓰지 않은 이유

작업 기록은 중첩된 문서라 관계형으로 쪼갤 것이 아니면 결국 JSON 칸 하나가 됩니다. 저장한 형식이 통신 형식 그대로라 스키마가 없고, 구조가 바뀌어도 이전 작업이 필요 없습니다. 무엇보다 사람도 AI 도 그냥 열어 읽을 수 있습니다. 기록이 수만 건이 되어 조회가 필요해지면 고칠 파일은 하나입니다.

쓰다 만 파일이 남지 않도록 임시 파일에 쓰고 한 번에 바꿔치기합니다. 기록이 깨져도 그 건만 건너뛰고 에이전트는 죽지 않습니다. 보관 한도(max_runs)를 주면 오래된 것부터 지웁니다 — 하루 이상 돌려 보실 때 디스크가 차지 않게 하기 위해서입니다.

09

비용

키 없이 도는 경로가 있지만 거기서는 쓸 만한 코드가 나오지 않습니다. 실제로 쓸 때 드는 비용을 먼저 적습니다.

100번 돌려도 200원 안쪽입니다. 단가는 설정한 모델을 따라가지 않으므로, 모델을 바꾸면 표시 금액도 함께 손봐야 합니다.

동작방식 셋

def handle_request(data):
    """이메일 주소가 올바른지 검사하는 함수를 만들어줘"""
    if data is None:
        raise ValueError("data 가 필요하다")
    return True          # 무엇을 넣든 참이다 — 검사하지 않는다


def test_handle_request():
    assert handle_request("data") is True   # 스스로 만든 틀을 스스로 통과시킨다

비용이 새지 않게 하는 장치

0 을 넣으면 해당 제한이 풀립니다. 코드에 박힌 상한은 없습니다. 상한에 걸리면 조용히 멈추지 않고 사유를 남기고 실패로 보고합니다. 키가 없거나 패키지가 없으면 자동으로 무료 동작방식으로 내려가 시연이 죽지 않습니다.

10

화면

왼쪽이 무엇을 시켰는가, 가운데가 누가 무엇을 했는가, 오른쪽이 결과와 판단입니다. 아래는 오늘 실제로 돌려 찍은 화면입니다.

언어는 어떻게 정해지나

언어를 지정하지 않으면 파이썬입니다. "두 수를 더하는 함수를 만들어주세요" 는 파이썬으로 나옵니다. 다른 언어는 지시문에 적습니다 — "C# 으로", "자바로".

무슨 언어인지는 코드가 알아내지 않습니다. 지시문이 그대로 모델에게 전달되어 모델이 읽고 정합니다 — 코드가 먼저 정해 버리면 모델의 판단과 어긋날 수 있기 때문입니다. 코드가 가리는 것은 딱 하나, "기계 검사 도구를 가진 언어인가" 입니다. 기본 검증자의 정적 검사가 파이썬 문법 분석기라 자바 코드를 넣으면 무조건 문법 오류가 납니다. 그래서 파이썬이 아니면 기계 검사를 건너뛰고 건너뛰었다고 적습니다. 언어별 검증자를 세우면 그 검증자가 자기 기준으로 봅니다 — 자바·HTML 검증자가 그렇게 돌고 있습니다. 다만 그 판정은 코드를 읽은 결과이지 돌려 본 결과는 아닙니다.

화면 구성

11

사용법

키가 없어도 전부 돕니다. Python 3.13 이상이 필요합니다.

a2a setup

a2a start

────────────────────────────────────────────────
  reviewer       127.0.0.1:8003  수신 ['worker'] (끝단)
  worker         127.0.0.1:8002  수신 ['manager'] → reviewer
  manager        127.0.0.1:8001  수신 ['console'] → worker
  GUI(config)    :8080  사용자 인터페이스 (HTTP)
────────────────────────────────────────────────

python -m console.cli "로그인 검증 함수를 만들어줘"

a2a stop

키를 넣는 곳

쓸 만한 코드를 받으시려면 키가 필요합니다. 프로젝트 맨 위 .env 파일에 두 줄을 넣습니다. 키는 직접 발급하며 저장소 어디에도 들어가지 않습니다.

OPENAI_API_KEY=sk-...       # 발급받은 키
BRAIN=openai                # 이 줄이 없으면 키가 있어도 무료 경로로 돕니다

키가 없거나 잘못되면 자동으로 무료 경로로 내려가 시연이 중간에 죽지 않습니다. 발급 절차는 별도 안내서로 드립니다.

지난 실행을 꺼내 쓰기

CLI 와 화면이 같은 기록을 봅니다. 화면에서 돌린 것을 CLI 로 이어갈 수 있습니다.

python -m console.cli --list                 지난 실행 목록
python -m console.cli --show <번호>          하나 자세히
python -m console.cli --resume <번호> "…"    이어서 지시 — 그때 산출물이 실려 간다
python -m console.cli --agents               에이전트 생사 확인

설정 한 장에 들어가는 것

에이전트마다 자기 설정 하나만 읽습니다. 전체 배치를 아는 파일은 없습니다.

# 관리자 — 검증자 주소가 어디에도 없다
self:         { name: manager, bind: 127.0.0.1, port: 8001 }
accepts_from: [console]              # 이 발신자만 받는다
delegates:
  - { name: worker, url: "http://127.0.0.1:8002",
      delivery: polling }            # 이 상대에게만 적용된다
limits:       { max_depth: 5, max_llm_calls: 4 }
auth:         { token: "" }          # 비면 토큰 검사 안 함
store:        { dir: ./_data, enabled: true }

이름·포트·바인드가 전부 설정에 있습니다. 코드에 이름 상수가 없어서, 같은 실무자를 둘 띄우려면 설정을 복사해 이름과 포트만 바꿉니다 — 코드 복제가 아닙니다.

12

기술 선택

에이전트 사이는 A2A 표준, 안쪽은 State Machine

두 축을 분리한 것이 이 구현의 핵심 판단입니다. 층이 다르므로 서로 경쟁하지 않습니다. 에이전트 사이를 State Machine 으로 이으면 모두가 같은 상태를 보게 되어, "관리자 ↔ 검증자 불가"가 규약으로만 남습니다.

A2A 규약을 무엇까지 지키나

복잡한 규격 타입은 파일 한 곳에 가둬 두어 에이전트 코드에는 나오지 않습니다. 추가 개발을 AI 에게 맡기실 때 규격을 몰라도 되도록 한 조치입니다. 검증 방법은 눈으로 보는 것이 아니라, 우리 서버가 내보낸 형식을 표준 라이브러리로 되읽어 원본과 같은지 확인하고 그 검사를 회귀 테스트에 넣었습니다. 사람이 읽고 해석하는 것보다 정확하기 때문입니다.

함수 하나를 넘어 — 여러 파일

"Spring Boot 로 기본 프로그램을 짜라"를 실제로 돌려 한계를 확인했습니다. 검증자는 제대로 일했습니다 — pom.xml 과 설정 파일이 없다고 정확히 짚어 반려했습니다. 막힌 곳은 판단이 아니라 산출물의 그릇이었습니다. 한 파일 안에 함수 하나를 담도록 못박혀 있어 디렉터리를 표현할 방법이 없었습니다.

지금은 여러 파일을 한 번에 냅니다. A2A 의 Data Model 에는 파일명을 담을 자리가 없고 거기에 필드를 더하면 사양에서 벗어나므로, 본문 안에 파일 경계를 표시하는 방식을 골랐습니다. 사양을 건드리지 않고 프로젝트 골격을 나를 수 있습니다.

=== FILE: pom.xml ===
<project>…</project>

=== FILE: src/main/java/com/example/DemoApplication.java ===
package com.example;
…

함수 하나를 요청하면 예전 그대로 나옵니다. 기존 경로를 뜯지 않는 것이 조건이었고, 회귀 테스트가 그것을 확인합니다. 계층 격리 · 검증자 우위 · 비용 0원 경로도 그대로입니다. 다만 이 기능은 보내 드린 견적의 범위 밖이라는 점을 밝혀 둡니다.

확장하는 방법

13

지금 상태

지금 하고 있는 것

• 예외 처리 점검 — 연결 실패 · 타임아웃(call_timeout · wait_timeout) · 상한 초과(재작업 3회 · 깊이 5 · LLM 호출 수) · 설정 오류일 때 어느 지점에서 멈추고 어떤 오류 코드와 로그를 남기는지를 경로별로 확인합니다
• 최종 테스트 — Windows 와 Linux 양쪽에서 회귀 테스트와 종단(E2E) 실행을 다시 돌리고, 띄워 둔 서버의 10노드 배치에서 같은 항목을 확인합니다
• 문서 마무리 — 운영 매뉴얼 최종본과 키 발급 안내서를 정리합니다

납품 전 자체 점검

넘겨 드리기 전에 회귀 점검을 돌립니다. 고쳐서 다시 드릴 때 예전에 되던 것이 깨지지 않았는지를 확인하는 장치입니다. 직접 돌려 보실 수 있게 함께 넣어 드립니다 — a2a test 한 줄이고 추가 설치는 필요 없습니다. 현재 684건 전부 통과합니다.

이번 범위 밖

• 로컬 모델(Ollama·Qwen) 연동 — 비용 0원으로 내용 있는 코드를 얻는 유일한 길입니다
• 푸시 알림 — 폴링·스트리밍은 실제로 돕니다. 푸시는 나중에 쉽게 붙이도록 구조를 갖춰 두었습니다 — 전달 방식이 갈아 끼우게 되어 있고, 받을 주소(push_url)도 서버가 이미 보관합니다
• 언어별 기계 검사 도구 — 자바·HTML 검증자는 이미 따로 세울 수 있고 자기 기준으로 판정합니다. 다만 그 판정은 코드를 읽은 결과이지 돌려 본 결과가 아닙니다. javac · tsc 처럼 언어별 도구를 물리는 일이 남았습니다
• 인증 — HTTP Bearer 1종이 돕니다. OAuth 2.0 · OIDC · API Key · mTLS 는 Agent Card 가 알리는 자리까지 갖춰 두어 방식을 더할 때 그 자리에 붙입니다
• 클라우드 배포 · 데이터베이스 · 모바일 화면
• 여러 대에 나눠 띄우는 실배치와 하루 이상 연속 동작, OS·네트워크 조합 검증 — 실제 운영 환경에서 확인할 부분입니다

14

향후 개선 방안

다음에 얹을 것들입니다. 지금 구조에서 어디까지 준비돼 있고 무엇을 채우면 되는지를 항목마다 적었습니다. 방향은 하나입니다 — 지금의 실행 시스템 위에 스스로 정의하고 검증하고 다시 계획하는 루프를 얹는 것입니다.

1 · 지금 구조를 고치지 않고 붙는 것

2 · 품질을 올리는 루프 — 다음 단계의 핵심

지금은 사람이 쓴 지시가 실무자에게 거의 그대로 갑니다. 그래서 검증자가 보는 것도 "코드가 규칙에 맞는가"에 가깝습니다. 여기에 요구사항을 먼저 확정하는 단계와 실패 원인을 분석해 계획을 고치는 단계를 넣으면, 검증자가 "요구한 것을 다 했는가"를 판정할 수 있습니다.

3 · 운영과 확장

4 · 자율 운전 — 사람이 매번 승인하지 않게

위 항목이 갖춰지면 사람이 중간에 끼지 않고 도는 모드가 가능해집니다. 계획을 세우고, 맡기고, 검증하고, 실패를 분석해 다시 계획하는 루프를 스스로 도는 것입니다. 지금도 한 번의 지시가 재작업 3회까지는 사람 없이 돌지만, 그 범위가 지시 하나 안에 묶여 있습니다.

• 위험도로 가른다 — 코드 생성처럼 되돌릴 수 있는 일은 자동으로, 데이터 변경 · 배포 · 파일 삭제처럼 되돌리기 어려운 일은 사람 승인으로 보냅니다. 무엇이 어느 쪽인지는 정책 파일이 정합니다
• 멈추는 조건을 먼저 정한다 — 예산 소진 · 같은 실패 반복 · 상한 초과 · 취소 요청. 자율 모드는 멈추는 방법이 확실할 때 켜는 기능입니다
• 남기고 되짚는다 — 자율로 돈 구간은 추적 기록 · 판정 · 산출물 이력으로 남겨 나중에 사람이 검토할 수 있어야 합니다
• 스스로 고치는 단계 — 실패 기록이 쌓이면 어디서 반복해 무너지는지(예: 요구사항 누락) 집계해, 검증자를 하나 더 세우거나 계획 단계를 넣도록 제안합니다

먼저 할 순서

위 항목은 전부 이번 범위 밖입니다. A2A 표준 객체(Task · Message · Artifact · Agent Card)는 그대로 두고 깊이 · 비용 · 출처 같은 정보는 metadata 에 싣는 지금 방식을 지키면, 나중에 다른 회사 에이전트와 붙일 때도 그대로 맞습니다.