파이썬 코드 없이 YAML로 구축하는 선언적 멀티 에이전트 런타임, tama

실용적 조언

반복적인 에이전트 실험이 필요한 경우 tama의 CLI 생성기를 사용하여 프로젝트 뼈대를 빠르게 구축할 수 있다.
에이전트 간의 복잡한 전환 로직은 YAML의 FSM 섹션에 상태 전이 규칙을 명시하여 시각적으로 관리 가능하다.

섹션별 상세

에이전트 워크플로우 실험 시 발생하는 반복적인 파이썬 스캐폴딩 작업이 개발 속도를 저해한다. 프로젝트 초기 설정, 의존성 관리, 그래프 노드 및 엣지 연결 등의 과정이 실제 프롬프트 반복 개선보다 우선시되는 역전 현상을 해결하고자 했다.

tama는 에이전트와 스킬을 개별 파일로 분리하고 YAML 프론트매터를 통해 오케스트레이션을 정의하는 선언적 방식을 채택했다. 이는 Terraform과 같은 코드형 인프라(IaC) 모델을 차용하여 복잡한 그래프 구축 코드 없이도 시스템 구조를 명확히 관리할 수 있게 한다.

라우팅 로직을 파이썬 코드가 아닌 FSM(유한 상태 기계) 패턴으로 정의하여 에이전트 간 전환을 제어한다. 초기 상태(initial)와 각 상태에서의 전이 조건(states)을 YAML에 명시함으로써 복잡한 조건문 없이도 지원(support)이나 기술(tech) 에이전트 간의 흐름을 구성한다.

yaml

name: support
pattern: fsm
initial: triage
states:
  triage:
    - billing: billing-agent
    - technical: tech-agent
  billing-agent:
    - done: ~
    - escalate: triage
  tech-agent: ~

FSM(유한 상태 기계) 패턴을 사용하여 에이전트 간의 라우팅과 상태 전이를 정의하는 YAML 설정 예시

CLI 도구와 내장 트레이싱 기능을 통해 에이전트 시스템의 실험 주기를 단축한다. 'tama init'과 'tama add' 명령어로 구조를 자동 생성하고, 실행 후에는 어떤 에이전트가 호출되었는지와 도구 사용 내역을 즉시 확인할 수 있어 디버깅 효율이 높다.

bash

tama init
tama add fsm support
// 프롬프트 작성 후
tama run

CLI를 통해 프로젝트를 초기화하고 에이전트 워크플로우 구조를 생성 및 실행하는 과정

용어 해설

선언적 오케스트레이션(Declarative Orchestration): — 시스템이 '어떻게(How)' 동작해야 하는지 코드로 일일이 작성하는 대신, 최종적으로 '어떤(What)' 상태가 되어야 하는지를 명시하는 방식이다. 에이전트 워크플로우에서 복잡한 파이썬 제어 로직 없이 YAML 설정만으로 에이전트 간의 관계와 흐름을 정의할 수 있어 유지보수와 실험 속도가 향상된다.
유한 상태 기계(Finite State Machine): — 시스템이 가질 수 있는 유한한 상태들과 그 상태들 간의 전이 규칙을 정의한 수학적 모델이다. 에이전트 시스템에서 현재 에이전트의 작업 결과에 따라 다음으로 실행될 에이전트를 결정하는 라우팅 로직을 명확하고 예측 가능하게 설계하는 데 사용된다.
스캐폴딩(Scaffolding): — 새로운 프로젝트나 기능을 시작할 때 반복적으로 작성해야 하는 기초적인 뼈대 코드를 자동으로 생성하는 기법이다. 에이전트 개발 시 프로젝트 구조 설정, 의존성 설치, 기본 클래스 정의 등의 번거로운 작업을 줄여 개발자가 핵심 로직인 프롬프트와 도구 설계에 집중하게 돕는다.
코드형 인프라(Infrastructure as Code): — 수동 프로세스가 아닌 코드를 통해 인프라를 관리하고 프로비저닝하는 방식이다. 본문에서는 에이전트 시스템 구축을 Terraform과 같은 IaC 도구처럼 선언적 파일로 관리하는 멘탈 모델을 설명하기 위한 비유로 사용됐다.
트레이싱(Tracing): — 분산 시스템이나 복잡한 워크플로우에서 요청의 흐름을 추적하여 기록하는 기술이다. 멀티 에이전트 시스템에서 어떤 에이전트가 실행되었고, 어떤 도구가 호출되었으며, 데이터가 어떻게 전달되었는지 시각화하여 디버깅과 성능 최적화를 지원한다.

언급된 도구

tama추천링크

선언적 오케스트레이션을 지원하는 멀티 에이전트 워크플로우 오픈소스 런타임

언급된 리소스

GitHubtama GitHub Repository

튜토리얼Hello World: Deep Research Walkthrough