Início rápido da API de Agentes

Crie um assistente de programação que escreve tree.py, executa esse arquivo e exibe uma árvore de diretórios. A OpenAI gerencia o agente, sua conversa e o sandbox onde ele trabalha.

Pré-requisitos

Crie uma chave de API de aplicativo no seu projeto na plataforma da OpenAI. Conceda as permissões api.agents.read e api.agents.write para operações de sessão, além de api.responses.write para inferência do modelo, e então 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 mais sobre a configuração e os limites do sandbox.

As requisições exigem o cabeçalho OpenAI-Beta: agents=v1. Os SDKs da OpenAI o adicionam automaticamente; inclua-o explicitamente ao usar cURL.

1. Execute uma tarefa

Escolha uma linguagem, instale o SDK da OpenAI e execute o exemplo. Os exemplos dos SDKs usam o namespace beta.agents. A requisição cria uma sessão, envia uma tarefa e transmite o progresso em tempo real.

Instale ou atualize o SDK para Python:

pip install --upgrade openai

Salve o exemplo como quickstart.py:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14from 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)

Execute no seu terminal:

python quickstart.py

Instale o SDK para JavaScript:

npm install openai

Salve o exemplo como quickstart.mjs:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import 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();
}

Execute no seu terminal:

node quickstart.mjs

Em 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@latest

Salve o exemplo como main.go:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import (
	"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)
}

Execute no seu terminal:

go run .

Adicione o SDK da OpenAI ao pom.xml do seu projeto Maven:

1
2
3
4
5<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.58.0</version>
</dependency>

Salve o exemplo como src/main/java/AgentsApiSessionsStreamConversationExample.java:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33import 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));
  }
}

Execute no seu terminal:

mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExample

Instale o SDK para Ruby:

gem install openai

Salve o exemplo como quickstart.rb:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19require "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
end

Execute no seu terminal:

ruby quickstart.rb

Use cURL no seu terminal; não é necessário instalar um SDK:

Crie e execute tree.py

1
2
3
4
5
6
7
8
9
10
11
12
13curl --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 transmitidos em tempo real. Os exemplos dos SDKs imprimem JSON; o cURL exibe o fluxo bruto de eventos. Em uma execução bem-sucedida, o agente cria tree.py, executa esse arquivo e apresenta uma árvore de diretórios que o contém. Os demais arquivos e a saída dependem do sandbox.

Procure por agent.session.turn.completed e confira o resultado da execução informado pelo agente. Um turno concluído não garante que todas as ferramentas tenham sido executadas com sucesso. Eventos que terminam em turn.failed, turn.cancelled ou session.failed indicam falha ou cancelamento; agent.session.idle, por si só, não significa sucesso. Se o fluxo for desconectado antes do fim, recupere a sessão e seus itens salvos antes de tentar novamente.

3. Continue a sessão

Salve o session_id presente nos eventos. Use-o para enviar uma mensagem de acompanhamento, como “Add a maximum-depth option to tree.py, run it, and show me the output.” Abra o fluxo de eventos antes de enviar a nova mensagem para não perder os eventos iniciais.

4. Faça a limpeza

Mantenha a sessão para outras tarefas ou exclua-a quando terminar. Antes, salve os arquivos de que precisar.

No exemplo, substitua o valor ilustrativo sess_123 pelo ID da sessão que você salvou.

Excluir a sessão

1
2
3
4
5
6
7
8
9
10
11
12# 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())

Excluir a sessão

1
2
3
4
5
6
7
8
9// 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);

Excluir a sessão

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// 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)
}

Excluir a sessão

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20// 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);
  }
}

Excluir a sessão

1
2
3
4
5
6
7
8# 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")

Próximos passos

Explore aplicativos de exemplo.
Configure um sandbox hospedado pela OpenAI: adicione pacotes e arquivos de entrada, controle o acesso à rede e baixe artefatos.
Compare notas de versão com subagentes.
Trabalhe com arquivos e artefatos.
Escolha um ambiente ou conecte seu próprio sandbox.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog