Agent Factory: 대규모에서 일관된 에이전트 구축

Source: Dev.to

위에 제공된 Source 라인 외에 번역할 텍스트가 포함되어 있지 않습니다. 번역을 원하는 본문을 제공해 주시면 한국어로 번역해 드리겠습니다.

Source: …

에이전트가 어디에나 – 확장성 문제

동일한 에이전트를 여러 이벤트, 고객, 혹은 제품 라인에 배포하는 일은 겉보기보다 어렵습니다.

• 모든 인스턴스가 올바른 구성을 갖추도록 어떻게 보장하나요?
• 무언가가 개선되면 각 에이전트를 일일이 수정하지 않고 어떻게 변경 사항을 전파하나요?

저는 컨퍼런스 데모를 하나의 이벤트에서 여러 이벤트로 확장하면서 Agent Factory 패턴을 개발했습니다. 이 글에서는 패턴을 설명하고, 에이전트를 여러 상황에 일관되게 배포해야 하는 모든 프로젝트에 적용하는 방법을 보여드립니다.

에이전트란 정확히 무엇인가?

API 표면을 벗겨내면 모든 에이전트는 세 가지 요소로 구성됩니다:

대부분의 에이전트 프레임워크에서는 이 세 가지 다리를 생성 시 한 번 설정합니다. 이렇게 하면 에이전트가 예측 가능하고 감사 가능해지지만, 여러 상황에 동일한 에이전트 경험을 제공하려면 각 상황마다 올바르게 구성된 인스턴스가 필요합니다. 이를 수동으로 관리하는 것은 확장되지 않습니다.

실제 사례: 포켓몬 카드 자동 판매기

저는 Algolia의 Agent Studio를 사용해 Algolia 컨퍼런스 부스에서 운영하는 포켓몬 카드 자동 판매기 데모를 만들었습니다. 참석자들은 AI 에이전트와 대화하여:

• 카드를 찾고
• 가치를 확인하고
• 받은 카드를 청구합니다

에이전트는 MCP와 유사한 도구를 통해 검색 가능한 인덱스에서 모든 데이터를 가져옵니다.

각 컨퍼런스마다 해당 이벤트의 카드가 들어있는 새로운 기계가 제공되므로 세 가지 다리 모두가 조정되어야 합니다:

• Tool – 이벤트 인덱스(shoptalk-2026가 아니라 etail-palm-springs-2026)를 가리켜야 합니다.
• Prompt – 올바른 이벤트 이름, 부스 번호, 컨텍스트를 언급해야 합니다.
• Model – 비용이나 이벤트에 따라 달라질 수 있습니다(예: AWS 이벤트에서는 Gemini 사용을 피함).

세 부분 모두 이벤트마다 달라질 수 있습니다. 수동으로 하지 않고 각 이벤트에 맞게 올바르게 구성된 에이전트를 어떻게 만들 수 있을까요?

왜 단일 공유 에이전트를 쓰지 않나요?

모든 이벤트 인덱스에 접근할 수 있는 단일 공유 에이전트는 편리해 보이지만, 에이전트는 정적입니다. 공유 에이전트는 자신이 어느 이벤트를 서비스하고 있는지 알 수 없으므로 다음 중 하나를 해야 합니다:

• 모든 인덱스를 무차별적으로 검색하거나
• 신뢰할 수 없게 적용되는 방어 장치를 요구하거나

따라서 이벤트당 하나의 에이전트가 올바른 컨텍스트를 제공하는 유일한 방법입니다. 문제는 이들을 일관되게 유지하는 것입니다.

Source: …

에이전트 팩토리 패턴

에이전트 생성을 반복 가능한 프로세스로 다룹니다:

1. 세 가지 요소를 템플릿으로 정의합니다.
2. 새로운 컨텍스트마다 함께 렌더링합니다.
3. 생성된 에이전트 ID를 등록합니다.
4. 플릿을 하나의 단위로 관리합니다.

아래 다이어그램(개념)은 흐름을 보여줍니다:

[Template Store] → render (event variables) → [Agent Studio API] → create agent
                                                          ↓
                                                   return agent_id
                                                          ↓
                                            store agent_id in registry

