에이전트 설정하기

에이전트 설정하기 (Configuring Agents)

에이전트 설정(configuration)은 에이전트가 어떻게 동작할지 정의해요. 세션을 만들 때 제공하거나 재사용을 위해 저장할 수 있어요. 세션은 대화와 작업을 보유하고, 저장된 에이전트는 재사용 가능한 설정을 보유해요.

출처: 문서

본문

에이전트 설정은 에이전트가 어떻게 동작할지 정의해요. 세션을 만들 때 제공하거나 재사용을 위해 저장할 수 있어요. 세션은 대화와 작업을 보유하고, 저장된 에이전트는 재사용 가능한 설정을 보유해요.

에이전트의 동작 정의하기

모델과 지침으로 시작하고, 작업에 필요한 도구와 컨트롤을 추가하세요:

• Model(모델): 작업을 수행하는 모델.
• Instructions(지침): 에이전트가 무엇을 해야 하고 어떻게 행동해야 하는지.
• Tools(도구): 에이전트가 취할 수 있는 작업(예: 웹 검색, 함수 호출).
• Reasoning and output(추론 및 출력): 모델이 사용하는 추론량과 응답의 형식 및 세부 수준.

이 설정을 세션을 만들 때 agent에 전달하세요. 이 예시는 모델, 지침, 첫 번째 사용자 메시지를 제공해요:

한 세션에 대한 에이전트 설정하기

import 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);

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

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{
		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)

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()
                .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);

require "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 reference를 참고하세요. 도구 설정은 Functions와 MCP connections을, 위임은 Multi-agent를 참고하세요.

세션 간 에이전트 재사용하기

에이전트를 저장해 설정을 여러 세션에서 재사용하세요. 한 번 만들고, 각 세션을 시작할 때 그 ID를 agent_id로 전달하세요:

에이전트 재사용하기

import 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);

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

import (
	"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)

import 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);

require "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 reference를 참고하세요. 자격 증명은 저장된 설정과 분리된 vaults에 남아 있어요.

저장된 에이전트 업데이트하기

저장된 에이전트 업데이트는 새 세션에만 적용돼요. 각 세션은 생성할 때 저장된 설정을 복사하고, 이후 턴 동안 그 설정을 유지해요. 기존 세션을 변경하려면 그 세션의 설정을 업데이트하세요.

저장된 에이전트를 업데이트할 때:

• 생략된 필드는 저장된 값을 유지해요. model만 변경하면 reasoning, service_tier, text가 보존돼요.
• 제공된 객체는 전체 필드를 대체해요. effort만 담은 reasoning을 제공하면 저장된 summary도 지워져요.
• null은 이를 허용하는 필드를 초기화해요. 예를 들어 reasoning: null은 모델의 기본 effort를 복원해요.

새 모델이 지원하지 않는 설정은 같은 요청에서 변경하거나 초기화하세요.

한 세션에 대한 설정 재정의하기

세션을 만들 때 agent_id와 agent를 모두 포함하면 저장된 에이전트의 설정을 커스터마이즈할 수 있어요. 세션은 생성 시점에 모델을 포함한 생략된 설정을 저장된 에이전트에서 복사해요.

이 예시를 실행하기 전에 예시용 agent_123 값을 저장된 에이전트의 ID로 바꾸세요:

한 세션에 대한 에이전트 재정의하기

// 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);

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

// 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)

// 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);

# 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를 제공하면 저장된 도구 목록이 대체돼요.

요청 필드에 대한 자세한 내용은 Create session reference를 참고하세요.

기존 세션의 설정 업데이트하기

한 세션의 model, reasoning.effort, service_tier를 변경하려면 agent 객체와 함께 POST /v1/agents/sessions/{session_id}를 보내세요. 이 설정은 beta 및 GA API 계약에서 사용할 수 있어요. 같은 요청에서 metadata를 업데이트할 수도 있어요.

변경 사항은 업데이트가 완료된 후 전송된 메시지로 시작된 새 턴에 적용돼요. 이미 진행 중인 메시지는 이전 설정을 사용할 수 있어요. 활성 턴은 스티어링 메시지를 보낼 때를 포함해 그 설정을 유지해요. 세션은 대화 히스토리를 유지해요. 선택한 모델이 결과 설정을 지원해야 하며, 그렇지 않으면 업데이트가 실패해요.

• agent와 reasoning 객체는 제공된 필드를 현재 설정에 병합해요. 생략된 필드는 reasoning summary를 포함해 변경되지 않은 채 유지돼요. model만 변경하면 세션의 reasoning effort와 service tier가 보존돼요.
• reasoning.effort: null은 effort를 선택한 모델의 기본값으로 초기화해요.
• service_tier: null은 자동 티어 선택을 복원해요.
• 모델은 항상 설정되어 있어야 하므로 model: null을 제공할 수 없어요. agent와 reasoning 객체도 null을 거부해요.
• metadata는 전체 맵을 대체해요. 보존하려면 생략하고, 지우려면 null 또는 {}를 전달하세요.

예를 들어 이 요청은 reasoning effort를 변경하고 API가 서비스 티어를 자동으로 선택하게 해요:

{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

세션을 업데이트해도 저장된 에이전트나 다른 세션은 변경되지 않아요. 나중에 저장된 에이전트를 업데이트해도 세션은 변경되지 않아요.

이 엔드포인트를 통해 reasoning.summary, text, tools, instructions, multi_agent는 업데이트할 수 없어요. 그 설정을 변경하려면 새 세션을 만들어야 해요.

환경 설정

세션을 만들 때 agent와 함께 environment를 설정하세요. 에이전트가 명령을 실행하고 파일을 다루는 위치를 결정해요.

none, openai_hosted, self_hosted 중에서 선택하세요. Architecture가 각 옵션을 언제 사용해야 하고 누가 환경을 관리하는지 설명해요.

OpenAI 호스팅 환경의 경우 작업에 필요한 패키지, 초기 파일, 네트워크 접근을 설정하세요. 환경 템플릿을 여러 세션에서 재사용할 수 있어요. 자체 호스팅 환경의 경우 컴퓨팅을 준비하고 executor를 연결하세요.

환경 필드는 Create session reference를, 스킬, 플러그인, 템플릿은 Plugins를, 실행 후 보관할 파일은 Session artifacts를 참고하세요.

더 알아보기 (Learn more)

관련 문서: Agents API 아키텍처와 OpenAI 호스팅 환경을 참고하세요.