Crie um assistente de programação que escreve o script tree.py, executa esse script e exibe uma árvore de diretórios. A OpenAI gerencia o agente, a conversa e o sandbox em que ele trabalha.
Pré-requisitos
No seu projeto na plataforma da OpenAI, crie uma chave de API para o aplicativo. Conceda à chave as permissões api.agents.read e api.agents.write para operações de sessão e api.responses.write para inferência do modelo. Em seguida, exporte a chave:
export OPENAI_API_KEY="your-api-key"Mantenha essa chave fora do sandbox do agente. Consulte Sandboxes hospedados pela OpenAI para saber como configurar o sandbox e quais limites se aplicam.
As requisições exigem o cabeçalho OpenAI-Beta: agents=v1. Os SDKs da OpenAI incluem esse cabeçalho
automaticamente. Ao usar cURL, inclua o cabeçalho explicitamente.
1. Execute uma tarefa
Escolha uma linguagem, instale o SDK da OpenAI e execute o exemplo. Os exemplos com SDK usam o namespace beta.agents. A requisição cria uma sessão, envia uma tarefa e transmite atualizações de progresso em tempo real.
Instale ou atualize o SDK para Python:
pip install --upgrade openaiSalve o exemplo 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,
).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_idExecute o exemplo no terminal:
python quickstart.pyInstale o SDK para JavaScript:
npm install openaiSalve o exemplo 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,
});
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();
}Execute o exemplo no terminal:
node quickstart.mjsEm um novo diretório, crie um módulo Go e instale o SDK:
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latestSalve o exemplo 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()
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)Execute o exemplo no terminal:
go run .Adicione o SDK da OpenAI ao arquivo pom.xml do seu projeto Maven:
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.103.0</version>
</dependency>Salve o exemplo como 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);
}Execute o exemplo no terminal:
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExampleInstale o SDK para Ruby:
gem install openaiSalve o exemplo 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.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
endExecute o exemplo no terminal:
ruby quickstart.rbUse cURL no terminal, sem precisar instalar um 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
}'Não precisa de um sandbox? Defina environment.type como none para agentes que
respondem a perguntas ou chamam ferramentas externas sem executar comandos nem trabalhar
com arquivos locais. Saiba mais.
2. Acompanhe o progresso
O terminal exibe os eventos à medida que chegam. Os exemplos com SDK exibem os eventos em JSON. O cURL mostra o fluxo de eventos em formato bruto. Quando a execução é bem-sucedida, o agente cria tree.py, executa o script e mostra uma árvore de diretórios que contém esse arquivo. Os demais arquivos e a saída variam conforme o sandbox.
Procure o evento agent.session.turn.completed e confira o resultado da execução informado pelo agente. A conclusão de um turno não garante que todas as chamadas de ferramenta tenham sido bem-sucedidas. Eventos cujos nomes terminam em turn.failed, turn.cancelled ou session.failed indicam falha ou cancelamento. O evento agent.session.idle, por si só, não indica sucesso. Se a conexão cair antes do fim da transmissão, recupere a sessão e os itens salvos nela antes de tentar novamente.
3. Continue a sessão
Salve o session_id que aparece nos eventos. Use esse identificador para enviar outra mensagem, como “Adicione ao script tree.py uma opção para definir a profundidade máxima, execute o script e me mostre a saída.” Abra o fluxo de eventos antes de enviar a próxima mensagem para acompanhar os eventos desde o início.
4. Exclua a sessão quando terminar
Mantenha a sessão para executar outras tarefas ou exclua-a quando terminar. Antes de excluí-la, salve os arquivos de que precisar.
No exemplo, substitua sess_123 pelo ID da sessão que você salvou.
# 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 passos
- Explore os aplicativos de exemplo.
- Configure um sandbox hospedado pela OpenAI para adicionar pacotes e arquivos de entrada, controlar o acesso à rede e baixar artefatos.
- Compare notas de versão com subagentes.
- Trabalhe com arquivos e artefatos.
- Escolha um ambiente ou conecte seu próprio sandbox.