For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

Agents API 빠른 시작

OpenAI가 호스팅하는 샌드박스에서 스크립트를 작성하고 실행하는 에이전트를 만드세요.

이 예제에서는 tree.py를 작성하고 실행해 디렉터리 트리를 보여 주는 코딩 어시스턴트를 만듭니다. OpenAI가 에이전트와 그 대화, 에이전트가 작업하는 샌드박스를 관리합니다.

사전 준비

OpenAI Platform 프로젝트에서 애플리케이션 API 키를 만드세요. 이 키에 세션 작업에 필요한 api.agents.read 및 api.agents.write 권한과 모델 추론에 필요한 api.responses.write 권한을 부여한 뒤, 다음과 같이 환경 변수로 설정하세요.

export OPENAI_API_KEY="your-api-key"

이 키는 에이전트의 샌드박스 외부에 보관하세요. 샌드박스 설정 방법과 제한 사항은 OpenAI 호스팅 샌드박스를 참고하세요.

요청에는 OpenAI-Beta: agents=v1 헤더가 필요합니다. OpenAI SDK는 이 헤더를 자동으로 추가합니다. cURL을 사용할 때는 헤더를 직접 추가하세요.

1. 작업 실행하기

언어를 선택하고 OpenAI SDK를 설치한 다음 예제를 실행하세요. SDK 예제에서는 beta.agents 네임스페이스를 사용합니다. 요청을 보내면 세션이 생성되고 작업이 제출되며 진행 상황이 스트리밍됩니다.

Python SDK를 설치하거나 업데이트하세요.

pip install --upgrade openai

예제 코드를 quickstart.py로 저장하세요.

tree.py 작성 및 실행
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

터미널에서 예제를 실행하세요.

python quickstart.py

샌드박스가 필요 없나요? 에이전트가 명령어를 실행하거나 로컬 파일을 다루지 않고 질문에 답하거나 외부 도구를 호출한다면 environment.type을 none으로 설정하세요. 자세히 알아보기.

2. 진행 상황 확인하기

터미널에는 이벤트가 수신되는 대로 표시됩니다. SDK 예제는 이벤트를 JSON으로 출력하고, cURL은 원본 이벤트 스트림을 표시합니다. 실행에 성공하면 에이전트가 tree.py를 작성하고 실행한 뒤 해당 파일이 포함된 디렉터리 트리를 보여 줍니다. 그 밖의 파일과 출력 내용은 샌드박스에 따라 달라집니다.

이벤트 스트림에서 agent.session.turn.completed를 찾은 다음 에이전트가 보고한 실행 결과를 확인하세요. 턴이 완료되었더라도 일부 도구 호출은 실패했을 수 있습니다. 이름이 turn.failed, turn.cancelled 또는 session.failed로 끝나는 이벤트는 실패 또는 취소를 나타냅니다. agent.session.idle 이벤트만으로는 성공 여부를 판단할 수 없습니다. 스트림이 중간에 끊기면 세션과 세션에 저장된 항목을 조회한 뒤 다시 시도하세요.

3. 세션 이어가기

이벤트에 포함된 session_id를 저장하세요. 이 ID로 후속 요청을 보내세요. 예를 들어 “tree.py에 최대 깊이 옵션을 추가하고 실행해서 출력 결과를 보여 줘.”라고 요청할 수 있습니다. 초기 이벤트를 놓치지 않도록 후속 요청을 보내기 전에 이벤트 스트림을 여세요.

4. 세션 정리하기

추가 작업에 사용할 세션은 유지하고, 작업을 모두 마쳤다면 삭제하세요. 삭제하기 전에 필요한 파일을 저장하세요.

예제의 sess_123을 앞에서 저장한 세션 ID로 바꾸세요.

세션 삭제
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

다음 단계