프로젝트 개요 (Project Overview)

turtlesim_agent는 클래식한 ROS turtlesim 시뮬레이터를 자연어(natural language)로 구동되는 창의적인 캔버스로 변환하는 AI 에이전트입니다. LangChain을 기반으로 하는 이 AI 에이전트는 텍스트 기반의 지침을 해석하고 이를 시각적 그림으로 번역하여, 시뮬레이션되는 거북이를 디지털 아티스트로 만듭니다. 이 프로젝트는 대규모 언어 모델(Large Language Models, LLMs)이 어떻게 외부 환경과 상호작용하여 창의적인 행동을 보여줄 수 있는지 탐구합니다. 사용자는 평이한 영어로 모양이나 그림 의도를 설명할 수 있으며, AI 에이전트는 지침을 통해 추론하여 turtlesim의 동작 명령(motion commands)을 사용하여 이를 실행합니다.

TurtleSim 에이전트 데모 (TurtleSim Agent Demo)

📐 기본 도형 그리기 (Drawing Basic Shapes)

https://github.com/user-attachments/assets/049a6c99-ab22-458f-abac-61694f82df55

🌈 무지개 그리기 (Drawing a Rainbow)

사용된 프롬프트 (Prompt used)

7개의 반원형 호(semi-circular arcs)로 구성된 무지개를 그려주길 원합니다. 각 호는 서로 다른 색상을 가져야 하며 반지름은 2.0cm에서 2.7cm 사이여야 합니다. 색상은 보라, 남색, 파랑, 초록, 노랑, 주황, 빨강의 전통적인 무지개 순서를 따라야 하며 펜의 너비는 5로 설정해 주세요. 중첩을 피하기 위해 각 반원의 시작 위치를 0.1cm씩 오프셋(offset)해 주세요.

https://github.com/user-attachments/assets/ea9aee14-bdff-4f2b-8b49-c262b09e9051

참고: 이 데모는 gemini-2.0-flash 모델을 사용하여 생성되었습니다.
언어 모델의 비결정론적(non-deterministic) 특성으로 인해 동일한 모델을 사용하더라도 결과가 달라질 수 있음에 유의하십시오. 출력값은 프롬프트 문구, 타이밍 또는 모델 업데이트와 같은 요인에 따라 다를 수 있습니다.

🛠 시작하기 (Getting Started)

요구 사항 (Requirements)

• ROS 2 Humble Hawksbill (이 프로젝트는 ROS 2 Humble에서만 테스트되었습니다. 다른 ROS 2 배포판과의 호환성은 보장되지 않습니다.)
• Python 3.10+
• requirements.txt에 나열된 기타 종속성(dependencies)

1.

ROS2 워크스페이스에서 클론(Clone) 및 빌드

$ cd ~/{ROS_WORKSPACE}/src
$ git clone -b humble-devel https://github.com/Yutarop/turtlesim_agent.git
$ python3 -m pip install -r turtlesim_agent/requirements.txt
...

2. API Key 설정

turtlesim_agent는 LangChain을 통해 여러 언어 모델(Language Model) 제공업체를 지원합니다. 사용하려는 제공업체에 대한 API 키를 설정해야 합니다.

🔐 셸 설정에 API 키 추가하기

개발 환경에서 API 키를 사용할 수 있도록 셸 설정 파일(예: ~/.bashrc, ~/.zshrc)에 키를 추가한 다음, source 명령어를 사용하여 파일을 다시 로드하세요.

export OPENAI_API_KEY=your_openai_api_key
export ANTHROPIC_API_KEY=your_anthropic_api_key
export GOOGLE_API_KEY=your_google_api_key
...

💡 사용할 계획인 제공업체의 키만 설정하면 됩니다.

🖥️ 자체 호스팅 LLM 사용하기 (예: Ollama)

로컬 또는 원격 LLM 서버(예: Ollama를 통해)를 실행하는 경우, 다음과 같이 서버 URL을 지정하세요:

export URL="https://your_ollama_server_ip:11434"

3. (선택 사항) LangSmith를 이용한 트레이싱(Tracing) 활성화

