우리의 첫 번째 에이전트 워크플로우(agent workflows)는 시작하기 쉬웠습니다. 그러다 또 다른 에이전트, 도구(tool), 후속 턴(follow-up turn), 샌드박스(sandbox), 그리고 실행 간에 파일을 유지할 공간을 추가하게 되었습니다.

코드는 여전히 작동했지만, 워크플로우를 이해하려면 프로바이더(provider) 호출, 프롬프트 빌더(prompt builders), 스키마 파싱(schema parsing), 그리고 정리 코드(cleanup code) 사이를 계속 오가야 했습니다. 우리는 파일 하나만 열면 무엇이 실행되는지, 각 에이전트가 무엇을 사용할 수 있는지, 그리고 그 결과가 어디로 가는지 한눈에 볼 수 있기를 원했습니다.

그래서 우리는 Agent Markup Language를 구축했습니다.

트리에 들어가는 것들

AML을 사용하면 에이전트 워크플로우를 TypeScript와 JSX로 작성할 수 있습니다.

에이전트, 그들의 기능(capabilities), 그리고 리소스 경계(resource boundaries)는 하나의 실행 가능한 트리(executable tree) 안에 존재합니다. 런타임(runtime)은 해당 트리를 평가하고, 프로바이더 및 리소스의 라이프사이클(lifecycle)을 관리하며, 최종 에이전트의 출력을 반환합니다.

<Sandbox access="read-only" provider={Docker} root="repository">
  <Agent provider={Codex}>Inspect src/index.ts.</Agent>
</Sandbox>

이러한 중첩(nesting)은 런타임 상의 의미를 갖습니다. <Agent>를 <Sandbox> 안에 넣으면, 짜잔, 모델이 제어하는 파일 시스템과 명령 실행이 해당 샌드박스로 범위가 제한(scoped)됩니다. 스킬(skills)도 마찬가지입니다. <Agent> 안에 <Skill> 또는 <Tool>을 넣으면 AML 런타임이 에이전트에게 프롬프트를 보내기 전에 모든 것이 해결되도록 보장합니다.

AML은 현재 OpenCode 및 Codex 어댑터(adapters), Docker 샌드박스, 로컬 워크스페이스 프로바이더(local workspace provider), (그리고 테스트를 위한 결정론적 프로바이더(deterministic providers))를 제공합니다. 아직 초기 단계이며 API는 여전히 형태를 갖춰가는 중입니다.

우리는 접착제 코드를 다시 만드는 데 지쳤습니다

프로바이더 SDK(Provider SDKs)는 모델 세션(model sessions)을 잘 처리합니다. 인증 방법, 턴(turns) 전송, 네이티브 도구 호출, 그리고 프로바이더별 상태(provider-specific state) 유지 방법을 알고 있습니다.

유용한 워크플로우는 보통 해당 세션 주변에서 더 많은 일이 일어납니다. 두 명의 전문가를 병렬로 실행하고, 그들의 출력을 검증하며, 두 결과를 코디네이터(coordinator)에게 전달하거나, 외부 API 또는 데이터베이스의 결과를 섞는 작업이 포함될 수 있습니다.

우리는 이러한 오케스트레이션(orchestration)을 계속 수동으로 작성해 왔습니다.

