ConnectOnion 함수 도구 연결, 에이전트가 무엇을 했는지 기록까지 남기는 법
AI 에이전트에 함수를 붙인 뒤 가장 답답한 순간은 “그래서 이 함수가 실제로 불렸나?”가 보이지 않을 때입니다. ConnectOnion 공식 README는 일반 파이썬 함수를 tools에 등록하고 agent.history.summary()로 행동 이력을 읽는 흐름을 제시합니다.
첫 데모는 함수 하나와 실행 이력 하나만 끝까지 대조하면 충분합니다.
30초 요약
- 타입 힌트와 docstring이 도구 입력 설명의 재료가 됩니다.
tools=[search_docs]로 일반 함수를 에이전트에 등록합니다.- 응답과 실행 이력은 따로 읽어야 호출 여부를 점검할 수 있습니다.
- 아래는 공식 README를 바탕으로 재구성한 문서 기반 예제이며, 이 글 작성 환경에서 실행한 결과는 아닙니다.
함수 하나를 도구로 바꾸려면 무엇이 필요할까?
ConnectOnion은 타입 힌트와 docstring이 있는 평범한 파이썬 함수를 도구로 쓰는 예제를 제공합니다. 생활 비유로 보면 에이전트는 요청을 분류하는 비서이고, 함수는 각 업무 창구입니다.
창구 이름과 처리 범위를 분명히 적어야 엉뚱한 줄로 보내지 않습니다.
from connectonion import Agent
def search_docs(query: str) -> str:
"""문서에서 검색어와 일치하는 항목을 찾아 짧게 돌려준다."""
return f"문서 검색 결과: {query}"
agent = Agent(name="daily-demo", tools=[search_docs])
answer = agent.input("ConnectOnion 도구 연결 방식을 찾아줘")
print(answer)
함수 호출 코드와 tools 등록을 분리해 보면 디버깅 범위가 훨씬 작아집니다. 함수는 보통의 파이썬 함수이고 Agent가 이를 도구 인터페이스로 해석합니다.
직접 호출과 에이전트 호출은 어디가 다를까?
직접 호출에서는 개발자가 함수를 고릅니다. 에이전트 호출에서는 모델이 등록된 도구 설명을 참고해 호출 여부와 인자를 정합니다.
| 단계 | 직접 함수 호출 | 에이전트 도구 호출 |
|---|---|---|
| 입력 | search_docs("도구") |
agent.input("도구 연결 방식을 찾아줘") |
| 선택 주체 | 개발자 코드 | 등록된 도구 설명을 참고하는 에이전트 |
| 확인할 것 | 반환값·예외 | 응답과 도구 호출 흔적 |
함수 반환 문자열은 예측할 수 있어도, 자연어 요청에서 도구가 실제로 선택되는지와 최종 응답 형태는 모델·프롬프트·환경에 따라 달라집니다. 문서 예시의 출력 모양을 실제 실행 결과처럼 쓰면 안 됩니다.
하루 데모에서 실행 기록은 이렇게 확인한다
README는 agent.history.summary() 예시와 .co/logs/{agent_name}.log 기본 로그 위치를 안내합니다. 응답은 사용자에게 보이는 결과이고, 이력은 그 결과를 점검하는 단서입니다.
answer = agent.input("ConnectOnion 함수 도구를 한 번 써줘")
print("응답:", answer)
print("실행 이력:", agent.history.summary())
이 예제는 어디를 확인할지 잡아 주는 문서 기반 데모입니다. 실제 출력 전체를 저장해 요청 문장, 도구 이름, 전달된 인자, 반환값을 대조하세요.
- 도구 선택: 의도한 함수가 호출 흔적에 나타나는가
- 입력값: 요청의 핵심어가 함수 인자와 맞는가
- 실패 지점: 함수 내부 예외인지, 도구 선택 이전 문제인지 구분되는가
디버그 로그는 편하지만 운영 데이터 보관 정책을 대신하지는 않습니다. 토큰·개인정보·비밀값이 기록될 수 있다면 접근 권한과 마스킹 기준을 먼저 정해야 합니다.
다음 단계와 한계
처음부터 메일·브라우저·파일 권한을 한 에이전트에 몰아넣으면 문제의 위치를 좁히기 어렵습니다. 외부 부작용이 없는 함수부터 시작하고, 서비스에서는 읽기 전용 도구와 승인 경계를 분리하세요.
첫날의 목표는 기능을 많이 붙이는 일이 아니라 한 호출을 끝까지 설명할 수 있는 기록을 남기는 일입니다.
README 기준으로 ConnectOnion은 Python 3.10 이상과 pip install connectonion을 안내합니다. 2026년 9월 26일 확인한 공식 Releases에서 최신 안정 릴리스는 v1.8.8(2026년 9월 25일 공개)이며, v1.8.9b8은 pre-release로 표시됩니다.
작업 환경을 함께 정리한다면
코드와 터미널 로그를 한 화면에 보기 어려운 작업자에게는 보조 화면 역할의 카드입니다.
실행 조건과 오류 문구를 별도 메모로 남기는 작업자에게는 짧은 입력 장치 역할의 카드입니다.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
출처
핵심 정리: 다섯 가지 질문과 답
Q. 함수는 클래스로 감싸야 하나요?
아닙니다. 공식 README는 일반 파이썬 함수를 tools에 전달하는 예제를 제공합니다.
Q. 호출 여부는 무엇으로 보나요?
응답과 별도로 agent.history.summary()와 기본 로그를 대조합니다.
Q. 이 글의 출력은 실측 결과인가요?
아닙니다. 공식 문서를 바탕으로 한 문서 기반 예제입니다.
Q. 처음부터 도구를 여러 개 붙여도 되나요?
원인 분리를 위해 부작용 없는 함수 하나부터 시작하는 편이 낫습니다.
Q. 운영 환경에서도 이력만 보면 충분한가요?
아닙니다. 권한 통제와 민감정보 마스킹·보관 정책이 함께 필요합니다.
'AI > 오픈 소스 소개' 카테고리의 다른 글
| Kiro Crew 0.7.1, 재시작 뒤에도 이어지는 작업은 어디까지일까 (0) | 2026.09.27 |
|---|---|
| Orca Git worktree 데모, 에이전트 답이 섞일 때 비교부터 분리하는 법 (0) | 2026.09.25 |
| Smithers 0.35.0 복구 데모, 실패한 에이전트 작업을 처음부터 다시 돌리기 전에 (0) | 2026.09.22 |
| VeloxQuant-MLX로 긴 대화를 붙잡을 때, 압축률보다 먼저 볼 것 (0) | 2026.09.21 |
| SandBase Harness, 도구 실행이 멈췄을 때 승인 흐름을 확인하는 법 (0) | 2026.09.20 |
댓글