Crea un asistente de programación que escriba tree.py, lo ejecute y muestre un árbol de directorios. OpenAI administra el agente, su conversación y el sandbox donde trabaja.
Requisitos previos
Crea una clave de API de aplicación en tu proyecto de OpenAI Platform. Otorga los permisos api.agents.read y api.agents.write para las operaciones de sesión, además de api.responses.write para la inferencia del modelo, y luego exporta la clave:
export OPENAI_API_KEY="your-api-key"
Mantén esta clave fuera del sandbox del agente. Consulta Sandboxes alojados por OpenAI para conocer la configuración y los límites del sandbox.
Las solicitudes requieren el encabezado OpenAI-Beta: agents=v1. Los SDK de OpenAI lo agregan
automáticamente; inclúyelo explícitamente cuando uses cURL.
1. Ejecuta una tarea
Elige un lenguaje, instala el SDK de OpenAI y ejecuta el ejemplo. Los ejemplos del SDK usan el espacio de nombres beta.agents. La solicitud crea una sesión, envía una tarea y transmite el progreso.
Instala o actualiza el SDK de Python:
pip install --upgrade openaiGuarda el ejemplo como 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,
) as events:
for event in events:
print(event.to_json(indent=None), flush=True)Ejecútalo desde tu terminal:
python quickstart.pyInstala el SDK de JavaScript:
npm install openaiGuarda el ejemplo como 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,
});
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
} finally {
events.controller.abort();
}Ejecútalo desde tu terminal:
node quickstart.mjsEn un directorio nuevo, crea un módulo de Go e instala el SDK:
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latestGuarda el ejemplo como 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()
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
fmt.Println(event.RawJSON())
}
if err := events.Err(); err != nil {
panic(err)
}Ejecútalo desde tu terminal:
go run .Agrega el SDK de OpenAI al archivo pom.xml de tu proyecto de Maven:
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.58.0</version>
</dependency>Guarda el ejemplo como src/main/java/AgentsApiSessionsStreamConversationExample.java:
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
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;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = new 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())) {
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
System.out.println(json.writeValueAsString(event));
}
}Ejecútalo desde tu terminal:
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExampleInstala el SDK de Ruby:
gem install openaiGuarda el ejemplo como 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.each do |event|
puts JSON.generate(event.to_h)
end
ensure
events.close
endEjecútalo desde tu terminal:
ruby quickstart.rbUsa cURL desde tu terminal; no necesitas instalar ningún 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
}'¿No necesitas un sandbox? Establece environment.type en none para agentes que
respondan preguntas o llamen a herramientas externas sin ejecutar comandos ni trabajar
con archivos locales. Más
información.
2. Sigue el progreso
La terminal muestra los eventos a medida que se transmiten. Los ejemplos del SDK imprimen JSON; cURL muestra el flujo de eventos sin procesar. Si la ejecución se completa correctamente, el agente crea tree.py, lo ejecuta y muestra un árbol de directorios que contiene ese archivo. Los demás archivos y la salida dependen del sandbox.
Busca agent.session.turn.completed y luego revisa el resultado de ejecución que informa el agente. Que un turno se complete no garantiza que todas las herramientas hayan funcionado correctamente. Los eventos que terminan en turn.failed, turn.cancelled o session.failed indican un error o una cancelación; agent.session.idle por sí solo no indica que la ejecución haya sido exitosa. Si la transmisión se desconecta antes de tiempo, recupera la sesión y sus elementos guardados antes de volver a intentarlo.
3. Continúa la sesión
Guarda el session_id de los eventos. Úsalo para enviar un mensaje de seguimiento como “Add a maximum-depth option to tree.py, run it, and show me the output.” Abre el flujo de eventos antes de enviar la entrada de seguimiento para no perderte los primeros eventos.
4. Limpieza
Conserva la sesión para más tareas o elimínala cuando termines. Primero, guarda los archivos que necesites.
En el ejemplo, reemplaza el valor de muestra sess_123 por el ID de sesión que guardaste.
# 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"Próximos pasos
- Explora aplicaciones de ejemplo.
- Configura un sandbox alojado en OpenAI: agrega paquetes y archivos de entrada, controla el acceso a la red y descarga artefactos.
- Compara notas de la versión con subagentes.
- Trabaja con archivos y artefactos.
- Elige un entorno o conecta tu propio sandbox.