에이전트에게 새 툴 만들어 주기¶
툴은 에이전트의 손입니다. 내장 툴만으로도 센서를 읽고 주행하고 파일을 고치지만, 여기서는 어떤 툴을 쥐여줄지 직접 통제하고, 내 툴을 추가합니다.
툴박스 관리¶
- 패널 하단 TOOLS 배지.
- 체크박스로 툴을 켜고 끕니다. 꺼진 툴은 에이전트에게 보이지 않습니다 —
저학년용 안전한 에이전트를 만들 때도, "장님 상태"로 과제를 풀게 할 때도 이
방법을 씁니다. 체크 상태는 패널의 모델·effort·컨텍스트·읽어주기 설정과 함께
~/physicar_ws/agent/settings.json에 저장됩니다 — 처음 바꿀 때 파일이 생기고 (파일이 없으면 기본값), 이 머신의 모든 창이 같은 설정을 따릅니다.
실험: 카메라 툴을 끄고 "뭐가 보여?"라고 물어보세요 — 에이전트가 어떻게 대처하는지 보입니다.
커스텀 툴 추가¶
가장 빠른 방법은 튜터에게 시키는 것입니다:
"천천히 사각형으로 돌고 제자리로 오는
patrol툴 만들어줘."
에이전트가 커스텀 툴 파일 ~/physicar_ws/agent/tools.py에 툴을 작성해 줍니다 —
워크스페이스 안의 평범한 파일로, agent/instructions.md·agent/settings.json 옆에
있어 세션이 바뀌어도 남고 워크스페이스 백업에도 함께 담깁니다. 직접 열려면
TOOLS → Edit Code. 규칙은 간단합니다:
- 최상위 함수 하나가 툴 하나입니다. 에이전트에게는
custom_<함수명>으로 보입니다 (def patrol→custom_patrol)._로 시작하는 이름은 내부 헬퍼로 무시됩니다. - docstring이 툴 설명이고, 파라미터는
Annotated[타입, Field(description="...")](typing+pydantic)로 설명을 답니다. - 반환값은 콘텐츠 리스트입니다 —
{"type": "text", "text": ...}와{"type": "image", "mime": ..., "base64": ...}를 섞어 여러 개 돌려줄 수 있습니다. - 저장하면 다시 읽어 들이고, 바뀐 툴은 다음 메시지부터 호출됩니다. import 에러는 TOOLS 배지에 표시되며 그동안은 마지막으로 정상이던 버전이 계속 쓰입니다.
내장 툴도 똑같은 형식입니다 — 내장 섹션 옆 View Code로 열어 보면 그대로 예제가
됩니다. TOOLS 배지에 patrol이 나타나면(새 툴은 켜진 상태로 시작) 나도, 에이전트도
내장 툴처럼 부를 수 있습니다.
좋은 커스텀 툴은 작고 단일 목적입니다: 행동 하나, 명확한 파라미터, 짧은 반환 메시지. 복합 행동은 거대한 툴 하나가 아니라 instructions에서 조합하세요.
해보기¶
속도 + 최근접 라이다 거리를 한 줄로 반환하는 report_status 툴을 만들고,
instructions에 "주행이 끝나면 항상 report_status를 호출해"를 추가해 보세요.
툴콜링의 내부 동작 → 학습하기: LLM 에이전트
