Agent 구성에 대한 자세한 설명

Agent는 "한 번의 LLM 세션 + 그것이 사용할 수 있는 도구 + 그 실행 정책"을 캡슐화한 것입니다. Braidrun에서는 system prompt를 직접 작성할 필요가 거의 없습니다 — preset 하나를 선택하고 필요하면 몇 개 필드를 overrides하면 충분합니다.

사전 설정: 장면을 기반으로 기준선 선택

preset은 플랫폼 내장 Agent 템플릿으로, 「모델, 기본 도구셋, system prompt, 실행 정책」을 함께 묶어 업무 시나리오에 따라 이름 붙인 것입니다. 현재 내장 프리셋은 총 19개입니다:

최소한의 선언

agents:
  analyst:
    preset: universal

이것으로 충분합니다 — 모델, 도구, system prompt 모두 preset 기본값을 따릅니다.

재정의: 요청 시 재정의

agents:
  analyst:
    preset: universal
    overrides:
      system_prompt: |
        你是公司的风控分析师。所有输出用中文。
      llm_config:
        models:
          - model: anthropic/claude-sonnet-4-20250514
            provider: openrouter
        temperature: 0.2
      tool_set:
        - file_system
        - web
        - data_transform

일반적으로 사용되는 재정의 필드

• system_prompt — preset의 system prompt를 통째로 교체합니다(추가가 아님).
• llm_config — 모델 설정: models 목록(각 항목은 model + provider), fallback, temperature. 같은 워크플로 내에서 각 Agent는 서로 다른 모델을 사용할 수 있습니다.
• tool_set — 도구셋 이름의 목록으로, preset 기본값을 통째로 교체합니다(병합하지 않음).
• max_iterations — Agent 내부 "사고 + 도구 호출" 라운드의 하드 상한이며, 도달하면 강제로 중단합니다. 내장 프리셋의 기본값은 꽤 넉넉하게 설정되어 있습니다.
• strategy — just_work_parallel（대부분 프리셋 기본값）/ just_work_parallel_reasoning（가시적 추론 단계 유지）/ single_run（단일 라운드 직접 출력이며, lightweight가 이를 사용합니다）。
• mcp_servers — 외부 MCP Server를 등록하면 그것이 노출하는 도구가 해당 Agent의 도구셋에 병합됩니다.
• retry_max_attempts / retry_initial_delay / retry_max_delay — LLM 호출 실패 시의 백오프 재시도 정책입니다.

재사용 가능: 단계의 에이전트 참조

agents:
  analyst: { preset: universal }
  writer:  { preset: writer }

steps:
  - step: plan
    agent: analyst
    input: "拆解下面这个目标为 3~5 个可执行任务：..."

  - step: write
    agent: writer
    input: "把下面的计划改写成给客户的邮件：{{steps.plan.output}}"
    depends_on: [plan]

같은 Agent가 여러 step에서 참조될 수 있습니다. step이 실행될 때마다 새 세션 인스턴스가 열리므로 기억이 섞이지 않습니다. step 사이에 데이터를 전달하려면 템플릿 변수로 상류 출력을 참조하고, 라운드 간 컨텍스트를 유지하려면 state_machine 또는 group_chat을 사용하십시오.

도구 세트(tool_set)

내장 도구는 이름별로 그룹화되어 있으며, 자주 쓰는 것은 다음과 같습니다:

• file_system — 작업 디렉터리 내 파일을 읽고 씁니다.
• shell — shell 명령을 실행합니다.
• web — HTTP 요청, 웹 스크래핑, 검색.
• browser — 브라우저 자동화: 동적 페이지, 폼, 스크린샷.
• code_execution — 코드 스니펫을 실행합니다.
• csv · database · data_transform — CSV 표, SQL 데이터베이스, JSON/YAML/XML 형식 변환.
• email · im — 이메일 송수신과 IM 메시지(Slack, Telegram, 딩톡, 위챗 워크, 페이슈 등).
• word · excel · powerpoint · pdf · ocr — 문서 생성과 파싱.
• image_processing · multimedia — 이미지 처리와 AI 이미지 / 오디오 생성.
• git — 버전 관리 작업.
• knowledge_memory — 실행을 넘어 지속되는 지식 메모리.
• sub_agent — 하위 Agent를 파생하여 작업을 분해합니다.
• skill_tools — 스킬(skills)을 로드하고 호출합니다.

각 preset 정의에는 기본 tool_set 한 벌이 딸려 있습니다. 이 외에도 어떤 Agent든 mcp_servers 설정을 통해 MCP Server가 노출하는 도구를 연결할 수 있습니다.

모델 선택 권장 사항

• 정확성에 민감한 작업(리뷰, 추론, 코드 생성)에는 각 업체의 플래그십 또는 추론 모델을 사용합니다.
• 지연에 민감하고 출력 형식이 단순한 작업(classifier, 짧은 요약)에는 경량 모델을 사용하여 빠르고 절약합니다.
• 같은 워크플로 내에서 혼용할 수 있습니다. 대량 분석에는 저렴한 모델을, 핵심 최종 심사에는 더 강한 모델로 교체합니다.

모델은 전부 BYOK입니다: 15개 이상 공급업체(OpenAI, Anthropic, Google, DeepSeek, Kimi, MiniMax, 즈푸, xAI, Mistral, Qwen 등을 지원하며 로컬 Ollama / LM Studio도 지원)를 지원하고, 호출 비용은 귀하 자신의 계정으로 청구되며 자격 증명은 AES-256-GCM으로 암호화 저장됩니다. Claude Pro / ChatGPT 구독도 로그인 방식으로 연결할 수 있어 반드시 API Key가 필요하지는 않습니다.

FAQ

여러 단계에서 동일한 에이전트를 재사용하는 경우 할당량은 어떻게 계산되나요?

각 step 실행은 독립적인 LLM 세션이며, token 소비는 실행 상세에 매번 기록됩니다. 플랜 쿼터가 제한하는 것은 워크플로 수, 스케줄 수, 동시성 같은 플랫폼 리소스입니다. LLM token은 귀하 자신의 Key로 진행되며 플랫폼은 token 상한을 두지 않습니다.

Agent에 무한 루프가 발생하면 어떻게 해야 합니까?

max_iterations는 하드 상한이며, 도달하면 실행이 강제로 중단됩니다. 문제를 진단할 때는 먼저 실행 타임라인의 각 라운드 도구 호출을 확인하십시오. Pro 이상 플랜은 브레이크포인트 디버거로 단계 내에서 일시 중지하여 검사할 수도 있습니다.

나만의 도구를 추가하고 싶나요?

MCP server로 패키징하여 mcp_servers 설정으로 연결하는 것을 권장하며, 플랫폼을 수정할 필요는 없습니다. 참고: 내장 모듈 라이브러리 와 AI 어시스턴트 문서 MCP 장에서.