Agents SDK
Agents SDK
에이전트는 도구를 사용해 작업을 계획하고 완료하고, 다른 에이전트와 협력하며, 단계를 거쳐 맥락을 유지할 수 있어요. 첫 에이전트부터 시작해 시작점을 고르고 SDK로 구축하는 방법을 안내하는 개요예요.
출처: 문서
본문
에이전트는 도구를 사용해 작업을 계획하고 완료하고, 다른 에이전트와 협력하며, 단계를 거쳐 맥락을 유지할 수 있어요.
첫 번째 에이전트 실행하기
Agents SDK quickstart로 시작해 SDK를 설치하고 에이전트 하나를 정의하고 실행하세요. 그게 작동하면, 여기로 돌아와 애플리케이션에 필요한 다음 능력을 선택하세요.
Agents SDK 받기
더 많은 예시, 이슈, 언어별 레퍼런스 세부 사항은 GitHub 저장소를 사용하세요.
[TypeScript SDK
Open the TypeScript SDK repository on GitHub.](https://github.com/openai/openai-agents-js)
[Python SDK
Open the Python SDK repository on GitHub.](https://github.com/openai/openai-agents-python)
시작점 선택하기
| 원하는 것 | 여기서 시작 | 이유 |
|---|---|---|
| 코드 우선 에이전트 앱 구축 | Quickstart | 작동하는 SDK 통합으로 가는 가장 짧은 경로예요. |
| 하나의 전문가를 깔끔하게 정의 | Agent definitions | 단일 에이전트의 계약을 다듬고 있을 때 여기서 시작하세요. |
| 모델, 기본값, 전송 선택 | Models and providers | 모델 선택, 제공자 설정, 또는 전송 전략이 워크플로우에 영향을 줄 때 사용하세요. |
| 런타임 루프와 상태 이해 | Running agents | 에이전트 루프, 스트리밍, 연속 전략이 여기 있어요. |
| 컨테이너 기반 환경에서 작업 실행 | Sandbox agents | 에이전트가 파일, 명령, 패키지, 스냅샷, 마운트, 제공자 링크가 필요할 때 사용하세요. |
| 전문가 소유권 설계 | Orchestration and handoffs | 에이전트가 여럿이고 누가 답변을 소유할지 결정해야 할 때 사용하세요. |
| 검증 또는 인간 검토 추가 | Guardrails and human review | 위험한 작업이 계속되기 전에 워크플로우가 차단하거나 일시 중지해야 할 때 사용하세요. |
| 실행이 반환하는 것 이해 | Results and state | 이 페이지는 최종 출력, 재개 가능한 상태, 다음 턴 표면을 설명해요. |
| 호스팅 도구, 함수 도구, MCP 추가 | Using tools 및 Integrations and observability | 도구 의미론은 플랫폼 도구 문서에, SDK 특유의 MCP와 트레이싱은 여기 있어요. |
| 실행 검사 및 개선 | Integrations and observability 및 evaluate agent workflows | 먼저 트레이스로 디버깅하고, 그 다음 평가 루프로 이동하세요. |
| 음성 우선 워크플로우 구축 | Voice agents | SDK 음성 파이프라인과 realtime 에이전트 패턴을 사용하세요. |
SDK로 구축하기
여러분의 서버가 배포, 도구 구현, 상태 저장, 승인 결정을 소유하고 SDK가 에이전트 루프를 실행하며 그 도구들을 호출할 때 SDK 트랙을 사용하세요. 이 경로는 다음을 원할 때 가장 잘 맞아요:
- TypeScript 또는 Python의 타입이 지정된 애플리케이션 코드
- 도구, MCP 서버, 런타임 동작에 대한 직접 제어
- 커스텀 저장소 또는 서버 관리 대화 전략
- 기존 제품 로직이나 인프라와의 긴밀한 통합
일반적인 SDK 읽기 순서는:
- Quickstart로 시작해 화면에 하나의 작동하는 실행을 띄우세요.
- Agent definitions와 Models and providers를 사용해 하나의 전문가를 깔끔하게 다듬으세요.
- 워크플로우가 더 복잡해짐에 따라 Running agents, Orchestration and handoffs, Guardrails and human review로 계속 진행하세요.
- 애플리케이션 로직이 실행 객체나 더 깊은 동작 가시성에 의존할 때는 Results and state와 Integrations and observability를 사용하세요.
에이전트 런타임 옵션 비교
Agents overview를 사용해 Agents SDK, Agents API, Responses API를 비교하세요. Agents SDK는 애플리케이션 안에서 실행되고, Agents API는 OpenAI 서비스에서 관리형 harness를 실행해요.
더 알아보기 (Learn more)
관련 문서: Agents SDK 퀵스타트와 에이전트 개요를 참고하세요.