Agents API
Agents API
Agents API는 OpenAI가 관리하는 API를 통해 여러분의 애플리케이션이 Codex 하네스를 사용할 수 있게 해 줘요. OpenAI가 세션, 오케스트레이션, 컨텍스트 압축, 복구를 관리하고, 애플리케이션은 도구를 제공하고 실행 환경을 선택해요.
출처: 문서
본문
에이전트는 샌드박스에서 동작할 수 있는데, 그곳에서 코드를 실행하고, 파일을 편집하고, MCP 서버에 연결하고, 아티팩트(artifact)를 만들 수 있어요.
가격 (Pricing)
모델 사용량은 선택한 모델의 API 요금으로 청구돼요. OpenAI 도구는 표준 요금을, OpenAI 호스팅 샌드박스는 표준 컨테이너 요금을 사용해요.
예시 사용해 보기 (Try an example)
이 완전한 예시들을 시도해 보세요:
- OpenAI 호스팅 샌드박스에서 디렉터리 트리 스크립트 만들고 실행하기.
- 서브에이전트로 릴리스 노트 비교하기 그리고 여러 서브에이전트의 결과를 하나의 답으로 합치기.
완전한 애플리케이션 둘러보기:
- 인시던트 대응 에이전트: 경보를 조사하고 복구 작업에 대한 승인을 요청해요.
- Slack 봇: 연결된 업무 도구를 사용해 요청을 조사해요.
- 데이터 분석가: 읽기 전용 SQL로 웨어하우스 질문에 답해요.
- GitHub 이슈 조사자를 사용해 보고된 버그를 재현하고 GitHub에서 결과를 공유해요.
- 문서 리뷰어를 사용해 정책 스킬과 전문 에이전트로 문서를 검토해요.
핵심 개념 (Core concepts)
Agents API는 네 가지 주요 개념을 중심으로 만들어졌어요:
- Agent: 에이전트가 사용할 수 있는 모델, 지시사항, 도구, MCP 서버.
- Environment: 에이전트가 파일에 접근하고, 스킬을 불러오고, 명령을 실행하는 선택적 샌드박스 또는 컴퓨터.
- Session: 과제를 수행하고 입력에 응답하는 에이전트의 지속적 인스턴스.
- Events and items: 에이전트에 보내는 입력과 세션 중 생성되는 출력.
처음부터 끝까지의 세션 (A session from start to finish)
퀵스타트에서 OpenAI 호스팅 샌드박스로 시작해 보세요:
- 세션 만들기. 에이전트를 구성하면 OpenAI가 환경을 프로비저닝해요.
- 과제 부여하기. 환경이 준비되면 사용자 입력이 한 턴의 작업을 시작해요.
- 진행 상황 따라가기. 출력 스트리밍을 보거나 웹훅을 사용해 에이전트가 끝났는지, 입력이 필요한지 알 수 있어요.
- 이어가거나 방향 바꾸기. 같은 세션에 다른 과제를 보내거나, 진행 중인 턴 동안 에이전트를 안내해요.
OpenAI 호스팅 세션에서는 애플리케이션이 입력을 보내고 이벤트를 받는 동안, OpenAI가 에이전트를 실행하고 샌드박스를 프로비저닝하고 관리해요. 설정과 제한은 환경 옵션을 참고하세요.
관리형 하네스가 제공하는 것 (What the managed harness provides)
관리형 Codex 하네스가 지원하는 것:
- 샌드박스에서 명령과 코드를 실행하기.
- 관련 스킬과 지시사항 적용하기.
- 도구 또는 MCP를 통해 외부 데이터에 연결하기.
- 작업 중인 동안 에이전트를 안내하기.
- 컨텍스트 창을 관리하기 위해 이전 작업 요약하기.
- 작업을 하위 과제로 나누고 서브에이전트에 위임하기.
- 중단한 지점부터 세션 다시 시작하기.
퀵스타트 전제 조건에서 API 키 권한과 SDK 설정을 확인하세요. 세션을 만들 때 이 기능들을 구성해요:
관리형 하네스 기능 구성하기
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions:
"Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
tools: [
{ type: "programmatic_tool_calling" },
{
type: "mcp",
server_label: "openai_docs",
transport: {
type: "http",
server_url: "https://developers.openai.com/mcp",
},
},
{ type: "web_search" },
],
multi_agent: { enabled: true, max_concurrent_subagents: 4 },
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/capabilities/skills"],
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
},
],
},
],
});
console.log(session.id);
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{"type": "programmatic_tool_calling"},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp",
},
},
{"type": "web_search"},
],
"multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
},
environment={
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"],
},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
}
],
}
],
)
print(session.id)
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",
Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},
MultiAgent: openai.MultiAgentConfigParam{Enabled: true,
MaxConcurrentSubagents: openai.Int(4)}},
Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",
CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{openai.AgentSessionInputMessageParam{Content: []openai.InputContentParamUnion{openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}}}})
if err != nil {
panic(err)
}
fmt.Println(session.ID)
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions(
"Use the OpenAI documentation MCP and web search to answer"
+ " technical questions accurately. Delegate independent"
+ " research tasks to subagents when useful.")
.addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
.addTool(
AgentToolParam.Mcp.builder()
.serverLabel("openai_docs")
.transport(
McpTransportParam.Http.builder()
.serverUrl("https://developers.openai.com/mcp")
.build())
.build())
.addTool(AgentToolParam.WebSearch.builder().build())
.multiAgent(
MultiAgentConfigParam.builder()
.enabled(true)
.maxConcurrentSubagents(4L)
.build())
.build())
.environment(
EnvironmentParam.SelfHosted.builder()
.workspaceDirectory("/workspace")
.capabilityDirectories(List.of("/workspace/capabilities/skills"))
.build())
.input(
"Research how to connect an MCP server to an OpenAI agent, check for recent"
+ " updates, and summarize the recommended setup.")
.build());
System.out.println(session.id());
require "openai"
client = OpenAI::Client.new
session = client.beta.agents.sessions.create(
agent: {
model: "gpt-6-astra",
instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
tools: [
{ type: "programmatic_tool_calling" },
{
type: "mcp",
server_label: "openai_docs",
transport: {
type: "http",
server_url: "https://developers.openai.com/mcp"
}
},
{ type: "web_search" }
],
multi_agent: {
enabled: true,
max_concurrent_subagents: 4
}
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/capabilities/skills"]
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
}
]
}
]
)
puts session.id
curl -sS -X POST "https://api.openai.com/v1/agents/sessions" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{
"type": "programmatic_tool_calling"
},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp"
}
},
{
"type": "web_search"
}
],
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 4
}
},
"environment": {
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"]
},
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
}
]
}
]
}'
런타임 비교는 Agents 개요를 참고하세요.
Agents API는 세션 상태를 유지해서, 대화 컨텍스트를 다시 만들지 않아도 여러 턴에 걸쳐 작업을 이어갈 수 있어요. 더 이상 필요 없는 세션과 게시된 아티팩트는 삭제할 수 있어요. Agents API는 현재 미국에서만 데이터 보존(residency)을 지원하며 Zero Data Retention(ZDR)은 지원하지 않아요. 자체 호스팅 샌드박스를 선택한다고 해서 Agents API가 ZDR 자격을 얻는 건 아니에요. 데이터 보존과 보존에 대한 자세한 내용은 OpenAI 플랫폼의 데이터 통제를 참고하세요.
더 알아보기 (Learn more)
- Agents API 빠른 시작에서 OpenAI 호스팅 샌드박스로 첫 세션을 만들어 보세요.
- 멀티 에이전트 가이드에서 서브에이전트로 작업을 나누는 방법을 확인하세요.