함수 | OpenAI API

함수 도구를 사용하면 에이전트가 애플리케이션 코드를 호출할 수 있습니다. 개발자는 함수와 인자를 정의합니다. 에이전트가 함수 호출을 요청하고 애플리케이션 코드가 결과를 반환하면 하네스가 턴을 이어갑니다.

핸들러는 애플리케이션 서버, 워커 또는 직접 관리하는 환경에서 실행할 수 있습니다. 세션에 환경을 연결해도 그 환경에서 함수 도구가 자동으로 실행되지는 않습니다.

Responses API의 함수 호출을 사용하고 있다면 여기서 설명하는 세션 플로우에서도 기존 함수 구현을 재사용할 수 있습니다.

함수 정의하기

agent.tools에 함수 정의를 추가하는 작업은 에이전트를 구성할 때 수행하세요. 함수 이름과 설명을 지정하고 인자의 JSON 스키마를 정의하세요.

1234567891011{
  "type": "function",
  "name": "get_customer",
  "description": "Look up a customer by ID.",
  "parameters": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  }
}

필요한 작업 처리하기

에이전트에 함수 결과가 필요하면 세션에서 agent.session.requires_action 이벤트가 발생합니다. event.session.required_actions에서 대기 중인 호출을 확인하세요. 스트리밍 없이도 세션을 조회해 session.required_actions를 확인할 수 있습니다.

required_actions의 함수 호출 항목은 다음과 같습니다.

1234567{
  "type": "function_call",
  "turn_id": "turn_123",
  "call_id": "call_123",
  "name": "get_customer",
  "arguments": { "customer_id": "123" }
}

지정된 이름의 함수에 전달받은 인자를 넣어 실행하세요. 어떤 호출에 결과를 반환해야 하는지는 required_actions에서 확인하세요. 세션 기록에 function_call 항목이 있다는 사실만으로는 해당 호출이 아직 결과를 기다리고 있는지 알 수 없습니다.

결과 반환하기

agent.session.input.tool_result를 세션 이벤트 엔드포인트로 보내세요. 대기 중인 작업에서 turn_id와 call_id를 복사하세요.

성공하면 success: true로 설정하고 output에 문자열이나 지원되는 형식의 콘텐츠 배열을 전달하세요. JSON 객체는 문자열로 직렬화하세요.
오류가 발생하면 success: false로 설정하고 error에 에이전트가 활용할 수 있는 오류 메시지를 전달하세요.

대기 중인 get_customer 호출마다 고객 정보를 조회하고 그 결과를 반환하세요. 다음 예제에서 action은 required_actions에 있는 항목입니다.

함수 결과 반환하기

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const result = {
  turn_id: action.turn_id,
  call_id: action.call_id,
};
let outcome;

outcome = {
  success: true,
  output: JSON.stringify(getCustomer(action.arguments)),
};

await client.beta.agents.sessions.events.create(sessionId, {
  events: [
    { type: "agent.session.input.tool_result", ...result, ...outcome },
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14import json

action = action.to_dict()

result = {
    "type": "agent.session.input.tool_result",
    "turn_id": action["turn_id"],
    "call_id": action["call_id"],
}

output = get_customer(action["arguments"])
result.update(success=True, output=json.dumps(output))

client.beta.agents.sessions.events.create(session_id, events=[result])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24result := openai.AgentSessionInputParamAgentSessionInputToolResult{
	TurnID: action.TurnID,
	CallID: action.CallID,
}

arguments := action.Arguments.(map[string]any)
customerID := arguments["customer_id"].(string)
var customer any
if customerID == "123" {
	customer = map[string]any{"name": "Example Customer", "plan": "pro"}
}
output, err := json.Marshal(map[string]any{"found": customer != nil, "customer": customer})
if err != nil {
	panic(err)
}
result.Success = true
result.Output = openai.AgentFunctionCallOutputParamUnion{OfString: openai.String(string(output))}

err = client.Beta.Agents.Sessions.Events.New(ctx, session.ID, openai.BetaAgentSessionEventNewParams{
	Events: []openai.AgentSessionInputParamUnion{{OfParamAgentSessionInputToolResult: &result}},
})
if err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25var json = new JsonMapper();

var result =
    AgentSessionInputParam.AgentSessionInputToolResult.builder()
        .turnId(action.turnId())
        .callId(action.callId());
var arguments = json.valueToTree(action._arguments());

boolean found = arguments.path("customer_id").asText().equals("123");
var output = json.createObjectNode().put("found", found);
if (found)
  output.putObject("customer").put("name", "Example Customer").put("plan", "pro");
else output.putNull("customer");
result.success(true).output(json.writeValueAsString(output));

client
    .beta()
    .agents()
    .sessions()
    .events()
    .create(
        EventCreateParams.builder()
            .sessionId(sessionId)
            .addEvent(result.build())
            .build());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "json"

result = {
  type: "agent.session.input.tool_result",
  turn_id: action.turn_id,
  call_id: action.call_id
}
arguments = action.arguments

customer_id = arguments[:customer_id] || arguments["customer_id"]
customer = (customer_id == "123") ? {
  name: "Example Customer",
  plan: "pro"
} : nil
result[:success] = true
result[:output] = JSON.generate(found: !customer.nil?, customer: customer)

client.beta.agents.sessions.events.create(session.id, events: [result])

하네스는 필요한 결과를 받으면 턴을 이어갑니다. 세션 이벤트 및 항목을 추적해 턴이 어떻게 끝났는지 확인하고 출력을 가져오세요.

결과 크기

도구 결과가 너무 커서 API가 거부하면 결과 크기를 4 MiB(4,194,304바이트) 미만으로 줄이세요. 이때 Agents API 메타데이터를 위한 여유 공간을 조금 남겨 두세요. 호출이 아직 대기 중일 때 같은 turn_id와 call_id로 다시 시도하세요.

연결이 끊긴 후 복구하기

세션을 조회해 대기 중인 작업을 확인하세요. 이미 함수를 실행했다면 같은 turn_id와 call_id로 저장해 둔 결과를 제출하세요.

사이드 이펙트가 있는 함수는 세션 ID, 턴 ID, 호출 ID를 기준으로 결과를 영구 저장소에 보관하세요. 함수가 정상적으로 실행됐을 가능성이 있는데 저장된 결과가 없다면, 함수를 다시 실행하기 전에 실행 결과를 확인하세요.

필요할 때 함수 로드하기

기본적으로 함수는 미리 로드됩니다. 함수 로드를 미루려면 함수 정의에 defer_loading: true를 설정하고 { "type": "tool_search" }를 agent.tools에 추가하세요. 전체 예제는 도구 검색을 참고하세요.

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스