# a2a-agent

`a2a-agent`는 MQTT 위에서 커맨더와 워커가 A2A 형식 메시지를 주고받기 위한 작은 명령줄 도구입니다.

현재 버전은 MQTT 브로커(기본값은 환경변수 `A2A_BROKER_HOST`, 미설정 시 `localhost:1883`), 기본 방 `team`, 6자리 페어링 코드, 역할별 `run` 루프, 커맨더 `send`, 워커 `echo`/`opencode` 실행기를 지원합니다.

## 설치

PyPI 배포 후에는 다음처럼 설치할 수 있습니다.

```bash
python -m pip install a2a-agent
```

개발 환경에서 소스 코드로 설치하려면 저장소 루트에서 실행합니다.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

## 기본 사용

커맨더 설정을 만듭니다.

```bash
a2a-agent init --room team --device-name commander --broker-host <BROKER_HOST> --broker-port 1883 --no-tls
```

커맨더 실행 루프를 켭니다. 이 루프가 켜져 있어야 워커의 페어링 요청에 답할 수 있습니다.

```bash
a2a-agent run
```

다른 터미널에서 워커 6자리 페어링 코드를 발급합니다.

```bash
a2a-agent invite macbook-air
```

워커 기기에서는 코드만 입력해 참여합니다.

```bash
a2a-agent join ABC234
```

워커 실행 루프를 켭니다. 기본 실행기는 `echo`입니다.

```bash
A2A_EXECUTOR=echo a2a-agent run
```

커맨더에서 워커에게 작업을 보냅니다.

```bash
a2a-agent send macbook-air "ping-테스트"
```

## 워커 실행기

- `echo`: 받은 텍스트를 그대로 회신합니다. 연결 확인용 기본값입니다.
- `opencode`: `opencode run -m opencode/big-pickle "<프롬프트>"`를 호출하고 표준출력을 회신합니다. 실패하거나 설치되어 있지 않으면 에러 메시지를 결과로 돌려보냅니다.

실행기는 설정 파일의 `executor` 또는 환경변수 `A2A_EXECUTOR`로 선택합니다. 환경변수가 우선합니다.

## 토픽

페어링 토픽은 방과 무관한 전역 토픽입니다.

```text
a2a/_pairing/request
a2a/_pairing/reply/{code}
```

작업 토픽은 방과 워커 이름을 기준으로 나뉩니다.

```text
a2a/{room}/agents/{device}/card
a2a/{room}/agents/{device}/status
a2a/{room}/cmd/{device}/request
a2a/{room}/cmd/{device}/response
a2a/{room}/cmd/{device}/task-status
```

## 구조

```text
a2a-agent/
├── pyproject.toml
├── README.md
├── LICENSE
├── install/install.sh
├── scripts/live_broker_roundtrip.py
├── src/a2a_agent/
│   ├── cli.py
│   ├── client.py
│   ├── config.py
│   ├── executor.py
│   ├── invite.py
│   ├── pairing.py
│   ├── protocol.py
│   ├── runtime.py
│   └── topics.py
└── tests/
```

## 라이선스

MIT 라이선스를 따릅니다.
