세션 관리하기

세션 관리하기 (Manage sessions)

각 세션 ID를 애플리케이션의 데이터 저장소와 함께 보관하세요. 세션의 현재 상태를 검색하거나, 에이전트의 요청을 처리하거나, 세션을 삭제하는 데 사용해요.

출처: 문서

본문

세션 찾기 (Find sessions)

프로젝트에서 세션을 나열해 이전 작업을 살펴보세요. SDK 페이지네이션 헬퍼로 추가 페이지를 가져와요:

세션 나열하고 다음 페이지 가져오기

import OpenAI from "openai";

const client = new OpenAI();
let page = await client.beta.agents.sessions.list({ limit: 20 });
console.log(page.data);
if (page.hasNextPage()) {
  page = await page.getNextPage();
  console.log(page.data);
}

from openai import OpenAI

client = OpenAI()
page = client.beta.agents.sessions.list(limit=20)
print(page.to_json())
if page.has_next_page():
    page = page.get_next_page()
    print(page.to_json())

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.List(ctx,
	openai.BetaAgentSessionListParams{Limit: openai.Int(20)})
if err != nil {
	panic(err)
}
fmt.Println(result.Data)
if result.HasMore {
	result, err = result.GetNextPage()
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Data)
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionListParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client.beta().agents().sessions().list(SessionListParams.builder().limit(20L).build());
System.out.println(result.items());
if (result.hasNextPage()) {
  result = result.nextPage();
  System.out.println(result.items());
}

require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.list(limit: 20)
puts result.data
if result.next_page?
  result = result.next_page
  puts result.data
end

page=$(curl -sS --fail-with-body "https://api.openai.com/v1/agents/sessions?limit=20&order=desc" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer ***")
after=$(printf '%s' "$page" | jq -r 'select(.has_more) | .last_id // empty')

if [ -n "$after" ]; then
  curl --get "https://api.openai.com/v1/agents/sessions" \
    -H "OpenAI-Beta: agents=v1" \
    -H "Authorization: Bearer ***" \
    --data-urlencode "after=$after" \
    --data-urlencode "limit=20"
fi

세션 검사하기 (Inspect a session)

세션을 검색해 상태, 에이전트 구성, 환경, required_actions를 읽으세요. API 클라이언트와 대화의 세션 ID를 전달하세요:

세션 검색하기

// Pass your saved session ID to this helper.
async function retrieveSession(client, sessionId) {
  return client.beta.agents.sessions.retrieve(sessionId);
}

# Pass your saved session ID to this helper.
def retrieve_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.retrieve(session_id)

// Pass your saved session ID to this helper.
func retrieveSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSession, error) {
	return client.Beta.Agents.Sessions.Get(ctx, sessionID)
}

// Pass your saved session ID to this helper.
public static AgentSession retrieveSession(OpenAIClient client, String sessionId) {
  return client
      .beta()
      .agents()
      .sessions()
      .retrieve(SessionRetrieveParams.builder().sessionId(sessionId).build());
}

# Pass your saved session ID to this helper.
def retrieve_session(client, session_id)
  client.beta.agents.sessions.retrieve(session_id)
end

curl \
  "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer ***"

전체 응답 스키마는 Retrieve session 레퍼런스를 참고하세요.

필수 작업 처리하기 (Handle required actions)

상태가 requires_action인 세션은 작업이 계속되려면 애플리케이션이 먼저 동작해야 해요. agent.session.requires_action를 받으면 세션을 검색하고 required_actions의 각 항목을 검사하세요:

  • function_call: name이 가리키는 함수를 arguments로 실행하세요. 같은 세션에 그 작업의 turn_id와 call_id로 결과를 반환하세요. 함수 도구를 참고하세요.
  • environment_connection: environment_id가 가리키는 환경을 연결하세요. 환경 연결을 참고하세요.

이벤트는 언제 확인할지, 검색된 세션은 무엇을 할지를 알려 줘요. 재시작이나 스트림 끊김 후에는 세션을 검색해 대기 중인 작업을 찾으세요. 처리한 뒤에는 턴의 결과를 위해 이벤트를 계속 따라가세요.

저장된 메시지, 도구 호출, 턴 결과는 Fetch items and turns를 참고하세요. 어떤 에이전트가 명령을 실행했는지 식별하려면 위임 관찰을 참고하세요.

세션 삭제하기 (Delete a session)

애플리케이션이 더 이상 필요 없을 때 세션을 삭제하세요. 삭제는 API에서 세션을 제거해요. 물리적 정리는 비동기로 계속될 수 있어요.

세션 삭제하기

// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

async function deleteSession(client, sessionId) {
  return client.beta.agents.sessions.delete(sessionId);
}

const result = await deleteSession(new OpenAI(), "sess_123");
console.log(result);

# 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())

// Replace the illustrative IDs and URLs below with your own resource values.
package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func deleteSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSessionDeleted, error) {
	return client.Beta.Agents.Sessions.Delete(ctx, sessionID)
}

func main() {
	client := openai.NewClient()
	result, err := deleteSession(context.Background(), &client, "sess_123")
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}

// Replace the illustrative IDs and URLs below with your own resource values.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentSessionDeleted;
import com.openai.models.beta.agents.sessions.SessionDeleteParams;

public final class AgentsApiSessionsDeleteSessionExample {
  public static AgentSessionDeleted deleteSession(OpenAIClient client, String sessionId) {
    return client
        .beta()
        .agents()
        .sessions()
        .delete(SessionDeleteParams.builder().sessionId(sessionId).build());
  }

  public static void main(String[] args) {
    var result = deleteSession(OpenAIOkHttpClient.fromEnv(), "sess_123");
    System.out.println(result);
  }
}

# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

def delete_session(client, session_id)
  client.beta.agents.sessions.delete(session_id)
end

puts delete_session(OpenAI::Client.new, "sess_123")

curl -X DELETE \
  "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer ***"

현재 작업을 멈추고 대화는 유지하려면 활성 턴 취소를 사용하세요. 삭제 응답은 Delete session 레퍼런스를 참고하세요.

더 알아보기 (Learn more)