LangGraph에서 Plugin 활용하기

여기에서는 Anthropic의 Plugin을 LangGraph에서 활용하는 방법에 대해 설명합니다. Agent에서는 선택된 plugin의 Skill을 이용해 사용자의 요청을 처리하는데, 외부의 데이터는 Connector의 MCP를 이용해 가져옵니다. 여기에서는 Notion, Tavily, Slack, RAG와 같은 데이터 소스를 활용합니다. UI는 편의상 streamlit을 사용하고 있으며 외부와 접속시 CloudFront - ALB - EC2로 구성합니다. Production에서는 EC2를 ECS/EKS로 대체하여 scalability를 확보하거나, AgentCore와 같은 서버리스 형태로 구성할 수 있습니다.

동작 아키텍처

flowchart TB
  UI[Streamlit app.py]

  subgraph Agent["Agent (LangGraph)"]
    LGA[langgraph_agent<br/>Agent / Agent Chat]
    LGP[plugin_agent<br/>Plugin 모드]
    SG[StateGraph<br/>call_model ↔ ToolNode]
    BT[내장 도구 execute_code, write_file ...]
    MCP[MCP 도구 mcp_config.py]
    LGA --> SG
    LGP --> SG
    SG --> BT
    SG --> MCP
  end

  subgraph Skill["Skill (skill.py)"]
    BSP[build_skill_prompt]
    BCP[build_command_prompt]
    GSI[get_skill_instructions]
    BASE[베이스 스킬<br/>skills/*/SKILL.md]
    PSK[플러그인 스킬<br/>plugins/*/skills/*/SKILL.md]
  end

  subgraph Plugin["Plugin (plugins/)"]
    PLG[productivity / enterprise-search ...]
    CMD[commands/*.md<br/>슬래시 커맨드]
    CON[.mcp.json Connector]
    PLG --> CMD
    PLG --> CON
    PLG --> PSK
  end

  BR[Amazon Bedrock chat.py]

  UI -->|Agent 모드| LGA
  UI -->|Plugin 모드| LGP

  LGA -->|베이스 스킬만| BSP
  LGP -->|베이스 + 플러그인 스킬| BSP
  LGP -->|/search 등| BCP
  CMD --> BCP

  BSP -->|이름·설명 XML| SG
  BCP -->|커맨드 지침| SG
  SG -->|필요 시 상세 지침 로드| GSI
  GSI --> BASE
  GSI --> PSK
  SG --> BR
  CON -.-> MCP

Skills

Agent Skills은 AI agent에게 특정 작업 수행 방법을 가르치는 재사용 가능한 지침 패키지입니다. Agent skills는 효과적으로 context를 관리하기 위하여 discovery, activation, execution의 과정을 거칩니다. 정리하면 agent가 관련된 skill의 name과 description을 읽는 discovery를 수행한 후에, SKILL.md에 포함된 instruction을 읽는 activation을 수행합니다. Agent는 instruction을 수행하는데 필요하다면 관련된 파일(referenced file)을 읽거나 포함된 코드(bundled code)를 실행합니다. 각 스킬은 SKILL.md 파일로 구성되며, YAML 프론트매터(name, description)와 상세 지침(워크플로, 코드 패턴 등)으로 이루어져 있습니다.

Progressive Disclosure

시스템 프롬프트에는 스킬의 이름과 설명만 XML 형태로 포함하고, 상세 지침은 agent가 get_skill_instructions 도구를 호출하여 필요할 때만 로드합니다. 이를 통해 프롬프트 크기를 최소화하면서도 agent가 다양한 스킬을 활용할 수 있습니다.

<available_skills>
  <skill>
    <name>pdf</name>
    <description>PDF 파일 읽기/병합/분할/OCR/폼 처리 등</description>
  </skill>
  ...
</available_skills>

스킬의 구조

각 스킬은 SKILL.md 파일 하나가 핵심이며, 필요에 따라 scripts/, references/, assets/ 등의 보조 폴더를 포함할 수 있습니다.

application/skills/
├── pdf/
│   └── SKILL.md          # YAML 프론트매터 + 상세 지침
├── notion/
│   └── SKILL.md
└── retrieve/
    ├── SKILL.md
    └── scripts/          # 예: 보조 스크립트(execute_code 등에서 호출)

SKILL.md는 아래와 같이 YAML 프론트매터와 마크다운 본문으로 구성됩니다.

---
name: pdf
description: PDF 파일 처리를 위한 스킬
---

# PDF Processing Guide

## Overview
이 가이드는 Python 라이브러리를 사용한 PDF 처리 작업을 다룹니다.
execute_code 도구로 아래의 Python 코드를 실행하세요.
...

스킬의 종류

스킬은 베이스 스킬과 플러그인 스킬 두 가지로 구분됩니다.

• 베이스 스킬 (application/skills/): Agent / Agent (Chat) 모드에서 사용합니다. 구현상 langgraph_agent.py의 selected_skill_info("base")만 프롬프트에 넣습니다.

• 플러그인 스킬 (application/plugins/<플러그인명>/skills/): 해당 플러그인 이름의 모드에서 선택됩니다. plugin_agent.py에서 베이스 스킬 목록과 selected_skill_info(<플러그인명>) 결과를 합쳐 <available_skills>에 포함합니다 (skill_mode가 활성일 때).

스킬의 동작 흐름

skill.py에서 구현된 스킬의 동작 흐름은 다음과 같습니다.

1. 스킬 탐색: SkillManager가 application/skills/<스킬명>/SKILL.md(베이스) 또는 application/plugins/<플러그인>/skills/<스킬명>/SKILL.md(플러그인)를 스캔해 레지스트리에 등록합니다. 메타데이터와 본문은 Skill 객체에 보관되며, 플러그인별로 skill_managers에 분리 저장됩니다.
2. 선택 필터: selected_skill_info()가 application/config.json의 default_skills(베이스)와 plugin_skills.<플러그인명>(플러그인 모드)에 따라 노출할 스킬만 고릅니다.
3. 프롬프트 구성: build_skill_prompt()가 선택된 스킬의 이름·설명만 <available_skills> XML로 넣고, WORKING_DIR·ARTIFACTS_DIR 경로 안내를 덧붙입니다. 플러그인 슬래시 커맨드 모드에서는 build_command_prompt()가 commands/<이름>.md를 get_command_instructions()로 읽어 옵니다.
4. 지침 로드: 모델이 get_skill_instructions 도구로 본문 지침을 요청하면, 등록된 SkillManager들에서 해당 이름을 찾아 반환합니다.
5. 작업 수행: 지침에 따라 execute_code, write_file 등 에이전트 도구를 사용합니다.
6. 결과 전달: 생성물이 있으면 S3 업로드 등 기존 도구 흐름으로 URL을 제공합니다.

default_skills / plugin_skills는 Streamlit UI에서도 체크박스로 바꿀 수 있으며, 앱은 설정을 application/config.json에 저장합니다. UI에서 스킬 모드(chat.skill_mode)가 꺼져 있으면 베이스/플러그인 모두 langgraph_agent.py의 일반 시스템 프롬프트만 사용하고 스킬 XML·get_skill_instructions는 붙지 않습니다. 베이스 스킬 레지스트리는 Agent 모드 진입 시 register_plugin_skills("base")로 한 번 올려 둡니다(app.py).

Plugin

Plugin은 아래와 같이 Skill을 이용해 동작하는데 외부의 연결은 MCP를 포함한 Connector로 구현하고 sub-agent를 활용할 수 있습니다.

Plugin = Skills(행동 방식) + Connectors(외부 연결) + Slash Commands(명령어) + Sub-agents(하위 에이전트) 

플러그인 디렉터리 구조

각 플러그인은 application/plugins/<플러그인명>/ 아래에 두며, 베이스 스킬과 동일하게 **skills/<스킬명>/SKILL.md**로 플러그인 전용 스킬을 둡니다. 추가로 MCP·슬래시 커맨드·문서를 같은 폴더에 함께 둡니다.

application/plugins/
└── enterprise-search/
    ├── skills/                    # 플러그인 스킬 (베이스와 동일한 SKILL.md 규약)
    │   ├── search-strategy/
    │   │   └── SKILL.md
    │   └── knowledge-synthesis/
    │       └── SKILL.md
    ├── commands/                  # 슬래시 커맨드(파일명이 /search → search.md)
    │   ├── search.md
    │   └── digest.md
    ├── .mcp.json                  # Anthropic 플러그인 규약의 MCP 서버 정의(참고용)
    ├── mcp_servers.list           # 이 앱에서 선택할 MCP 서버 목록([mcp_config.py](https://github.com/kyopark2014/agent-plugins/blob/main/application/mcp_config.py) 연동)
    ├── CONNECTORS.md              # 연결 가능한 데이터 소스·커넥터 설명
    ├── .claude-plugin/
    │   └── plugin.json            # Claude Code 플러그인 메타데이터(upstream 호환)
    └── README.md

• skills/: 베이스와 같이 YAML 프론트매터 + 본문; plugin.py의 PluginManager가 스캔합니다.
• commands/: /<이름> 입력 시 get_command_instructions()가 commands/<이름>.md를 읽습니다(skill.py).
• mcp_servers.list / .mcp.json: 런타임에서는 UI에서 고른 MCP와 Secret Manager 등을 반영해 mcp_config.py가 서버 파라미터를 구성합니다.
• CONNECTORS.md: 사람이 읽는 커넥터·도구 안내입니다.

knowledge-work-plugins

Anthropic의 knowledge-work-plugins은 특정 직무 전문가로 만들어주는 오픈소스 플러그인입니다. 여기에서 제공하는 plugin은 아래와 같습니다.

해당 git을 다운로드한 후 application/plugins에 플러그인 폴더를 두는 방식으로 확장합니다.

https://github.com/anthropics/knowledge-work-plugins

이 저장소에는 현재 productivity, enterprise-search, frontend-design 플러그인만 포함되어 있으며, 위 표의 나머지는 upstream 저장소에서 가져와 동일한 방식으로 추가할 수 있습니다.

claude-plugins-official

claude-plugins-official에서 Claude Code에서 사용할 수 있는 다양한 플러그인을 활용할 수 있습니다. 여기에서 frontend-design는 프론트엔드 인터페이스를 자동으로 생성해주는 도구입니다.

Plugin 기능 구현

app.py은 streamlit UI에서 plugin을 선택하여 agent를 활용할 수 있도록 합니다. application/plugins에는 knowledge-work-plugins와 claude-plugins-official에서 다운로드한 plugin들이 있습니다. 사용자가 streamlit에서 plugin을 선택하면 아래와 같이 plugin_agent에서 run_plugin_agent()가 실행됩니다.

containers = {
    "tools": st.empty(),
    "status": st.empty(),
    "notification": [st.empty() for _ in range(500)]
}
response = asyncio.run(plugin_agent.run_plugin_agent(
    query=prompt, 
    plugin_name=plugin["name"],
    containers=containers))
logger.info(f"response: {response}")
st.session_state.messages.append({"role": "assistant", "content": response})

plugin_agent.py에서는 plugin을 활용하여 agnet를 구현합니다. Anthropic에서는 plugin 폴더에 .mcp.json와 같이 [CONNECTORS.md](https://github.com/kyopark2014/agent-plugins/blob/main/(./application/plugins/enterprise-search/CONNECTORS.md)의 데이터 소스인 MCP를 지정하게 되어 있지만, 여기에서는 credential을 secret manager에서 가져오도록 mcp_servers.list와 같이 MCP 서버를 리스트하고, mcp_config.py에서 동적으로 mcp.json을 생성합니다.

아래와 같이 MCP tool과 plugin skill를 가져와서 tool을 정의한 다음에 agent를 생성하고 astream을 이용해 결과를 얻습니다.

mcp_servers = load_plugin_mcp_servers_from_list(plugin_path)
mcp_json = mcp_config.load_selected_config(mcp_servers)

server_params = langgraph_agent.load_multiple_mcp_server_parameters(mcp_json)
client = MultiServerMCPClient(server_params)
tools = await client.get_tools()

builtin_tools = plugin.get_builtin_tools()
tool_names = {tool.name for tool in tools}
for bt in builtin_tools:
    if bt.name not in tool_names:
        tools.append(bt)
    else:
        logger.info(f"builtin_tool {bt.name} already in tools")

app = langgraph_agent.buildChatAgent(tools)
config = {
    "recursion_limit": 100,
    "configurable": {
        "thread_id": f"plugin-{plugin_name}",
        "tools": tools,
        "system_prompt": None,            
        "plugin_name": plugin_name,
        "command": command
    }
}

inputs = {
    "messages": [HumanMessage(content=query)]
}

async for stream in app.astream(inputs, config, stream_mode="messages"):
    if content_item.get('type') == 'text':
    text_content = content_item.get('text', '')

langgraph_agent.py에서는 skill 동작에 필요한 internal tool을 정의하고 있습니다. 여기에서 get_skill_instructions은 skill의 description을 리턴합니다.

@tool
def get_skill_instructions(skill_name: str) -> str:
    """Load the full instructions for a specific skill by name.

    Use this when you need detailed instructions for a task that matches
    one of the available skills listed in the system prompt.

    Args:
        skill_name: The name of the skill to load (e.g. 'pdf').

    Returns:
        The full skill instructions, or an error message if not found.
    """
    instructions = skill_manager.get_skill_instructions(skill_name)
    return instructions

langgraph_agent.py의 call_model은 아래와 같이 tool가 skill에 대한 정보를 가지고 system_prompt를 생성합니다.

async def call_model(state: State, config):
    last_message = state['messages'][-1]

    tools = config.get("configurable", {}).get("tools", None)
    custom_prompt = config.get("configurable", {}).get("system_prompt", None)
    plugin_name = config.get("configurable", {}).get("plugin_name", None)    
    command = config.get("configurable", {}).get("command", None)    
    system = build_system_prompt(custom_prompt, plugin_name, command)
    
    reasoning_mode = getattr(chat, 'reasoning_mode', 'Disable')
    chatModel = chat.get_chat(extended_thinking=reasoning_mode)
    model = chatModel.bind_tools(tools)
    prompt = ChatPromptTemplate.from_messages([
        ("system", system),
        MessagesPlaceholder(variable_name="messages"),
    ])
    chain = prompt | model
    response = await chain.ainvoke({"messages": messages})

    return {"messages": [response], "image_url": image_url}

아래와 같이 system prompt에는 WORKING_DIR와 ARTIFACTS_DIR와 같은 path를 포함하고 skill 정보를 포함합니다.

SKILL_USAGE_GUIDE = (
    "\n## Skill 사용 가이드\n"
    "위의 <available_skills>에 나열된 skill이 사용자의 요청과 관련될 때:\n"
    "1. 먼저 get_skill_instructions 도구로 해당 skill의 상세 지침을 로드하세요.\n"
    "2. 지침에 포함된 코드 패턴을 execute_code 도구로 실행하세요.\n"
    "3. skill 지침이 없는 일반 질문은 직접 답변하세요.\n"
)

def build_system_prompt(custom_prompt: Optional[str] = None, skills: Optional[list] = None) -> str:
    """Assemble the full system prompt with available skills metadata."""
    if custom_prompt:
        base = custom_prompt
    else:
        base = BASE_SYSTEM_PROMPT

    path_info = (
        f"\n## 경로 (write_file, read_file 시 절대 경로 사용 권장)\n"
        f"- WORKING_DIR: {WORKING_DIR}\n"
        f"- ARTIFACTS_DIR: {ARTIFACTS_DIR}\n"
        f"예: write_file(filepath='{os.path.join(ARTIFACTS_DIR, 'report.drawio')}', content='...')\n\n"
        f"## write_file 규칙 (필수)\n"
        f"write_file 호출 시 filepath와 content를 반드시 함께 전달하세요. content 없이 호출하면 오류가 발생합니다.\n"
        f"다이어그램(.drawio) 등 대용량 파일도 content에 전체 내용을 담아 한 번에 전달해야 합니다.\n"
    )
    skills_xml = skill_manager.available_skills_xml(skills)
    if skills_xml:
        return f"{base}\n{path_info}\n\n{skills_xml}\n{SKILL_USAGE_GUIDE}"
    return f"{base}\n{path_info}"

Skill 정보는 아래와 같이 SkillManager에서 skill에 대한 name과 description 정보를 포함합니다.

def get_skills_xml(skill_info: list) -> str:
    lines = ["<available_skills>"]
    for s in skill_info:
        lines.append("  <skill>")
        lines.append(f"    <name>{s['name']}</name>")
        lines.append(f"    <description>{s['description']}</description>")
        lines.append("  </skill>")
    lines.append("</available_skills>")
    return "\n".join(lines)

Command 구현

Claude Pluggin의 주요기능중 하나인 Command는 슬랙시(/)을 통해 command와 명령을 전달할 수 있습니다. knowledge-work-plugins의 enterprise-search에는 search.md에서는 한번의 query로 연결된 모든 MCP를 조회하는 기능을 제공합니다. 또한 digest.md에서는 Connector에 연결된 데이터소스들의 최근 활동을 모아서 보여주는 기능을 제공합니다. 이런 기능을 활용하기 위하여 plugin.py와 같이 query에 슬랙시(/)가 있는 경우에 첫번째 단어가 command인지 확인합니다. 이때 선택된 plugin에 실제 command에 해당하는 md 파일이 있는지 확인합니다.

command = None
if plugin.is_command(query, plugin_name):
    command = query.split(" ")[0].lstrip("/")
    logger.info(f"command: {command}")

def is_command(query: str, plugin_name: str) -> bool:
    """Check if the query is a command."""
    if plugin_name == "base":
        return False
    if not query.startswith("/"):
        return False
    command = query.split(" ")[0]
    command_name = command.lstrip("/").lower()  
    commands_dir = os.path.join(PLUGINS_DIR, plugin_name, "commands")
    if not os.path.isdir(commands_dir):
        return False
    commands = os.listdir(commands_dir)
    if command_name + ".md" not in commands:
        return False
    else:
        return True

plugin_agent.py와 같이 Command를 가지고 있으면 아래와 같이 agent를 생성할 때에 command를 전달합니다.

app = langgraph_agent.buildChatAgentWithHistory(tools)
config = {
    "recursion_limit": 100,
    "configurable": {
        "thread_id": f"plugin-{plugin_name}",
        "tools": tools,
        "system_prompt": None,            
        "plugin_name": plugin_name,
        "command": command
    }
}

langgraph_agent.py의 call_model에서는 command를 가지고 system prompt를 생성합니다.

async def call_model(state: State, config):
    last_message = state['messages'][-1]

    plugin_name = config.get("configurable", {}).get("plugin_name", None)    
    command = config.get("configurable", {}).get("command", None)    
    system = build_system_prompt(custom_prompt, plugin_name, command)
    
    reasoning_mode = getattr(chat, 'reasoning_mode', 'Disable')
    chatModel = chat.get_chat(extended_thinking=reasoning_mode)
    model = chatModel.bind_tools(tools)

     prompt = ChatPromptTemplate.from_messages([
        ("system", system),
        MessagesPlaceholder(variable_name="messages"),
    ])
    chain = prompt | model
    response = await chain.ainvoke({"messages": messages})

Command를 위한 system prompt는 plugin으로 부터 command에 대한 description을 추가하고 COMMAND_USAGE_GUIDE를 추가하는 방법으로 아래와 같이 구현합니다.

COMMAND_USAGE_GUIDE = (
    "\n## Command 사용 가이드\n"
    "위의 <command_instructions>에 따라 사용자 요청을 처리하세요.\n"
    "필요한 경우 get_skill_instructions로 skill 지침을 추가 로드하거나, execute_code, write_file 등 도구를 사용하세요.\n"
)

def build_command_prompt(plugin_name: str, command: str) -> str:
    """Build prompt for command mode: path info, command instructions, and available skills."""
    skill_info = selected_skill_info(plugin_name)

    if plugin_name != "base":
        default_skill_info = selected_skill_info("base")
        if default_skill_info:
            skill_info.extend(default_skill_info)

    path_info = (
        f"## Paths (use absolute paths for write_file, read_file)\n"
        f"- WORKING_DIR: {WORKING_DIR}\n"
        f"- ARTIFACTS_DIR: {ARTIFACTS_DIR}\n"
        f"Example: write_file(filepath='{os.path.join(ARTIFACTS_DIR, 'report.drawio')}', content='...')\n\n"
    )

    command_instructions = get_command_instructions(plugin_name, command)
    command_section = f"## Command Instructions\n<command_instructions>\n{command_instructions}\n</command_instructions>\n\n"

    skills_xml = get_skills_xml(skill_info)
    skills_section = f"{skills_xml}\n" if skills_xml else ""

    return f"{SKILL_SYSTEM_PROMPT}\n{path_info}\n{command_section}\n{skills_section}\n{COMMAND_USAGE_GUIDE}"

MCP

Plugin의 Connector는 MCP를 이용해 구현합니다. 이때 필요한 MCP 설정은 아래를 참조합니다.

• Slack: Slack 내용을 조회하고 메시지를 보낼 수 있습니다. SLACK_TEAM_ID, SLACK_BOT_TOKEN으로 설정합니다.

• Tavily: Tavily를 이용해 인터넷을 검색합니다. installer.py에서 secret으로 설정후에 utils.py에서 TAVILY_API_KEY로 등록하여 활용합니다.

• RAG: Knowledge Base를 이용해 RAG를 활용합니다. IAM 인증을 이용하므로 별도로 credential 설정하지 않습니다.

• web_fetch: playwright기반으로 url의 문서를 markdown으로 불러올 수 있습니다. 별도 인증이 필요하지 않습니다.

• Google 메일/캘린더: 구글 메일을 조회하거나 보낼 수 있습니다. Gog CLI를 설치하여 google 인증을 통해 활용합니다.

• Notion: Notion을 읽거나 쓸 수 있습니다. installer.py에서 secret으로 설정후에 utils.py에서 NOTION_TOKEN을 등록하여 활용합니다.

• text_extraction: 이미지의 텍스트를 추출합니다. 별도 인증이 필요하지 않습니다.

Message Trim

LangGraph 에이전트(application/langgraph_agent.py의 call_model)는 LLM 호출 직전에 HumanMessage 기준 최근 N턴만 남깁니다. LangGraph state의 messages는 checkpointer에 그대로 두고, 모델에 넘기는 메시지만 trim합니다. Agent·Plugin Agent 모두 history_mode=Enable/Disable에서 동일하게 적용됩니다.

기본값: MAX_CONTEXT_TURNS = 5 (일반 채팅의 SimpleMemory(k=5)와 동일한 “최근 5턴” 의도)

설정 변경:

• application/langgraph_agent.py의 MAX_CONTEXT_TURNS 상수 수정
• 또는 langgraph_agent.create_agent() / plugin_agent.create_agent()에서 생성하는 config의 max_turns / configurable.max_turns 지정
• max_turns=0이면 trim 비활성화

상수와 trim 함수는 langgraph_agent.py에 정의합니다.

# application/langgraph_agent.py
MAX_CONTEXT_TURNS = 5


def trim_messages_by_human_turns(messages: list, max_turns: int) -> list:
    """Keep messages from the last N HumanMessage turns (inclusive)."""
    if max_turns <= 0 or not messages:
        return messages

    human_indices = [i for i, msg in enumerate(messages) if isinstance(msg, HumanMessage)]
    if len(human_indices) <= max_turns:
        return messages

    return messages[human_indices[-max_turns]:]

call_model에서는 ToolMessage content 정규화 후 trim을 적용합니다.

# application/langgraph_agent.py — call_model() 내부
        max_turns = (
            config.get("configurable", {}).get("max_turns")
            or config.get("max_turns")
            or MAX_CONTEXT_TURNS
        )
        trimmed = trim_messages_by_human_turns(messages, max_turns)
        if len(trimmed) < len(messages):
            logger.info(
                f"trimmed messages from {len(messages)} to {len(trimmed)} "
                f"(max_turns={max_turns})"
            )
            messages = trimmed

        prompt = ChatPromptTemplate.from_messages([
            ("system", system),
            MessagesPlaceholder(variable_name="messages"),
        ])
        chain = prompt | model
        async for chunk in chain.astream({"messages": messages}):
            ...

에이전트 config는 create_agent()에서 생성하며, history_mode와 관계없이 max_turns를 전달합니다.

# application/langgraph_agent.py — create_agent()
    if history_mode == "Enable":
        app = buildChatAgentWithHistory(tools)
        config = {
            "recursion_limit": 100,
            "configurable": {
                "thread_id": chat.user_id,
                "tools": tools,
                "system_prompt": system_prompt,
            },
            "max_turns": MAX_CONTEXT_TURNS,
        }
    else:
        app = buildChatAgent(tools)
        config = {
            "recursion_limit": 100,
            "configurable": {
                "thread_id": chat.user_id,
                "tools": tools,
                "system_prompt": system_prompt,
            },
            "max_turns": MAX_CONTEXT_TURNS,
        }

Plugin Agent(application/plugin_agent.py)도 동일한 max_turns 설정을 사용합니다.

max_turns=5의 의미

• 사용자 HumanMessage 5개와, 각 턴에 이어진 모든 후속 메시지를 유지
• 1턴 = HumanMessage 1개 + 그 뒤의 AIMessage, ToolMessage, 도구 feedback loop 전체
• 도구를 여러 번 호출해도 같은 사용자 질문이면 1턴으로 카운트

예 (도구 사용 포함)

Human(Q1) → AI(tool_calls) → ToolMessage → AI(A1)
Human(Q2) → AI(A2)
Human(Q3) → AI(tool_calls) → ToolMessage → AI(A3)

max_turns=2이면 Q2부터 유지:

Human(Q2) → AI(A2) → Human(Q3) → AI(tool_calls) → ToolMessage → AI(A3)

메시지 개수 trim과의 차이

Checkpointer와의 관계

• history_mode=Enable일 때 MemorySaver checkpointer에는 전체 대화 이력이 저장됩니다.
• trim은 LLM 컨텍스트 윈도우 관리용이며, 저장된 history를 삭제하지 않습니다.
• CloudWatch(/ecs/...) 또는 애플리케이션 로그에서 trimmed messages from X to Y (max_turns=5)로 trim 여부를 확인할 수 있습니다.

배포하기

AWS console의 EC2로 접속하여 Launch an instance를 선택합니다. [Launch instance]를 선택한 후에 적당한 Name을 입력합니다. (예: es) key pair은 "Proceed without key pair"을 선택하고 넘어갑니다.

Instance가 준비되면 [Connet] - [EC2 Instance Connect]를 선택하여 아래처럼 접속합니다.

이후 아래와 같이 python, pip, git, boto3를 설치합니다.

sudo yum install python3 python3-pip git docker -y
pip install boto3

Workshop의 경우에 아래 형태로 된 Credential을 복사하여 EC2 터미널에 입력합니다.

아래와 같이 git source를 가져옵니다.

git clone https://github.com/kyopark2014/agent-plugins

아래와 같이 installer.py를 이용해 설치를 시작합니다.

cd agent-plugins && python3 installer.py

API 구현에 필요한 credential은 secret으로 관리합니다. 따라서 설치시 필요한 credential 입력이 필요한데 아래와 같은 방식을 활용하여 미리 credential을 준비합니다.

• 일반 인터넷 검색: Tavily Search에 접속하여 가입 후 API Key를 발급합니다. 이것은 tvly-로 시작합니다.
• 날씨 검색: openweathermap에 접속하여 API Key를 발급합니다. 이때 price plan은 "Free"를 선택합니다.

설치가 완료되면 CloudFront로 접속하여 Agent를 실행합니다.

인프라가 더이상 필요없을 때에는 uninstaller.py를 이용해 제거합니다.

python uninstaller.py

Chat UI로 실행

Flask 기반 chat_ui/app.py가 정적 파일(index.html, script.js, style.css)과 API(/api/chat)를 함께 제공합니다. 반드시 HTTP로 접속해야 하며, index.html만 탐색기에서 file://로 여는 방식은 API 호출이 되지 않습니다.

1. 의존성 설치 (저장소 루트에서 가상환경을 쓰는 경우 활성화한 뒤)

   cd chat_ui
   pip install -r requirements.txt
   

2. 서버 기동

   python app.py
   

   기본 포트는 5001입니다. 다른 포트를 쓰려면 예를 들어 PORT=8080 python app.py처럼 환경 변수 PORT를 지정합니다.

3. 브라우저에서 열기

   터미널에 표시되는 주소(예: http://127.0.0.1:5001)로 접속합니다. 루트(/)에서 index.html이 서빙되므로 chat_ui/index.html 파일을 직접 더블클릭하여 file://로 열 필요가 없습니다.

   • 정상: http://127.0.0.1:5001/ 또는 http://localhost:5001/
   • 비권장: file:///.../chat_ui/index.html (CORS·경로 문제로 /api/chat이 동작하지 않을 수 있음)

4. 포트를 바꾼 경우 (file://로 HTML만 열어야 하는 특수한 경우) 브라우저 쪽 API 주소를 맞추려면 index.html의 <head> 안에 다음과 같이 지정할 수 있습니다.

   <meta name="chat-api-base" content="http://127.0.0.1:8080">
   

실행결과

왼쪽 메뉴에서 "frontend-design"을 선택한 후에 아래와 같이 "LLM에 맞는 챗봇 UI를 디자인해주세요."라고 입력하면, get_skill_instructions이 frontend-design의 description을 읽어오고, 이를 바탕으로 챗봇 UI를 생성합니다.

생성된 Frontend UI는 아래와 같습니다.

Plugin의 command을 쓰고자 할 때에는 enterprise-search와 같은 plugin을 선택한 후에 아래와 같이 "/search claude의 cowork에서 활용하는 plugin 기능에 대해 설명하고 이를 ppt로 정리하세요."라고 입력합니다. 이렇게 하면 search.md에 정의된 search를 이용해 Connector에 있는 MCP들을 조회한 후에 ppt를 생성할 수 있습니다.