에이전트 설정은 에이전트의 동작을 정의합니다. 세션을 만들 때 설정을 직접 지정하거나 나중에 재사용할 수 있도록 저장할 수 있습니다. 세션에는 대화와 작업이 담기고, 저장된 에이전트에는 재사용할 설정이 담깁니다.
먼저 모델과 지침을 정한 다음 작업에 필요한 도구와 제어 옵션을 추가하세요.
- 모델: 작업을 수행할 모델을 지정합니다.
- 지침: 에이전트가 수행할 작업과 동작 방식을 정의합니다.
- 도구: 웹 검색이나 사용자 정의 함수 호출 등 에이전트가 수행할 수 있는 동작을 지정합니다.
- 추론 및 출력: 모델의 추론 수준과 응답 형식, 응답의 상세도를 지정합니다.
세션을 만들 때 agent에 이 설정을 전달하세요. 다음 예시에서는 모델, 지침, 첫 번째 사용자 메시지를 지정합니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Answer the user clearly and concisely.",
},
environment: {
type: "none",
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "What can you help with?",
},
],
},
],
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Answer the user clearly and concisely.",
},
environment={"type": "none"},
input=[
{
"role": "user",
"content": [{"type": "input_text", "text": "What can you help with?"}],
}
],
)
print(session.to_json())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Answer the user clearly and concisely."),
},
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
},
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(result)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Answer the user clearly and concisely.")
.build())
.environmentNone()
.input("What can you help with?")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"
client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
agent: {
model: "gpt-6-astra",
instructions: "Answer the user clearly and concisely."
},
environment: { type: "none" },
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "What can you help with?"
}
]
}
]
)
puts result
설정 필드와 값은 Agents API 레퍼런스를 참고하세요. 설정 방법은 함수, 컴퓨터 사용, MCP 연결 또는 여러 에이전트 간 작업 위임을 참고하세요.
지침과 도구 설정을 합한 크기는 4 MiB(4,194,304바이트) 미만으로 유지하고 Agents API 메타데이터를 위한 여유 공간을 조금 남겨 두세요. 설정이 너무 커서 세션을 시작할 수 없다면 지침과 도구 설정의 크기를 줄여 새 세션을 만드세요.
환경에 업로드하는 파일에는 별도의 파일 제한이 적용됩니다.
여러 세션에서 같은 설정을 재사용하려면 에이전트를 저장하세요. 에이전트를 한 번 만든 뒤 각 세션을 시작할 때 해당 ID를 agent_id로 전달하세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();
const agent = await client.beta.agents.create({
model: "gpt-6-astra",
instructions: "Answer technical questions accurately.",
reasoning: {
summary: "auto",
},
});
const session = await client.beta.agents.sessions.create({
agent_id: agent.id,
environment: { type: "none" },
input: "Explain how an agent connects to an MCP server.",
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai import OpenAI
client = OpenAI()
agent = client.beta.agents.create(
model="gpt-6-astra",
instructions="Answer technical questions accurately.",
reasoning={"summary": "auto"},
timeout=360,
)
session = client.beta.agents.sessions.create(
agent_id=agent.id,
environment={"type": "none"},
input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
openai.BetaAgentNewParams{
Model: "gpt-6-astra",
Instructions: openai.String("Answer technical questions accurately."),
Reasoning: openai.AgentReasoningParam{Summary: "auto"},
})
if err != nil {
panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
AgentID: openai.String(agent.ID),
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
})
if err != nil {
panic(err)
}
fmt.Println(result)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
client
.beta()
.agents()
.create(
AgentCreateParams.builder()
.model("gpt-6-astra")
.instructions("Answer technical questions accurately.")
.reasoning(
AgentReasoningParam.builder()
.summary(AgentReasoningParam.Summary.of("auto"))
.build())
.build());
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agentId(agent.id())
.environmentNone()
.input("Explain how an agent connects to an MCP server.")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"
client = OpenAI::Client.new
agent = client.beta.agents.create(
model: "gpt-6-astra",
instructions: "Answer technical questions accurately.",
reasoning: { summary: "auto" }
)
result = client.beta.agents.sessions.create(
agent_id: agent.id,
environment: { type: "none" },
input: "Explain how an agent connects to an MCP server."
)
puts result
세션마다 대화와 작업은 독립적으로 유지됩니다. 저장된 에이전트의 목록을 보거나 개별 에이전트를 조회, 업데이트 또는 삭제하는 방법은 Agents API 레퍼런스를 참고하세요. 자격 증명은 저장된 설정과 별도로 보관소에 보관됩니다.
저장된 에이전트의 변경 사항은 새 세션에만 적용됩니다. 각 세션은 생성 시점에 저장된 설정을 복사하고 이후 턴에도 그 설정을 유지합니다. 기존 세션을 변경하려면 해당 세션의 설정을 업데이트하세요.
저장된 에이전트를 업데이트할 때는 다음 규칙이 적용됩니다.
- 생략한 필드는 저장된 값을 유지합니다.
model만 변경하면 reasoning, service_tier, text는 그대로 유지됩니다.
- 객체를 전달하면 해당 필드의 값 전체를 교체합니다.
reasoning에 effort만 지정하면 저장된 summary도 삭제됩니다.
null을 허용하는 필드는 이 값을 전달해 초기화할 수 있습니다. 예를 들어 reasoning: null을 지정하면 모델의 기본 추론 수준으로 돌아갑니다.
새 모델이 지원하지 않는 설정은 모델을 변경하는 요청에서 함께 변경하거나 초기화하세요.
저장된 에이전트의 설정을 세션에 맞게 조정하려면 세션 생성 요청에 agent_id와 agent를 모두 포함하세요. 모델을 비롯해 요청에서 생략한 설정은 세션 생성 시점에 저장된 에이전트에서 복사됩니다.
다음 예시를 실행하기 전에 예시 값 agent_123을 저장된 에이전트의 ID로 바꾸세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();
const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
agent_id: agentId,
agent: {
instructions: "Answer this question in one concise paragraph.",
},
environment: {
type: "none",
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Explain how an agent connects to an MCP server.",
},
],
},
],
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
client = OpenAI()
agent_id = "agent_123"
session = client.beta.agents.sessions.create(
agent_id=agent_id,
agent={"instructions": "Answer this question in one concise paragraph."},
environment={"type": "none"},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Explain how an agent connects to an MCP server.",
}
],
}
],
)
print(session.to_json())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// Replace the illustrative IDs and URLs below with your own resource values.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
AgentID: openai.String("agent_123"),
Agent: openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
},
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(result)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// 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.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agentId("agent_123")
.agent(
SessionCreateParams.Agent.builder()
.instructions("Answer this question in one concise paragraph.")
.build())
.environmentNone()
.input("Explain how an agent connects to an MCP server.")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"
client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
agent_id: "agent_123",
agent: { instructions: "Answer this question in one concise paragraph." },
environment: { type: "none" },
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Explain how an agent connects to an MCP server."
}
]
}
]
)
puts result
재정의한 설정은 해당 세션에만 적용됩니다. 저장된 에이전트나 다른 세션의 설정은 바뀌지 않습니다. 객체나 배열을 전달하면 저장된 값과 병합하지 않고 해당 필드의 값 전체를 교체합니다. 예를 들어 tools를 전달하면 저장된 도구 목록 전체가 교체됩니다.
요청 필드는 세션 생성 레퍼런스를 참고하세요.
POST /v1/agents/sessions/{session_id} 요청에 agent 객체를 포함하면 해당 세션의 tools, model, reasoning.effort 또는 service_tier를 변경할 수 있습니다. 베타 및 정식 출시(GA) API 사양 모두에서 이 설정을 지원합니다. 같은 요청에서 metadata도 업데이트할 수 있습니다.
모델, 추론 수준, 서비스 등급의 변경 사항은 업데이트가 완료된 뒤 보낸 메시지로 시작하는 새 턴부터 적용됩니다. 이미 처리 중인 메시지에는 이전 설정이 적용될 수 있습니다. 진행 중인 턴에서는 작업 방향을 조정하는 메시지를 보내더라도 이 세 가지 설정이 기존 값으로 유지됩니다. 세션의 대화 기록도 유지됩니다. 선택한 모델이 변경 후의 설정을 지원하지 않으면 업데이트가 실패합니다.
agent와 reasoning 객체에 지정한 필드는 현재 설정에 병합됩니다. 추론 요약을 비롯해 생략한 필드는 그대로 유지됩니다. model만 변경하면 세션의 추론 수준과 서비스 등급은 유지됩니다.tools를 전달하면 도구 목록 전체가 교체됩니다. 함수와 MCP 서버의 변경 사항은 다음 모델 호출부터 적용됩니다. 기본 제공 도구의 변경 사항은 늦어도 다음 턴에 적용됩니다. 현재 도구 목록을 유지하려면 tools를 생략하고, 목록을 비우려면 null이나 []를 전달하세요.reasoning.effort: null을 지정하면 추론 수준이 선택한 모델의 기본값으로 돌아갑니다.service_tier: null을 지정하면 서비스 등급이 다시 자동으로 선택됩니다.- 모델은 항상 지정되어 있어야 하므로
model: null은 사용할 수 없습니다. agent와 reasoning 객체에도 null을 지정할 수 없습니다.
metadata를 전달하면 전체 키-값 맵이 교체됩니다. 메타데이터를 유지하려면 이 필드를 생략하고, 모두 지우려면 null이나 {}를 전달하세요.
다음 요청은 추론 수준을 변경하고 API가 서비스 등급을 자동으로 선택하도록 설정합니다.
123456{
"agent": {
"reasoning": { "effort": "low" },
"service_tier": null
}
}
세션을 업데이트해도 저장된 에이전트나 다른 세션은 바뀌지 않습니다. 이후에 저장된 에이전트를 업데이트해도 해당 세션은 바뀌지 않습니다.
이 엔드포인트로는 reasoning.summary, text, instructions 또는 multi_agent를 업데이트할 수 없습니다. 이 설정을 변경하려면 새 세션을 만드세요. 요청 필드는 세션 업데이트 레퍼런스를 참고하세요.
지원되는 승인 요청을 자동으로 검토하려면 세션 수준의 review 필드를 "auto_review"로 설정하세요. 이 필드는 에이전트 설정 외부에서 agent 또는 agent_id와 같은 수준에 지정하세요. 세션을 만들 때 review를 생략하면 기본값은 "none"입니다.
자동 검토를 활성화하면 실행 권한도 달라집니다. 활성화하기 전에 환경 요구 사항을 확인하세요.
주 작업이 유휴 상태이고 진행 중인 입력 제출이 모두 끝났을 때 review를 업데이트할 수 있습니다. 이후의 실행과 복구에는 새 설정이 적용됩니다. 두 조건이 모두 충족되기 전에 모드 변경을 요청하면 API는 409 Conflict를 반환하고 아무 변경 사항도 적용하지 않습니다. 자동 검토가 활성화된 프로젝트와 자동 검토를 지원하는 세션을 사용하세요. 설정 방법과 승인 요청을 처리하는 방법은 자동 검토를 참고하세요.
세션을 만들 때 environment를 agent와 같은 수준에 지정하세요. 환경 설정에 따라 에이전트가 명령어를 실행하고 파일을 다루는 위치가 결정됩니다.
none, openai_hosted, self_hosted 중 하나를 선택하세요. 각 옵션이 적합한 상황과 환경 관리 주체는 아키텍처에서 확인할 수 있습니다.
OpenAI 호스팅 환경에서는 컨테이너 크기를 선택하고 작업에 필요한 패키지, 초기 파일, 네트워크 액세스를 설정하세요. 환경 템플릿은 여러 세션에서 재사용할 수 있습니다. 자체 호스팅 환경에서는 컴퓨팅 리소스를 준비하고 실행기를 연결하세요.
환경 관련 필드는 세션 생성 레퍼런스를, 스킬, 플러그인, 템플릿에 관한 내용은 플러그인을 참고하세요. 실행 후에도 파일을 보관하려면 세션 아티팩트를 참고하세요.
