에이전트는 도구를 사용해 작업을 계획하고 완료할 수 있습니다. 다른 에이전트와 협업하고 여러 단계에 걸쳐 컨텍스트를 유지할 수도 있습니다.
첫 에이전트 실행하기
Agents SDK 빠른 시작에 따라 SDK를 설치하고 에이전트 하나를 정의한 뒤 실행하세요. 에이전트가 정상적으로 실행되면 이 페이지로 돌아와 애플리케이션에 필요한 다음 기능을 선택하세요.
Agents SDK 리포지터리
GitHub 리포지터리에서 더 많은 예제와 이슈, 언어별 레퍼런스 문서를 확인하세요.
목적에 맞는 문서 선택하기
| 목적 | 먼저 읽을 문서 | 이 문서를 읽는 이유 |
|---|---|---|
| 코드 중심의 에이전트 앱 만들기 | 빠른 시작 | SDK를 연동하고 실행해 보는 가장 빠른 방법입니다. |
| 전문 에이전트 하나를 명확하게 정의하기 | 에이전트 정의 | 에이전트 하나가 맡을 역할과 입출력 규약을 구체화하는 단계에서 참고하세요. |
| 모델, 기본값, 전송 방식 선택하기 | 모델 및 제공자 | 모델 선택, 제공자 설정 또는 전송 전략이 워크플로우에 영향을 줄 때 참고하세요. |
| 런타임 루프와 상태 이해하기 | 에이전트 실행 | 에이전트 루프와 스트리밍, 실행을 이어 가는 방법을 다룹니다. |
| 컨테이너 기반 환경에서 작업 실행하기 | 샌드박스 에이전트 | 에이전트에 파일, 명령어, 패키지, 스냅샷, 마운트 또는 제공자 연결이 필요할 때 참고하세요. |
| 전문 에이전트별 책임 정하기 | 오케스트레이션 및 핸드오프 | 여러 에이전트가 필요하고 어느 에이전트가 응답을 맡을지 정해야 할 때 참고하세요. |
| 검증 또는 사람의 검토 추가하기 | 가드레일 및 사람의 검토 | 위험한 작업을 계속하기 전에 워크플로우를 차단하거나 일시 중지해야 할 때 참고하세요. |
| 실행 시 반환되는 값 이해하기 | 결과 및 상태 | 최종 출력, 실행을 재개할 때 필요한 상태, 다음 턴에서 사용할 수 있는 인터페이스를 설명합니다. |
| 호스팅 도구, 함수 도구 또는 MCP 추가하기 | 도구 사용과 통합 및 관측 가능성 | 플랫폼 도구 문서에서는 도구의 동작 방식을, SDK 통합 문서에서는 SDK에서 MCP와 트레이싱을 사용하는 방법을 설명합니다. |
| 실행 과정 점검 및 개선하기 | 통합 및 관측 가능성과 에이전트 워크플로우 평가 | 먼저 트레이스로 디버깅한 다음 반복 평가를 진행하세요. |
| 음성 중심 워크플로우 만들기 | 음성 에이전트 | SDK의 음성 파이프라인과 실시간 에이전트 패턴을 활용하세요. |
SDK로 개발하기
애플리케이션 서버가 배포, 도구 구현, 상태 저장, 승인 여부 결정을 담당하고 SDK가 에이전트 루프를 실행하면서 해당 도구를 호출하는 구조라면 SDK를 사용하세요. 다음과 같은 요구 사항에 가장 적합합니다.
- TypeScript 또는 Python으로 타입을 명시한 애플리케이션 코드 작성
- 도구, MCP 서버, 런타임 동작을 직접 제어
- 사용자 지정 저장소 사용 또는 서버에서 대화 관리 방식 결정
- 기존 제품 로직이나 인프라와 긴밀하게 통합
SDK 문서는 보통 다음 순서로 읽습니다.
- 빠른 시작에 따라 에이전트를 한 번 실행하고 화면에서 결과를 확인하세요.
- 에이전트 정의와 모델 및 제공자를 참고해 전문 에이전트 하나의 역할과 구성을 명확히 정하세요.
- 워크플로우가 복잡해지면 에이전트 실행, 오케스트레이션 및 핸드오프, 가드레일 및 사람의 검토를 차례로 읽으세요.
- 애플리케이션 로직에서 실행 객체를 사용하거나 에이전트의 동작을 더 자세히 파악해야 한다면 결과 및 상태와 통합 및 관측 가능성을 참고하세요.
에이전트 런타임 옵션 비교하기
에이전트 개요에서 Agents SDK, Agents API, Responses API를 비교하세요. Agents SDK는 애플리케이션에서 실행되며, Agents API는 OpenAI 서비스에서 관리형 하네스를 실행합니다.