핵심 인사이트

모델, 도구, 프롬프트는 독립적이지 않으며 동일한 컨텍스트를 참조합니다. 도구 설정에 있는 인덱스 이름은 프롬프트가 에이전트에게 검색하도록 알려주는 내용과 일치해야 합니다. 이를 별도로 렌더링하면 서로 어긋날 수 있습니다.

템플릿 기반 구성

Agent Studio가 에이전트 생성을 위한 API를 제공하므로, 모든 것을 공유 플래이스홀더 변수를 가진 템플릿으로 저장하고 세 가지 요소를 한 번에 렌더링합니다.

agent-config.json

{
  "name": "Demo Agent — {{event_name}}",
  "provider": "your-llm-provider",
  "model": "your-model",
  "instructions": "PROMPT.md",
  "tools": [
    {
      "type": "algolia_index_search",
      "index": "catalog_{{event_id}}",
      "description": "Product catalog for the {{event_name}} event."
    }
  ]
}

PROMPT.md (발췌)

You are an agent at {{event_name}} (booth {{booth}}).
Use Algolia search to help attendees find cards in the vending machine.

• {{event_id}}, {{event_name}}, {{booth}}는 두 파일을 함께 해석합니다.
• 변수 누락이나 불일치가 있으면 API 호출 전에 실패합니다.
• 프롬프트가 개선되거나 도구 설정이 변경될 때 두 파일이 원자적으로 업데이트됩니다.

에이전트 ID 저장

Agent Studio는 각 에이전트를 관리형 엔드포인트로 호스팅하고 생성 시 고유 ID를 반환합니다. 애플리케이션은 런타임에 이 ID를 사용해 올바른 에이전트를 로드하지만, ID는 사전에 예측할 수 없으므로 데이터베이스, 설정 파일 또는 다른 Algolia 인덱스와 같이 접근 가능한 곳에 저장해야 합니다. 팩토리는 반환된 agent_id를 이벤트 레지스트리에 다시 기록하여 생성과 런타임 사이의 루프를 닫습니다.

전체 수명 주기 관리

에이전트 생성은 시작에 불과합니다. 프롬프트가 변경되거나, 새로운 모델이 출시되거나, 이벤트가 종료될 때, 팩토리는 업데이트와 삭제를 처리합니다.

# New event
python agent.py create shoptalk-2026 "Shoptalk 2026" 701 --publish

# Prompt improvement — preview then push to all existing agents
python agent.py update --all --dry-run
python agent.py update --all --publish

# Retire an event
python agent.py delete etail-palm-springs-2026

• update --all 은 팩토리의 핵심 엔진입니다. 하나의 명령으로 에이전트가 있는 모든 이벤트에 대해 현재 템플릿을 다시 렌더링합니다. 프롬프트 개선이나 도구 수정이 하나의 명령 으로 처리되며, N 개의 오류가 발생하기 쉬운 대시보드 편집을 없앨 수 있습니다.

Source: …

파일‑기반, 버전‑관리 설정의 장점

• History – 무엇이 왜 변경되었는지에 대한 전체 감사 추적.
• Rollback – 회귀가 발생한 프롬프트를 되돌릴 수 있는 기능.
• Clarity – 각 에이전트를 생성한 정확한 구성을 명확히 기록.

프롬프트와 구성을 파일로 저장하면 Git(또는 기타 VCS)의 모든 장점을 활용하면서 배포 과정을 결정론적이고 재현 가능하게 유지할 수 있습니다.

TL;DR

• 에이전트 = 모델 + 도구 + 프롬프트.
• 여러 에이전트가 필요할 때는 세 요소를 함께 템플릿화합니다.
• 컨텍스트별로 템플릿을 렌더링하고, API를 통해 에이전트를 생성한 뒤 반환된 ID를 저장합니다.
• 작은 CLI(※ Agent Factory)를 사용해 에이전트를 일괄 생성, 업데이트, 삭제합니다.

이 패턴을 사용하면 하나의 데모에서 수십 개의 이벤트—또는 기타 다중‑테넌트 시나리오—까지도 확장하면서 모든 에이전트를 일관성 있게, 감사 가능하게, 그리고 쉽게 진화시킬 수 있습니다.

