아키텍처

LLaMON Agent SDK는 포트와 어댑터 구조를 사용합니다. Core는 외부 시스템의 구체 구현을 직접 import하지 않고, application port를 통해 Registry·LLM·MCP·A2A·메모리 어댑터를 호출합니다.

Driving adapter  →  Application  →  Core  →  Driven adapter
 A2A · CLI ·        use cases       runtime    LLM · MCP · Registry
 Studio                                      A2A · Memory · Trace

에이전트와 플로우는 한 실행 그래프를 A2A로 노출합니다. 오케스트레이터는 여러 자식 Agent, WorkflowState, durable checkpoint, 최종 응답 경계를 묶는 별도 런타임입니다.

실행 경계

경계	실행을 결정하는 곳	상태
Agent	ReAct Agent 또는 주입한 `RuntimeAdapter`	선택한 memory checkpointer
Flow	애플리케이션의 LangGraph	flow state와 checkpointer
Agentic orchestrator	OKF rule과 bounded `AgenticProgram`	`WorkflowState`와 durable execution
Deterministic orchestrator	명시적 `run_turn(ctx)`	같은 durable 경계, controller LLM 없음

Agentic rules-first는 구조로 확정할 수 있는 child를 먼저 호출하고, 나머지만 controller가 판단합니다. 도구 결과는 observation으로 같은 bounded loop에 돌아오며, Completed 후보는 설정된 경우에만 VerificationLoop를 거칩니다. 어느 경로든 입력·출력 guardrail, WorkMemory, 담당자 검수, FinalResponse를 우회하지 않습니다.

작은 화면에서는 좌우로 스크롤하세요.전체 화면에서 보기 ↗

상세한 선택 기준과 생성 방법은 오케스트레이터 시작하기, 설정값은 오케스트레이터 설정·API를 참고하세요.

서버 조립

create_server()는 두 입력 방식을 같은 실행 인터페이스로 정규화합니다.

방식	조립 과정
Registry	`ExtensionConfig`의 참조를 resolve하고 `ComponentContainer`를 만든 뒤 `LangGraphAgent`를 생성
코드 주입	전달한 graph 또는 adapter를 `GraphInvocationAdapter` 같은 경계 어댑터로 감쌈

Registry 경로의 ComponentContainer에는 LLM, prompt, MCP tools, A2A child, guardrail, memory manager, flow graph가 모입니다. Core는 이 컨테이너의 포트만 사용합니다.

Registry 경로와 코드 주입 경로가 같은 실행 경계로 합쳐집니다.전체 화면에서 보기 ↗

선택적으로 생성하는 resolved.json은 Registry 프로젝트 내부에서 만드는 LLM·prompt 빌드 시점 snapshot일 뿐입니다. MCP·A2A·guardrail·memory처럼 살아 있는 Registry 연결은 서버 기동 시 resolve합니다. snapshot이 없어도 Registry 런타임은 직접 resolve합니다. Components 프로젝트는 resolved.json을 편집하거나 fallback 입력으로 사용하지 않고, 명시적으로 주입된 Components의 부팅 snapshot만 사용합니다.

HTTP 표면

서버는 Starlette ASGI 앱 하나이며 A2A 표준 앱과 운영 라우트를 함께 마운트합니다.

경로	역할
`POST /`	JSON-RPC `message/send` 또는 `message/stream`
`GET /.well-known/agent-card.json`	공개 Agent Card
`GET /healthz`	프로세스 상태 확인
`GET /graph`	그래프 시각화 데이터
`/api/v1/*`	상태·Agent Card·메모리·Registry 관리

POST /invoke는 없습니다. 요청 envelope와 관리 endpoint는 런타임 API에 정리되어 있습니다.

요청 흐름

내부 graph가 달라도 A2A 입출력 경계는 같습니다.전체 화면에서 보기 ↗

A2A 앱이 JSON-RPC method와 Part를 검증합니다.
CustomAgentExecutor가 text·data·files, contextId, metadata를 실행 문맥으로 바꿉니다.
입력 guardrail과 HITL 재개 여부를 확인합니다.
Agent·Flow·Orchestrator 중 조립된 runtime을 호출합니다.
outbound adapter가 LLM, MCP, Registry, 원격 A2A, memory I/O를 수행합니다.
결과를 TextPart·DataPart·FilePart와 Task 상태로 정규화합니다.
출력 guardrail을 거쳐 A2A 응답 또는 SSE event를 보냅니다.

message/stream은 공개 가능한 exit node의 청크만 전송합니다. 첫 청크 전 실패는 invoke fallback이 가능하지만, 일부 청크를 보낸 뒤 실패하면 같은 요청을 다시 실행하지 않고 failed로 마감합니다.

코드 지도

책임	기준 위치
서버 composition root	`src/llamon_agent/inbound/server/factory.py`
A2A 요청·응답 경계	`src/llamon_agent/inbound/a2a/`
런타임과 출력 정규화	`src/llamon_agent/core/runtime/`
application port·use case	`src/llamon_agent/application/`
Registry·LLM·MCP·A2A adapter	`src/llamon_agent/outbound/`
Flow graph와 helper	`src/llamon_agent/graph/`
Orchestrator state·workflow	`src/llamon_agent/orchestrator/`

디버깅할 때는 바깥에서 안쪽 순서로 확인하면 빠릅니다: A2A envelope → executor → 선택된 runtime → outbound adapter → 결과 정규화. 구체적인 증상별 점검은 문제 해결을 보세요.