OpenAI Agents API 快速开始

本例构建编码助手：编写 tree.py、运行脚本并显示目录树。OpenAI管理智能体、对话及执行沙箱。

前置条件

在OpenAI项目创建应用API密钥，授予会话操作 api.agents.read、api.agents.write，以及推理 api.responses.write，再导出环境变量：

来源示例 1（bash）：

## [中文] 示例 1：前置条件。
## [中文] 在应用终端导出实际 API 密钥，替换占位值；此密钥不传入智能体执行环境。
export OPENAI_API_KEY="your-api-key"

密钥保留在智能体沙箱外。配置与限制见 OpenAI托管沙箱。

请求要求 OpenAI-Beta: agents=v1。官方SDK自动添加，cURL需显式提供。

1. 运行任务

选择一种语言，安装SDK后运行。SDK示例采用 beta.agents 命名空间；一个请求完成创建会话、提交任务、流式返回进度。

Python：安装或更新SDK，保存为 quickstart.py，再在终端运行：

来源示例 2（bash）：

## [中文] 示例 2：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
pip install --upgrade openai

来源示例 3（python）：

程序文字说明15：编写清晰代码，运行并报告实际输出。

程序文字说明34：创建tree.py，使其打印当前目录文件的易读树状结构，运行并展示输出。

程序文字说明35：此拼接输入要求创建、运行tree.py目录树脚本并展示实际输出。

## [中文] 示例 3：1. 运行任务。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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

来源示例 4（bash）：

## [中文] 示例 4：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
python quickstart.py

JavaScript：安装SDK，保存为 quickstart.mjs，再运行：

来源示例 5（bash）：

## [中文] 示例 5：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
npm install openai

来源示例 6（javascript）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

// [中文] 示例 6：1. 运行任务。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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();
}

来源示例 7（bash）：

## [中文] 示例 7：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
node quickstart.mjs

Go：在新目录初始化模块并安装SDK，保存为 main.go，再运行：

来源示例 8（bash）：

## [中文] 示例 8：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latest

来源示例 9（go）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

// [中文] 示例 9：1. 运行任务。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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)

来源示例 10（bash）：

## [中文] 示例 10：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
go run .

Java：在Maven项目 pom.xml 添加SDK依赖，保存为 src/main/java/AgentsApiSessionsStreamConversationExample.java，再运行：

来源示例 11（xml）：

<!-- [中文] 示例 11：1. 运行任务。 -->
<!-- [中文] 这是 Maven 依赖声明，放入 pom.xml 的 dependencies 中；不是可直接运行的 Java 程序。 -->
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.91.0</version>
</dependency>

来源示例 12（java）：

沿用程序文字说明15。

沿用程序文字说明35。

// [中文] 示例 12：1. 运行任务。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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);
}

来源示例 13（bash）：

## [中文] 示例 13：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExample

Ruby：安装SDK，保存为 quickstart.rb，再运行：

来源示例 14（bash）：

## [中文] 示例 14：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
gem install openai

来源示例 15（ruby）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

## [中文] 示例 15：1. 运行任务。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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

来源示例 16（bash）：

## [中文] 示例 16：1. 运行任务。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
ruby quickstart.rb

cURL：直接从终端调用，无需安装SDK：

来源示例 17（bash）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

## [中文] 示例 17：1. 运行任务。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions；示例占位地址需替换为实际资源。
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，用它发送后续请求，例如“给tree.py加最大深度选项，运行后显示输出”。先打开事件流，再发送输入，以免遗漏早期事件。

4. 清理

需要后续任务可保留会话；不再需要时删除。先保存文件，将示意 sess_123 替换为实际会话ID：

来源示例 18（python）：

## [中文] 示例 18：4. 清理。
## [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
## 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())

来源示例 19（javascript）：

// [中文] 示例 19：4. 清理。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// 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);

来源示例 20（go）：

// [中文] 示例 20：4. 清理。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// 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)
}

来源示例 21（java）：

// [中文] 示例 21：4. 清理。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// 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);
  }
}

来源示例 22（ruby）：

## [中文] 示例 22：4. 清理。
## [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
## 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")

来源示例 23（bash）：

## [中文] 示例 23：4. 清理。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/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"

后续步骤

• 应用示例。
• 配置托管沙箱：软件包、输入文件、网络和产物下载。
• 子智能体比较发行说明。
• 文件与产物。
• 选择环境或连接自己的沙箱。