코드 기반 에이전트 만들기

에이전트 템플릿으로 저장소를 만들고, 사용할 온톨로지와 도구를 구성한 뒤, 시험한 코드를 비동기 Foundry 함수로 게시합니다.

사전 요건

• 에이전트가 읽고 변경할 온톨로지에 접근할 수 있어야 합니다.
• Foundry 환경에서 코드 저장소를 만들 권한이 있어야 합니다.
• 사용할 모델과 도구의 접근 권한을 갖추어야 합니다.

시험 중에도 모델 호출과 도구 작업은 실제로 실행될 수 있습니다. 먼저 비민감 실습 데이터와 필요한 최소 권한 범위로 시작합니다.

1. 템플릿과 저장소 선택

+ New repository를 선택하고 What are you building?에서 사용할 프레임워크의 에이전트 템플릿을 찾습니다. Claude Agent SDK, OpenAI Agents SDK와 Google ADK용 저장소 유형이 있습니다.

설정 화면에서 다음을 입력합니다.

저장소 생성 후 Build agents in Foundry 안내 화면이 열립니다.

업무 로직은 agent/, 공통 플랫폼 도구는 utils/에 배치됩니다.

2. 온톨로지와 도구 구성

필요한 객체 유형, 액션 유형과 질의 함수를 포함하는 Ontology SDK를 추가하고 생성합니다. 같은 SDK 리소스를 바탕으로 OMCP 도구도 구성됩니다.

OSDK 클라이언트는 생성된 SDK의 $ontologyRid로 만들 수 있습니다.

import { getOntologySdkClient } from "@palantir/agent-templates-bundle";
import { $ontologyRid } from "@ontology/sdk";

const client = await getOntologySdkClient($ontologyRid);

OMCP 연결은 프레임워크에 맞는 getOntologyMcpConfiguration으로 가져옵니다. 플랫폼이 인증정보와 연결 주소를 해석하므로 클라이언트 ID, 비밀값이나 Foundry 토큰을 직접 넣지 않습니다. 템플릿에서 각 프레임워크의 가져오기 경로와 연결 코드를 확인합니다.

3. 에이전트 로직 작성

agent/index.ts의 runAgent에서 다음을 구성합니다.

• 실행할 작업과 프롬프트
• 사용할 모델
• 모델이 호출할 MCP 서버와 사용자 지정 도구
• 모델 응답 스트림의 소비와 실패 처리

agent/systemPrompt.ts에서 동작 지침을, agent/customTools.ts에서 직접 구현한 도구를 관리합니다. 실행 인수는 AgentArguments 스키마에 정의합니다. SDK별 도구와 실행 루프 예시를 참고하여 구성 요소를 연결합니다.

4. 개발 환경에서 시험

생성된 저장소의 터미널에서 의존성을 설치하고 실행합니다. 다음은 가상의 추가 문맥을 전달하는 예입니다.

npm install
npm run start -- --json-args '{"additionalAgentContext":{"type":"string","string":"비민감 실습 데이터만 사용합니다."}}'

파일 입력에는 --json-args-file을 사용합니다. 인수의 정의와 전달 형식은 게시와 호출을 따릅니다.

게시 전에는 빌드가 오류 없이 끝나는지 확인합니다.

npm run build

5. 버전 게시

먼저 게시할 변경을 커밋합니다. 플랫폼의 코드 저장소 화면이나 Palantir VS Code 확장을 사용하는 편집기에서 작업할 수 있습니다.

기본 브랜치에서는 다음 중 한 방법으로 게시합니다.

• 저장소 화면의 Tag version에서 변경 범위에 맞는 버전을 지정하고 Tag and release를 선택합니다.
• 로컬 복제본에서 해당 버전의 Git 태그를 만들고 그 태그만 원격으로 보냅니다.

다음은 원격 이름이 origin, 게시할 버전이 1.0.0인 경우의 예입니다.

git tag 1.0.0
git push origin refs/tags/1.0.0

태그 게시 후 템플릿의 CI가 빌드를 비동기 Foundry 함수로 배포하며 온톨로지 바인딩과 API 이름을 등록합니다.

전역 브랜치는 이 Git 태그 절차를 사용하지 않습니다. 저장소 화면이 브랜치용 사전 릴리스를 생성해야 하므로 전역 브랜치 게시 절차를 따릅니다.

6. 워크플로에서 실행

Automate의 함수 효과가 에이전트 함수를 가리키도록 구성하는 방식이 권장됩니다. Workshop, OSDK와 온톨로지 액션에서도 비동기 함수 호출 경로를 사용할 수 있습니다.

에이전트 함수는 Void를 반환합니다. 결과를 사용하는 앱이 있다면 에이전트가 온톨로지 객체에 결과를 쓰고 앱이 해당 객체를 읽도록 구성합니다. 호출 계약과 제약을 확인합니다.

로그와 문제 조사

console.log(), console.warn(), console.error()로 실행을 연결할 수 있는 비민감 식별자와 상태를 남깁니다. 인증정보나 불필요한 민감 데이터를 기록하지 않습니다.

여러 실행을 검색할 때는 로그 검색의 모드를 구분합니다. 단일 실행 시작 리소스 검색에서 Automate가 에이전트를 호출했다면 에이전트 함수가 아니라 자동화 노드에서 검색합니다. 클라우드의 전역 검색은 에이전트 함수를 로그 생성 리소스로 선택하여 검색할 수도 있습니다.

공유 로그에는 실행 시작 리소스의 실행 이력 작업 권한, 로그 접근 활성화와 로그의 모든 표지에 대한 접근 권한이 필요합니다. 일반 인스턴스의 본인 실행 24시간 예외는 CBAC 환경에는 적용되지 않습니다. 자세한 조건은 로그 접근 권한을 따릅니다.