이 예제에서는 tree.py를 작성하고 실행해 디렉터리 트리를 보여 주는 코딩 어시스턴트를 만듭니다. OpenAI가 에이전트와 그 대화, 에이전트가 작업하는 샌드박스를 관리합니다.
사전 준비
OpenAI Platform 프로젝트에서 애플리케이션 API 키를 만드세요. 이 키에 세션 작업에 필요한 api.agents.read 및 api.agents.write 권한과 모델 추론에 필요한 api.responses.write 권한을 부여한 뒤, 다음과 같이 환경 변수로 설정하세요.
export OPENAI_API_KEY="your-api-key"
이 키는 에이전트의 샌드박스 외부에 보관하세요. 샌드박스 설정 방법과 제한 사항은 OpenAI 호스팅 샌드박스를 참고하세요.
요청에는 OpenAI-Beta: agents=v1 헤더가 필요합니다. OpenAI SDK는 이 헤더를 자동으로 추가합니다. cURL을 사용할 때는 헤더를 직접 추가하세요.
1. 작업 실행하기
언어를 선택하고 OpenAI SDK를 설치한 다음 예제를 실행하세요. SDK 예제에서는 beta.agents 네임스페이스를 사용합니다. 요청을 보내면 세션이 생성되고 작업이 제출되며 진행 상황이 스트리밍됩니다.
Python SDK를 설치하거나 업데이트하세요.
pip install --upgrade openai예제 코드를 quickstart.py로 저장하세요.
from openai import OpenAI
with OpenAI() as client:
with client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output.",
},
environment={"type": "openai_hosted"},
input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream=True,
).with_result_collection() as stream:
for event in stream:
print(event.to_json(indent=None), flush=True)
result = stream.get_final_result()
print(result.output_text)
session_id = result.session_id터미널에서 예제를 실행하세요.
python quickstart.pyJavaScript SDK를 설치하세요.
npm install openai예제 코드를 quickstart.mjs로 저장하세요.
import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output.",
},
environment: { type: "openai_hosted" },
input:
"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream: true,
});
events.withResultCollection();
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
const result = await events.finalResult();
console.log(result.output_text);
console.log("Session:", result.session_id);
} finally {
events.controller.abort();
}터미널에서 예제를 실행하세요.
node quickstart.mjs새 디렉터리에서 Go 모듈을 만들고 SDK를 설치하세요.
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latest예제 코드를 main.go로 저장하세요.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
events := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Write clean code, run it, and report the actual output."),
},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfString: openai.String("Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."),
},
})
defer events.Close()
openai.BetaAgentSessionWithResultCollection(events)
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
fmt.Println(event.RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(events)
if err != nil {
panic(err)
}
fmt.Println(result.OutputText())
sessionID := result.SessionID()
fmt.Println("Session:", sessionID)터미널에서 예제를 실행하세요.
go run .Maven 프로젝트의 pom.xml에 OpenAI SDK를 추가하세요.
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.103.0</version>
</dependency>예제 코드를 src/main/java/AgentsApiSessionsStreamConversationExample.java로 저장하세요.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.ObjectMappers;
import com.openai.core.http.StreamResponse;
import com.openai.models.beta.agents.AgentSessionEvent;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.jsonMapper();
try (StreamResponse<AgentSessionEvent> events =
client
.beta()
.agents()
.sessions()
.createStreaming(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Write clean code, run it, and report the actual output.")
.build())
.environment(EnvironmentParam.OpenAIHosted.builder().build())
.input(
"Create tree.py, a Python script that prints a readable tree of the files"
+ " in the current directory. Run it and show me the output.")
.build())) {
AgentTurnResults.withResultCollection(events);
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
System.out.println(json.writeValueAsString(event));
}
var result = AgentTurnResults.getFinalResult(events);
System.out.println(result.outputText());
String sessionId = result.sessionId();
System.out.println(sessionId);
}터미널에서 예제를 실행하세요.
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExampleRuby SDK를 설치하세요.
gem install openai예제 코드를 quickstart.rb로 저장하세요.
require "openai"
require "json"
client = OpenAI::Client.new
events = client.beta.agents.sessions.create_streaming(
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output."
},
environment: { type: "openai_hosted" },
input: "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."
)
begin
events.with_result_collection
events.each do |event|
puts JSON.generate(event.to_h)
end
result = events.get_final_result
puts result.output_text
session_id = result.session_id
puts "Session: #{session_id}"
ensure
events.close
end터미널에서 예제를 실행하세요.
ruby quickstart.rb터미널에서 cURL로 요청을 보내세요. SDK를 설치할 필요는 없습니다.
curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output."
},
"environment": { "type": "openai_hosted" },
"input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
"stream": true
}'샌드박스가 필요 없나요? 에이전트가 명령어를 실행하거나 로컬 파일을 다루지 않고 질문에 답하거나 외부 도구를 호출한다면 environment.type을 none으로 설정하세요. 자세히 알아보기.
2. 진행 상황 확인하기
터미널에는 이벤트가 수신되는 대로 표시됩니다. SDK 예제는 이벤트를 JSON으로 출력하고, cURL은 원본 이벤트 스트림을 표시합니다. 실행에 성공하면 에이전트가 tree.py를 작성하고 실행한 뒤 해당 파일이 포함된 디렉터리 트리를 보여 줍니다. 그 밖의 파일과 출력 내용은 샌드박스에 따라 달라집니다.
이벤트 스트림에서 agent.session.turn.completed를 찾은 다음 에이전트가 보고한 실행 결과를 확인하세요. 턴이 완료되었더라도 일부 도구 호출은 실패했을 수 있습니다. 이름이 turn.failed, turn.cancelled 또는 session.failed로 끝나는 이벤트는 실패 또는 취소를 나타냅니다. agent.session.idle 이벤트만으로는 성공 여부를 판단할 수 없습니다. 스트림이 중간에 끊기면 세션과 세션에 저장된 항목을 조회한 뒤 다시 시도하세요.
3. 세션 이어가기
이벤트에 포함된 session_id를 저장하세요. 이 ID로 후속 요청을 보내세요. 예를 들어 “tree.py에 최대 깊이 옵션을 추가하고 실행해서 출력 결과를 보여 줘.”라고 요청할 수 있습니다. 초기 이벤트를 놓치지 않도록 후속 요청을 보내기 전에 이벤트 스트림을 여세요.
4. 세션 정리하기
추가 작업에 사용할 세션은 유지하고, 작업을 모두 마쳤다면 삭제하세요. 삭제하기 전에 필요한 파일을 저장하세요.
예제의 sess_123을 앞에서 저장한 세션 ID로 바꾸세요.
# 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.
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.
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/sess_123" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"다음 단계
- 예제 애플리케이션 살펴보기.
- OpenAI 호스팅 샌드박스 구성하기. 패키지와 입력 파일을 추가하고, 네트워크 액세스를 제어하고, 아티팩트를 다운로드하세요.
- 하위 에이전트로 릴리스 노트 비교하기.
- 파일과 아티팩트 다루기.
- 환경 선택하기 또는 자체 샌드박스 연결하기.