규모에 맞는 에이전트 업데이트 관리

에이전트를 실행하면 모델 업그레이드 전후의 동작을 비교하고, 프롬프트 변경을 코드 변경을 검토하듯 검토하며, 실제로 무엇이 개선되었는지 추론할 수 있습니다.

현재 에이전트 분야가 빠르게 변화하고 있어—모델 기능이 향상되고, 더 나은 프롬프트 패턴이 등장하며, 도구 자체도 진화하고 있습니다. 대시보드에서 에이전트를 관리할 때는 이와 같은 절차를 놓치기 쉽습니다.

팩토리 패턴 분리

팩토리가 성숙함에 따라 코드에서 명확한 분리가 나타났습니다:

그 분리가 코드로 표현된 패턴입니다. 저는 일반 레이어를 독립형 오픈소스 CLI — algolia-agent — 로 추출했고, CLI의 API를 호출하고 도메인에 고유한 세 가지 요소만 포함하는 가벼운 데모 래퍼를 만들었습니다.

algolia-agent CLI

CLI는 팩터리 패턴을 모든 프로젝트에서 사용할 수 있게 합니다:

algolia-agent init        # defines all three parts of your agent interactively
algolia-agent create      # renders templates and calls the API
algolia-agent update      # diffs and pushes changes to existing agents
algolia-agent publish     # promotes a draft to live

init 워크플로우

init 명령은 정의를 순서대로 진행합니다:

1. 프로바이더와 모델 선택
2. 도구 선택 (또는 선택하지 않을 수도 있습니다—모델과 프롬프트만으로도 에이전트가 유효합니다)
3. 프롬프트 작성

Real‑world Prompt Fix

A user at the booth asked:

“Do you have any cards worth more than $50?”

The first version of the prompt had no guidance on numeric filters. The agent searched for “cards worth more than 50 dollars” as a keyword query. It got results, but not the right ones—keyword search matched card descriptions that mentioned the word “worth,” not cards filtered by actual value.

The fix

Add one line to the prompt:

For “more than” / “less than” questions on numeric fields, use comparison operators in searchParams filters rather than facets.

Example:

{
  "searchParams": {
    "filters": "estimated_value > 50"
  }
}

After adding this, the agent correctly translated the question into a filter against the estimated_value attribute, returning only cards actually priced above $50.

Because I was running agents for multiple active events, a single algolia-agent update --all pushed the improvement to every instance simultaneously. The agent at the next conference was better than the one at the previous conference without anyone touching it individually. That’s the payoff of treating the prompt as a versioned artifact and the fleet as a unit.

안전망

여러 에이전트를 관리하는 가장 어려운 부분은 에이전트를 만드는 것이 아니라, 만든 뒤에 일관성을 유지하는 것입니다. 플릿에 어떤 변경을 적용하기 전에 정확히 어떤 내용이 바뀔지 미리 확인하고 싶습니다:

• 프롬프트가 어떻게 변했는지
• 어떤 도구가 추가되거나 제거되었는지
• 모델이 변경되었는지

잘못된 변경을 N개의 에이전트에 푸시하면, 배포 전에 잡아낸 경우보다 N배 더 디버깅하기 어렵습니다. 제 CLI에서는 API를 호출하기 전에 변경될 내용을 diff 형태로 보여주는 --dry-run 플래그를 포함했습니다.

요약

• Agent anatomy: 세 가지 구성 요소—model, set of tools, prompt.
• Separation of concerns: 핵심 에이전트 구성과 이벤트별 컨텍스트 구분.
• Factory pattern: 에이전트 정의를 스캐폴드하고, 컨텍스트별로 렌더링하며, 모든 인스턴스에서 일관된 CRUD 작업을 수행합니다.
• One‑command propagation: 프롬프트 개선, 모델 업그레이드, 툴 수정 등 무언가가 개선될 때, 하나의 명령으로 모든 에이전트를 한 번에 업데이트합니다.

Feel free to try out my algolia-agent for yourself. I’d also love to hear if the factory pattern is useful to you, or how it can be improved!