Agent Studio 의 Tool 은 에이전트 프로세스 안에서 함수로 호출되는 것이 아니라 별도 프로세스로 실행되는 파이썬 스크립트 다. 에이전트는 두 개의 JSON 문자열을 명령행 인자로 넘기고, 스크립트는 결과를 표준 출력에 찍는다.
Agent 또는 Tool Playground
│ --user-params '{"api_key": "..."}'
│ --tool-params '{"a": 1, "b": 2, "op": "+"}'
▼
Pydantic 검증 → run_tool() → print(OUTPUT_KEY, output)
프로세스가 분리되어 있으므로 Tool 마다 requirements.txt 로 의존성을 따로 가질 수 있고, 한 Tool 이 죽어도 에이전트가 함께 죽지 않는다. 반대로 에이전트 메모리의 객체를 그대로 넘겨받을 수는 없다. 주고받는 것은 JSON 으로 표현 가능한 값뿐이다.
from pydantic import BaseModel, Field
from typing import Literal
import json
import argparse
from calc import run_calc
class UserParameters(BaseModel):
"""Tool 을 등록·설정할 때 넣는 값. API 키, 접속 정보, 환경 변수 등."""
pass
class ToolParameters(BaseModel):
"""에이전트가 호출할 때 넘기는 인자. description 이 에이전트에게 그대로 보인다."""
a: float = Field(description="first number")
b: float = Field(description="second number")
op: Literal["+", "-", "*", "/"] = Field(description="operator")
def run_tool(config: UserParameters, args: ToolParameters):
return run_calc(args.a, args.b, args.op)
OUTPUT_KEY = "tool_output"
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--user-params", required=True, help="JSON string for tool configuration")
parser.add_argument("--tool-params", required=True, help="JSON string for tool arguments")
args = parser.parse_args()
config = UserParameters(**json.loads(args.user_params))
params = ToolParameters(**json.loads(args.tool_params))
output = run_tool(config, params)
print(OUTPUT_KEY, output)
Tool 을 등록하는 사람이 미리 채우는 값이다. API 키, 엔드포인트 URL, DB 접속 정보가 여기 들어간다. 에이전트는 이 값을 보지도 정하지도 못한다. 필요 없으면 pass 로 비워 둔다.
자격증명은 이 자리로 몰아야 한다. ToolParameters 에 두면 에이전트가 값을 지어내려 시도하게 된다.
에이전트가 매 호출마다 정하는 값이다. Field(description=...) 의 문구가 그대로 에이전트에게 전달되어 인자 판단의 근거가 된다. 여기서 모호하게 쓰면 에이전트가 엉뚱한 값을 넣는다. 단위, 형식, 허용 범위를 문장으로 적는다.
값이 정해진 목록이면 Literal 로 좁힌다. 자유 문자열보다 훨씬 안정적이다. 필수가 아닌 인자는 Optional 과 기본값으로 둔다.
인터페이스 정의와 비즈니스 로직을 나누는 것이 관례다. 위 예에서 계산은 calc.py 의 run_calc() 에 있고, Tool 파일은 인터페이스만 맡는다. 로직을 따로 두면 Tool 밖에서도 단위 테스트를 할 수 있다.
반환값은 에이전트가 읽을 텍스트다. 표·표본 데이터처럼 큰 결과를 그대로 돌려주면 컨텍스트를 잡아먹으므로, 요약이나 상위 몇 건만 돌려주고 전체는 파일로 남기는 구성이 낫다.
print(OUTPUT_KEY, output) 한 줄이 에이전트가 결과를 집어 가는 지점이다. 이 관례를 깨고 아무 곳에나 print 를 하면 그 출력이 결과에 섞인다. 디버깅 출력은 print 가 아니라 stderr 나 로깅으로 보낸다.
run_tool 안에서 예외가 나면 스크립트가 0 이 아닌 코드로 끝나고 에이전트는 실패로 받는다. 에이전트가 스스로 고칠 수 있는 오류(인자가 틀렸다, 없는 대상이다)는 예외 대신 설명이 담긴 문자열을 반환 하는 편이 낫다. 에이전트가 그 문장을 읽고 인자를 고쳐 다시 부른다.
반대로 자격증명 오류나 네트워크 단절처럼 재시도가 의미 없는 것은 예외로 올려 빨리 실패시킨다.
Agent Studio 에는 바로 쓸 수 있는 Tool 들이 들어 있다. 새로 만들기 전에 같은 계열이 있는지 본다.
| 갈래 | 예 |
|---|---|
| 계산·유틸 | 사칙연산, 날짜 계산 |
| 파일 | 디렉터리 목록, CSV · JSON 읽기, PDF 읽기, Markdown → PDF 변환 |
| 표 형식 질의 | 아티팩트 디렉터리의 CSV · Parquet 에 SQL 실행, 스키마 조회 |
| 데이터베이스 | 설정된 DB 에 SQL 실행 후 DataFrame 을 텍스트로 반환 |
| 협업 도구 | Jira REST 범용 호출, SMTP 메일 발송, Slack 메시지·파일 전송, 캘린더 일정 생성 |
| 플랫폼 연계 | Hugging Face 데이터셋을 데이터레이크로 반입, S3 Parquet 을 CDW 테이블로 등록, CDV 데이터셋·비주얼 생성 |
파일·표 형식 도구가 다루는 아티팩트 디렉터리 는 에이전트 실행 단위의 작업 디렉터리다. 도구 사이에 파일을 주고받는 통로가 되며, 한 도구가 내려받은 CSV 를 다음 도구가 SQL 로 질의하는 식으로 이어진다.
표 형식 질의 도구의 필터는 대개 AND 로만 결합 된다. OR 조건이 필요하면 필터 인자가 아니라 SQL 을 직접 넘긴다.
Jira Tool 은 동작 종류를 고정하지 않고 HTTP 메서드 · 경로 · 쿼리 · 본문을 인자로 받아 아무 API 나 호출한다. 표현력은 최대지만 에이전트가 경로를 지어내면 그대로 호출된다. 운영 환경에 붙일 때는 읽기 전용 계정을 쓰거나, UserParameters 로 허용 경로 접두사를 받아 run_tool 안에서 검사하는 식으로 좁힌다.