async function Review({ source }: { source: string }) {
  const findings = await evaluate(
    <Agent provider={OpenCode}>
...

JSX는 이미 트리를 기술하는 방법을 알고 있습니다

에이전트 워크플로우(Agent workflows)는 자연스럽게 트리를 형성합니다. 코디네이터(coordinators)는 전문가(specialists)에 의존하고, 도구(tools)는 특정 에이전트에 속하며, 샌드박스(sandboxes)는 도구가 필요한 작업을 감쌉니다. XML 스타일의 마크업(markup)은 이러한 관계를 가시화합니다.

JSX는 **우리가 이미 사용 중인 TypeScript 툴링(tooling)**인 자동 완성(autocomplete), 타입 체크(type checking), 리팩터링(refactoring), 구문 강조(syntax highlighting)를 추가합니다. React 개발자들은 이미 컴포넌트(components), 프롭스(props), 자식(children), 그리고 일반적인 자바스크립트(JavaScript) 제어 흐름(control flow)에 익숙합니다.

사고의 전환이 필요한 부분은 실행 순서입니다. AML은 루트(root)로부터 컴포넌트를 발견하지만, 중첩된 에이전트 세션(nested agent sessions)은 리프(leaves)에서부터 위로 거슬러 올라가며 실행됩니다. 자식 노드가 완료되면 그 출력이 부모의 요청에 합쳐지고, 그 후에 부모가 시작됩니다.

결과는 트리를 타고 위로 이동합니다

다음은 간단한 병렬 검토(parallel review) 예시입니다:

import { readFile } from "node:fs/promises"

import { Agent, AmlRuntime, evaluate, opencodeAgent } from "@aml-jsx/sdk"
...

Promise.all()은 두 검토자를 동시에 시작합니다. 이들의 출력은 **일반적인 값(ordinary values)**으로 돌아와 최종 에이전트의 프롬프트(prompt)에 전달됩니다. 코디네이터는 두 검토자가 모두 완료된 후에 실행됩니다.

동시성(Concurrency)은 일반적인 자바스크립트(JavaScript)와 같습니다. 프로바이더(Providers)는 트리에 전달되므로, 동일한 워크플로우를 Codex, OpenCode 또는 결정론적(deterministic) 테스트 프로바이더로 실행할 수 있습니다.

한 에이전트가 다음 에이전트에게 브리핑할 수 있습니다

한 에이전트가 다른 에이전트의 시스템 프롬프트(system prompt) 일부를 생성할 수 있습니다:

import { Agent, opencodeAgent, System } from "@aml-jsx/sdk"

const OpenCode = opencodeAgent({})
...

전문가가 먼저 실행됩니다. 전문가의 최종 텍스트는 코디네이터를 위한 시스템 콘텐츠(system content)가 되며, 코디네이터는 전체 요청이 조립된 후에만 시작됩니다.

도구 접근(Tool access) 또한 트리를 따릅니다. 만약 전문가가 <Tool> 또는 <Mcp> 권한을 부여받는다면, 해당 권한은 전문가에게만 유지됩니다. 형제(sibling) 노드나 부모(parent) 노드가 이를 조용히 상속받지는 않습니다.

직접 AML을 실행해 보세요

Node 26 이상 버전이 있다면, 모델 자격 증명(model credentials) 없이도 결정론적 검토 예제를 실행할 수 있습니다:

git clone https://github.com/we-are-singular/aml.git
cd aml
npm install
...

자신의 프로젝트에서 AML을 사용하려면 SDK를 설치하세요:

npm install @aml-jsx/sdk

그 다음, TypeScript가 AML의 JSX 런타임(runtime)을 가리키도록 설정하세요:

{
  "compilerOptions": {
    "jsx": "react-jsx",
...

프로젝트 사이트에는 대화형 워크스루(walkthrough)가 있으며, 리포지토리에는 병렬 에이전트(parallel agents), 구조화된 출력(structured output), 후속 턴(follow-up turns), 루프(loops), 도구(tools), MCP, 샌드박스(sandboxes), 그리고 워크스페이스(workspaces)에 대한 실행 가능한 예제들이 있습니다.

예제 중 하나를 시도해 본 뒤, 저희에게 알려주세요: API의 어느 부분에서 멈춰서 문서를 찾아보게 되었나요? 이슈를 생성하여 어떤 부분을 간소화하면 좋을지 저희에게 알려주세요. 보내주신 피드백은 다음 변경 사항을 결정하는 데 활용하겠습니다.

만약 AML이 유용해 보인다면, GitHub에서 스타(star)를 눌러주세요.