LangSmith를 사용하여 에이전트의 동작을 추적(Trace)하고 디버깅하려면 다음 환경 변수를 설정하세요:

기본 트레이싱 설정:

export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
export LANGSMITH_TRACING=false

API 키 및 프로젝트 이름을 포함한 전체 설정:

export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=your_api_key_here
...

4. LLM 모델 설정

에이전트가 사용할 거대 언어 모델(LLM)을 지정하려면 다음 두 곳에서 모델 이름을 구성해야 합니다:

• turtlesim_node.py
• turtlesim_agent.launch.xml (ROS 2 런치 파일을 사용하는 경우에만 해당)

기본 모델 이름 편집

turtlesim_node.py와 turtlesim_agent.launch.xml 모두에서 agent_model 파라미터를 사용하려는 모델과 일치하도록 업데이트하세요.

• Python (turtlesim_node.py):

  복사

  self.declare_parameter("agent_model", "gemini-2.0-flash")
  

  1

  2

  • Launch file (turtlesim_agent.launch.xml):

    복사

    <arg name="agent_model" default="gemini-2.0-flash"/>
    

    1

    2

  💡 기본 모델은 "gemini-2.0-flash"입니다. 선호하는 모델 이름(예: "gpt-4", "claude-3-opus" 등)으로 교체하세요.

LangChain이 사용자의 모델을 지원하는지 확인하세요

사용자 정의 모델 이름을 지정하는 경우, 해당 모델이 LangChain에서 지원되는지 확인해야 합니다. llm.py 내부의 로직을 확인하거나 업데이트하여 이를 검증할 수 있습니다.

• 모델이 아직 처리되지 않았다면, llm.py에 모델을 올바르게 로드할 수 있도록 해당하는 케이스를 추가하세요.
• 최신 지원 모델 및 제공업체(Provider)는 LangChain documentation을 참조하세요.

5. 변경 사항 적용하기

변수 설정을 마쳤다면, 빌드 및 변경 사항을 적용하여 설정을 완료하세요:

$ cd ~/{ROS_WORKSPACE} && colcon build
$ source ~/.bashrc  # 또는 source ~/.zshrc

▶️ 실행 방법

turtlesim_agent는 두 가지 상호작용 모드를 제공합니다:

• CLI 기반 인터페이스 (CLI-based interface): 디버깅 및 에이전트의 내부 추론(Reasoning)을 이해하는 데 권장됩니다.
• GUI 기반 채팅 인터페이스 (GUI-based chat interface): 직관적이고 사용자 친화적인 상호작용에 이상적입니다.

⌨️ CLI로 실행 (개발 시 권장)

$ ros2 run turtlesim turtlesim_node
$ ros2 run turtlesim_agent turtlesim_agent_node

🖼️ GUI로 실행 (채팅 인터페이스)

$ ros2 launch turtlesim_agent turtlesim_agent.launch.xml

🧰 AI 에이전트를 위해 제공되는 도구들

turtlesim_agent는 tools/ 디렉토리에 구현된 도구들을 호출 가능한 함수 (callable functions)로 활용하며, 사용자가 정의한 그리기 작업을 완수하기 위해 추론 과정 (reasoning process) 중에 이를 호출합니다.

📁 파일 구조

tools/
├── all_tools.py # 에이전트가 사용할 수 있는 모든 도구를 임포트(import)하고 내보냄(export)
├── math_tools.py # 기본적인 산술 및 기하학적 계산
...

🚀 에이전트의 창의성 확장하기

이 프로젝트의 핵심 아이디어 중 하나는 도구 증강 (tool augmentation)을 통한 창의적 표현의 가능화입니다. 에이전트의 능력을 더욱 향상시키고 싶다면, tools/ 디렉토리에 자신만의 도구를 자유롭게 추가해 보세요.

새로운 도구를 사용할 수 있게 만드는 방법:

1. tools/ 디렉토리에 새로운 *_tools.py 파일을 생성합니다.
2. LangChain 호환 시그니처 (LangChain-compatible signatures)를 사용하여 커스텀 함수를 정의합니다.
3. 에이전트가 접근할 수 있도록 all_tools.py에서 해당 함수들을 임포트(import)합니다.