Engenharia de prompt

Com a API da OpenAI, você pode usar um grande modelo de linguagem para gerar texto a partir de um prompt, como faria no ChatGPT. Os modelos podem gerar praticamente qualquer tipo de resposta em texto, como código, equações matemáticas, dados estruturados em JSON ou textos que soam como se tivessem sido escritos por uma pessoa.

Veja um exemplo simples com a API Responses.

Gere texto a partir de um prompt simples

JavaScript

1
2
3
4
5
6
7
8
9import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	resp, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Say this is a test")},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(resp.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class Main {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    ResponseCreateParams params =
        ResponseCreateParams.builder().input("Say this is a test").model("gpt-6-astra").build();

    Response response = client.responses().create(params);
    response.output().stream()
        .flatMap(item -> item.message().stream())
        .flatMap(message -> message.content().stream())
        .flatMap(content -> content.outputText().stream())
        .forEach(outputText -> System.out.println(outputText.text()));
  }
}

1
2
3
4
5
6
7
8
9
10
11
12using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

ResponseResult response = await client.CreateResponseAsync(
    "gpt-6-astra",
    "Say 'this is a test.'"
);

Console.WriteLine($"[ASSISTANT]: {response.GetOutputText()}");

1
2
3
4
5
6
7
8
9
10require "openai"

openai = OpenAI::Client.new

response = openai.responses.create(
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn."
)

puts(response.output_text)

1
2
3
4
5openai responses create \
  --model "gpt-6-astra" \
  --input "Write a one-sentence bedtime story about a unicorn." \
  --raw-output \
  --transform 'output.#(type=="message").content.0.text'

1
2
3
4
5
6
7curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "input": "Write a one-sentence bedtime story about a unicorn."
    }'

A propriedade output da resposta contém um array com o conteúdo gerado pelo modelo. Neste exemplo simples, o array tem apenas um item:

1234567891011121314[
  {
    "id": "msg_67b73f697ba4819183a15cc17d011509",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
        "annotations": []
      }
    ]
  }
]

O array output costuma ter mais de um item! Ele pode conter chamadas de ferramentas, dados sobre os tokens de raciocínio gerados por modelos de raciocínio e outros itens. Não é seguro presumir que o texto gerado pelo modelo esteja em output[0].content[0].text.

Para facilitar o acesso ao texto, alguns dos nossos SDKs oficiais incluem nas respostas do modelo a propriedade output_text, que reúne todas as saídas de texto em uma única string. Você pode usar essa propriedade como atalho para acessar o texto gerado pelo modelo.

Além de texto simples, o modelo também pode retornar dados estruturados no formato JSON. Esse recurso se chama saídas estruturadas.

Veja um exemplo simples com a API chat completions.

Gere texto a partir de um prompt simples

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    {
      role: "user",
      content: "Write a one-sentence bedtime story about a unicorn.",
    },
  ],
});

console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)

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
27package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()

	completion, err := client.Chat.Completions.New(
		context.Background(),
		openai.ChatCompletionNewParams{
			Model: "gpt-6-astra",
			Messages: []openai.ChatCompletionMessageParamUnion{
				openai.UserMessage("Write a one-sentence bedtime story about a unicorn."),
			},
		},
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-6-astra")
        .addUserMessage("Write a one-sentence bedtime story about a unicorn.")
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11using OpenAI.Chat;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-6-astra";
ChatClient client = new(model, key);

ChatCompletion completion = await client.CompleteChatAsync(
    new UserChatMessage("Write a one-sentence bedtime story about a unicorn.")
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-6-astra",
  messages: [
    {
      role: :user,
      content: "Write a one-sentence bedtime story about a unicorn."
    }
  ]
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12curl "https://api.openai.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.5",
        "messages": [
            {
                "role": "user",
                "content": "Write a one-sentence bedtime story about a unicorn."
            }
        ]
    }'

A propriedade choices da resposta contém um array com o conteúdo gerado pelo modelo. Neste exemplo simples, o array tem apenas um item:

123456789101112[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
      "refusal": null
    },
    "logprobs": null,
    "finish_reason": "stop"
  }
]

Além de texto simples, o modelo também pode retornar dados estruturados no formato JSON. Esse recurso se chama saídas estruturadas.

Como escolher um modelo

Ao gerar conteúdo pela API, uma das principais decisões é qual modelo usar. Nos exemplos de código acima, você faz essa escolha com o parâmetro model. Consulte a lista completa de modelos disponíveis. Considere os seguintes fatores ao escolher um modelo para geração de texto.

Modelos de raciocínio geram uma cadeia de pensamento interna para analisar o prompt de entrada. Eles se destacam na compreensão de tarefas complexas e no planejamento em várias etapas. Em geral, também são mais lentos e custam mais que os modelos GPT.
Modelos GPT são rápidos, têm boa relação custo-benefício e são altamente inteligentes, mas produzem resultados melhores quando recebem instruções mais explícitas sobre como realizar as tarefas.
Modelos grandes e pequenos (mini ou nano) oferecem diferentes combinações de velocidade, custo e inteligência. Os modelos grandes são mais eficazes na interpretação de prompts e na resolução de problemas em diversas áreas. Os pequenos geralmente são mais rápidos e baratos.

Na dúvida, gpt-6-astra é uma boa escolha para gerar textos de uso geral e refinar prompts.

Engenharia de prompt

Engenharia de prompt é a prática de escrever instruções eficazes para que um modelo gere, de forma consistente, conteúdo que atenda aos seus requisitos.

Como a geração de conteúdo pelo modelo não é determinística, formular um prompt para obter o resultado desejado envolve tanto técnica quanto criatividade. Ainda assim, há técnicas e boas práticas que ajudam a obter bons resultados de forma consistente.

Algumas técnicas de engenharia de prompt funcionam com qualquer modelo, como o uso de papéis nas mensagens. Mas modelos de tipos diferentes, como os de raciocínio e os GPT, podem exigir prompts diferentes para produzir os melhores resultados. Até versões específicas de modelos da mesma família podem produzir resultados distintos. Por isso, ao desenvolver aplicativos mais complexos, recomendamos enfaticamente que você:

Configure seus aplicativos em produção para usar versões específicas dos modelos (como gpt-4.1-2025-04-14) para garantir um comportamento consistente.
Crie testes e conjuntos de avaliações que meçam o comportamento dos prompts. Assim, você pode acompanhar o desempenho ao refiná-los ou ao trocar ou atualizar a versão do modelo.

Veja a seguir algumas ferramentas e técnicas para criar prompts.

Papéis das mensagens e prioridade das instruções

Você pode dar ao modelo instruções com diferentes níveis de autoridade usando o parâmetro instructions da API ou os papéis das mensagens.

O parâmetro instructions define orientações gerais sobre como o modelo deve se comportar ao gerar uma resposta, incluindo o tom, os objetivos e exemplos de respostas corretas. As instruções fornecidas dessa forma têm prioridade sobre o prompt do parâmetro input.

Gere texto com instruções

JavaScript

1
2
3
4
5
6
7
8
9
10
11import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  instructions: "Talk like a pirate.",
  input: "Are semicolons optional in JavaScript?",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    instructions="Talk like a pirate.",
    input="Are semicolons optional in JavaScript?",
)

print(response.output_text)

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
29package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String("Talk like a pirate."),
		Reasoning: responses.ReasoningParam{
			Effort: responses.ReasoningEffortLow,
		},
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Are semicolons optional in JavaScript?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(semicolonsPrompt)
        .instructions(semicolonsDevMsg)
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    Instructions = "Talk like a pirate.",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.Low,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Are semicolons optional in JavaScript?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  instructions: "Talk like a pirate.",
  reasoning: { effort: :low },
  input: "Are semicolons optional in JavaScript?"
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "reasoning": {"effort": "low"},
        "instructions": "Talk like a pirate.",
        "input": "Are semicolons optional in JavaScript?"
    }'

O exemplo acima equivale, em linhas gerais, a usar as seguintes mensagens de entrada no array input:

Gere texto com mensagens de diferentes papéis

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  input: [
    {
      role: "developer",
      content: "Talk like a pirate.",
    },
    {
      role: "user",
      content: "Are semicolons optional in JavaScript?",
    },
  ],
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    input=[
        {"role": "developer", "content": "Talk like a pirate."},
        {"role": "user", "content": "Are semicolons optional in JavaScript?"},
    ],
)

print(response.output_text)

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
33
34
35
36
37package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Reasoning: responses.ReasoningParam{
			Effort: responses.ReasoningEffortLow,
		},
		Input: responses.ResponseNewParamsInputUnion{
			OfInputItemList: responses.ResponseInputParam{
				responses.ResponseInputItemParamOfMessage(
					"Talk like a pirate.",
					responses.EasyInputMessageRoleDeveloper,
				),
				responses.ResponseInputItemParamOfMessage(
					"Are semicolons optional in JavaScript?",
					responses.EasyInputMessageRoleUser,
				),
			},
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

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
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            ResponseCreateParams.Input.ofResponse(
                List.of(
                    ResponseInputItem.ofEasyInputMessage(
                        EasyInputMessage.builder()
                            .role(EasyInputMessage.Role.DEVELOPER)
                            .content(semicolonsDevMsg)
                            .build()),
                    ResponseInputItem.ofEasyInputMessage(
                        EasyInputMessage.builder()
                            .role(EasyInputMessage.Role.USER)
                            .content(semicolonsPrompt)
                            .build()))))
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.Low,
    },
};
options.InputItems.Add(
    ResponseItem.CreateDeveloperMessageItem("Talk like a pirate.")
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Are semicolons optional in JavaScript?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  reasoning: { effort: :low },
  input: [
    {
      role: :developer,
      content: "Talk like a pirate."
    },
    {
      role: :user,
      content: "Are semicolons optional in JavaScript?"
    }
  ]
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "reasoning": {"effort": "low"},
        "input": [
            {
                "role": "developer",
                "content": "Talk like a pirate."
            },
            {
                "role": "user",
                "content": "Are semicolons optional in JavaScript?"
            }
        ]
    }'

O parâmetro instructions se aplica apenas à solicitação atual de geração de resposta. Se você estiver gerenciando o estado da conversa com o parâmetro previous_response_id, o contexto não incluirá o conteúdo de instructions usado nos turnos anteriores.

Você pode dar ao modelo instruções (prompts) com diferentes níveis de autoridade usando os papéis das mensagens.

Gere texto com mensagens de diferentes papéis

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "developer",
      content: "Talk like a pirate.",
    },
    {
      role: "user",
      content: "Are semicolons optional in JavaScript?",
    },
  ],
});

console.log(completion.choices[0].message);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    reasoning_effort="low",
    messages=[
        {"role": "developer", "content": "Talk like a pirate."},
        {"role": "user", "content": "Are semicolons optional in JavaScript?"},
    ],
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()

	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-6-astra",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.DeveloperMessage("Talk like a pirate."),
			openai.UserMessage("Are semicolons optional in JavaScript?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-6-astra")
        .addDeveloperMessage(semicolonsDevMsg)
        .addUserMessage(semicolonsPrompt)
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15using OpenAI.Chat;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-6-astra";
ChatClient client = new(model, key);

ChatCompletion completion = await client.CompleteChatAsync(
    [
        new DeveloperChatMessage("Talk like a pirate."),
        new UserChatMessage("Are semicolons optional in JavaScript?"),
    ]
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-6-astra",
  messages: [
    {
      role: :developer,
      content: "Talk like a pirate."
    },
    {
      role: :user,
      content: "Are semicolons optional in JavaScript?"
    }
  ]
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl "https://api.openai.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "messages": [
            {
                "role": "developer",
                "content": "Talk like a pirate."
            },
            {
                "role": "user",
                "content": "Are semicolons optional in JavaScript?"
            }
        ]
    }'

A especificação do modelo da OpenAI descreve como nossos modelos atribuem prioridade às mensagens de acordo com o papel de cada uma.

`developer`	`user`	`assistant`
As mensagens `developer` contêm instruções de quem desenvolve o aplicativo e têm prioridade sobre as mensagens `user`.	As mensagens `user` contêm instruções do usuário final e têm prioridade menor que as mensagens `developer`.	As mensagens geradas pelo modelo têm o papel `assistant`.

Uma conversa com vários turnos pode incluir diversas mensagens desses tipos, além de outros tipos de conteúdo fornecidos por você e pelo modelo. Saiba mais sobre como gerenciar o estado da conversa.

Pense nas mensagens developer e user como uma função e seus argumentos em uma linguagem de programação.

As mensagens developer estabelecem as regras do sistema e a lógica de negócio, como a definição de uma função.
As mensagens user fornecem os dados de entrada e as configurações aos quais se aplicam as instruções da mensagem developer, como os argumentos de uma função.

Versione os prompts no código

Armazene os prompts de produção no código do aplicativo em vez de criar objetos de prompt reutilizáveis. Ao gerenciar os prompts no código, você pode usar entradas tipadas, revisão de código, testes e seu processo habitual de implantação para alterar o comportamento do modelo.

A OpenAI está descontinuando os objetos de prompt reutilizáveis na API. A criação de prompts perderá destaque a partir de 3 de junho de 2026, e a desativação de v1/prompts está prevista para 30 de novembro de 2026. Consulte a página de descontinuações para conferir o cronograma atualizado.

Ao iniciar um novo trabalho de engenharia de prompt:

Mantenha as funções que montam os prompts em um módulo pequeno, próximo ao código do recurso que elas atendem.
Use argumentos de função tipados ou schemas para valores dinâmicos, como dados de clientes, arquivos ou opções da tarefa.
Passe os valores gerados de instructions e input diretamente para a API Responses.
Adicione dados de teste representativos, testes e verificações de avaliação antes de alterar os prompts de produção.
Publique as alterações nos prompts pelo seu sistema de implantação. Use sinalizadores de recursos ou opções de configuração quando precisar fazer a liberação em etapas.

Se a sua integração já chama um prompt salvo pelo ID ou pela versão, siga o guia de migração de objetos de prompt para mover esse prompt para o código.

Formatação de mensagens com Markdown e XML

Ao escrever mensagens developer e user, você pode combinar a formatação em Markdown com tags XML para ajudar o modelo a distinguir as partes do prompt e os dados de contexto.

Títulos e listas em Markdown ajudam a delimitar as seções do prompt e a indicar sua hierarquia ao modelo. Também podem facilitar a leitura dos prompts durante o desenvolvimento. As tags XML ajudam a indicar onde começa e termina cada trecho de conteúdo, como um documento de apoio usado como referência. Com os atributos XML, você também pode definir metadados sobre o conteúdo do prompt e fazer referência a eles nas instruções.

Em geral, uma mensagem de desenvolvedor contém as seções abaixo, normalmente nesta ordem. O conteúdo e a ordem ideais podem variar conforme o modelo:

Identidade: Descreva a finalidade, o estilo de comunicação e os objetivos gerais do assistente.
Instruções: Oriente o modelo sobre como gerar a resposta desejada. Quais regras ele deve seguir? O que deve fazer e o que nunca deve fazer? Inclua as subseções relevantes para o seu caso de uso, como orientações para o modelo chamar funções personalizadas.
Exemplos: Forneça exemplos de entradas possíveis e, para cada uma, a saída que você espera do modelo.
Contexto: Forneça as informações adicionais de que o modelo possa precisar para gerar uma resposta, como dados privados ou proprietários que não façam parte do conjunto de treinamento, ou outros dados que você saiba serem especialmente relevantes. Em geral, é melhor colocar esse conteúdo perto do fim do prompt, já que o contexto pode variar de uma solicitação de geração para outra.

Veja como usar Markdown e tags XML para criar uma mensagem developer com seções distintas e exemplos de apoio.

Mensagem de desenvolvedor para geração de código

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24# Identity

You are coding assistant that helps enforce the use of snake case
variables in JavaScript code, and writing code that will run in
Internet Explorer version 6.

# Instructions

* When defining variables, use snake case names (e.g. my_variable)
  instead of camel case names (e.g. myVariable).
* To support old browsers, declare variables using the older
  "var" keyword.
* Do not give responses with Markdown formatting, just return
  the code as requested.

# Examples

<user_query>
How do I declare a string variable for a first name?
</user_query>

<assistant_response>
var first_name = "Anna";
</assistant_response>

Envie um prompt para gerar código pela API

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13import fs from "fs/promises";
import OpenAI from "openai";
const client = new OpenAI();

const instructions = await fs.readFile("fixtures/prompt.txt", "utf-8");

const response = await client.responses.create({
  model: "gpt-6-astra",
  instructions,
  input: "How would I declare a variable for a last name?",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

with open("prompt.txt", "r", encoding="utf-8") as f:
    instructions = f.read()

response = client.responses.create(
    model="gpt-6-astra",
    instructions=instructions,
    input="How would I declare a variable for a last name?",
)

print(response.output_text)

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
32package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	instructions, err := os.ReadFile("prompt.txt")
	if err != nil {
		panic(err)
	}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String(string(instructions)),
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("How would I declare a variable for a last name?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .instructions(
            "You are a coding assistant. Answer with concise JavaScript examples and use semicolons.")
        .input("How would I declare a variable for a last name?")
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

string instructions = await File.ReadAllTextAsync("prompt.txt");
CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    Instructions = instructions,
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("How would I declare a variable for a last name?")
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11require "openai"

client = OpenAI::Client.new
instructions = File.read(File.join(__dir__, "prompt.txt"))
response = client.responses.create(
  model: "gpt-6-astra",
  instructions: instructions,
  input: "How would I declare a variable for a last name?"
)

puts(response.output_text)

1
2
3
4
5
6
7
8curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "instructions": "'"$(< prompt.txt)"'",
    "input": "How would I declare a variable for a last name?"
  }'

Reduza custos e latência com o cache de prompts

Ao montar uma mensagem, procure colocar o conteúdo que pretende reutilizar nas solicitações à API no início do prompt e entre os primeiros parâmetros enviados no corpo JSON da solicitação a Chat Completions ou Responses. Assim, você aproveita ao máximo a redução de custos e latência proporcionada pelo cache de prompts.

Aprendizado few-shot

O aprendizado few-shot permite orientar um grande modelo de linguagem a realizar uma nova tarefa incluindo no prompt alguns exemplos de entrada e saída, sem precisar fazer o ajuste fino do modelo. O modelo identifica implicitamente o padrão nos exemplos e o aplica ao prompt. Procure apresentar entradas variadas e indicar a saída desejada para cada uma.

Em geral, os exemplos fazem parte de uma mensagem developer na solicitação à API. A mensagem developer abaixo contém exemplos que mostram ao modelo como classificar avaliações positivas ou negativas sobre o atendimento ao cliente.

# Identity

You are a helpful assistant that labels short product reviews as
Positive, Negative, or Neutral.

# Instructions

* Only output a single word in your response with no additional formatting
  or commentary.
* Your response should only be one of the words "Positive", "Negative", or
  "Neutral" depending on the sentiment of the product review you are given.

# Examples

<product_review id="example-1">
I absolutely love this headphones — sound quality is amazing!
</product_review>

<assistant_response id="example-1">
Positive
</assistant_response>

<product_review id="example-2">
Battery life is okay, but the ear pads feel cheap.
</product_review>

<assistant_response id="example-2">
Neutral
</assistant_response>

<product_review id="example-3">
Terrible customer service, I'll never buy from them again.
</product_review>

<assistant_response id="example-3">
Negative
</assistant_response>

Inclua informações de contexto relevantes

Muitas vezes, vale a pena incluir no prompt informações adicionais que o modelo possa usar para gerar a resposta. Há alguns motivos comuns para fazer isso:

Dar ao modelo acesso a dados proprietários ou a outros dados que não façam parte do conjunto usado no treinamento.
Restringir a resposta do modelo a um conjunto específico de fontes que você identificou como as mais úteis para a tarefa.

A técnica de acrescentar contexto relevante à solicitação de geração do modelo é às vezes chamada de geração aumentada por recuperação (RAG). Há várias formas de acrescentar contexto ao prompt. Você pode, por exemplo, consultar um banco de dados vetorial e incluir no prompt o texto retornado ou usar a ferramenta integrada de pesquisa de arquivos da OpenAI para gerar conteúdo com base nos documentos enviados.

Planeje o uso da janela de contexto

Em cada solicitação de geração, há um limite para a quantidade de dados que o modelo consegue considerar como contexto. Esse limite de memória é chamado de janela de contexto e é medido em tokens, que representam partes dos dados enviados, de textos a imagens.

O tamanho da janela de contexto varia conforme o modelo, de pouco mais de 100 mil tokens a um milhão nos modelos GPT-4.1 mais recentes. Consulte a documentação dos modelos para conferir o tamanho da janela de contexto de cada um.

Como criar prompts para os modelos atuais

Modelos GPT como gpt-6-astra se beneficiam de instruções precisas que explicitem no prompt a lógica e os dados necessários para realizar a tarefa. Para aproveitar ao máximo o modelo mais recente, comece pelo guia atualizado de prompts.

GPT-6 Astra prompting guide

Aproveite melhor os prompts para o modelo mais recente com orientações atualizadas, exemplos práticos e notas sobre migração.

Boas práticas de criação de prompts para o modelo mais recente

Para orientações completas e atualizadas, consulte as boas práticas de criação de prompts para o modelo mais recente. As recomendações práticas abaixo continuam válidas.

GPT-6 Astra

tem bom desempenho tanto na criação de interfaces do zero quanto em contribuições para grandes bases de código já consolidadas. Para obter os melhores resultados, recomendamos as seguintes bibliotecas:

Estilização e interface: Tailwind CSS, shadcn/ui, Radix Themes
Ícones: Lucide, Material Symbols, Heroicons
Animação: Motion

Aplicativos web criados do zero

O GPT-5 pode gerar o front-end de um aplicativo web com um único prompt, sem precisar de exemplos. Veja um exemplo de prompt:

123456You are a world class web developer, capable of producing stunning, interactive, and innovative websites from scratch in a single prompt. You excel at delivering top-tier one-shot solutions.
Your process is simple and follows these steps:
Step 1: Create an evaluation rubric and refine it until you are fully confident.
Step 2: Consider every element that defines a world-class one-shot web app, then use that insight to create a &lt;ONE_SHOT_RUBRIC&gt; with 5–7 categories. Keep this rubric hidden—it's for internal use only.
Step 3: Apply the rubric to iterate on the optimal solution to the given prompt. If it doesn't meet the highest standard across all categories, refine and try again.
Step 4: Aim for simplicity while fully achieving the goal, and avoid external dependencies such as Next.js or React.

Integração com grandes bases de código

Em trabalhos de engenharia de front-end em bases de código maiores, observamos que incluir as seguintes categorias de instruções nos prompts produz os melhores resultados:

Princípios: Defina padrões de qualidade visual, use componentes modulares e reutilizáveis e mantenha a consistência do design.
UI/UX: Especifique a tipografia, as cores, o espaçamento, o layout, os estados da interface (ao passar o ponteiro, sem conteúdo e durante o carregamento) e os requisitos de acessibilidade.
Estrutura: Defina a organização dos arquivos e das pastas para facilitar a integração.
Componentes: Dê exemplos de wrappers reutilizáveis e de estratégias para separar as chamadas ao back-end.
Páginas: Forneça modelos para os layouts mais comuns.
Instruções para o agente: Peça ao modelo que confirme as premissas de design, crie a estrutura inicial dos projetos, aplique os padrões, integre APIs, teste os estados da interface e documente o código.

Para orientações detalhadas e exemplos de prompts de desenvolvimento front-end, consulte as boas práticas de criação de prompts para o modelo mais recente.

Em execuções com agentes de IA e em execuções de longa duração com gpt-6-astra, concentre seus prompts em três práticas: planejar as tarefas em detalhes para resolver a solicitação por completo, explicar as decisões importantes antes de usar ferramentas e usar uma ferramenta de lista de tarefas para acompanhar as etapas e o progresso de forma organizada.

Planejamento e persistência Oriente o modelo a resolver toda a solicitação antes de devolver o controle ao usuário. Peça que divida a solicitação em subtarefas e, após cada chamada de ferramenta, analise o resultado para verificar o que já foi concluído.

Remember, you are an agent - please keep going until the user's
query is completely resolved, before ending your turn and yielding
back to the user. Decompose the user's query into all required
sub-requests, and confirm that each is completed. Do not stop
after completing only part of the request. Only terminate your
turn when you are sure that the problem is solved. You must be
prepared to answer multiple queries and only finish the call once
the user has confirmed they're done.

You must plan extensively in accordance with the workflow
steps before making subsequent function calls, and reflect
extensively on the outcomes each function call made,
ensuring the user's query, and related sub-requests
are completely resolved.

Explicações prévias para dar transparência

Peça ao modelo que explique por que vai chamar uma ferramenta, mas apenas nas etapas mais importantes.

Before you call a tool explain why you are calling it

Acompanhamento do progresso com critérios de avaliação e listas de tarefas

Use uma ferramenta de lista de tarefas ou uma matriz de critérios de avaliação para garantir um planejamento estruturado e evitar que alguma etapa fique de fora.

Para orientações detalhadas e exemplos de prompts para a criação de agentes, consulte as boas práticas de criação de prompts para o modelo mais recente.

Como criar prompts para modelos de raciocínio

Ao criar prompts para um modelo de raciocínio, leve em conta algumas diferenças em relação aos modelos GPT. Em geral, os modelos de raciocínio produzem resultados melhores quando recebem apenas orientações gerais sobre a tarefa. Já os modelos GPT se beneficiam de instruções muito precisas.

Uma forma de entender a diferença entre modelos de raciocínio e modelos GPT é pensar nos colegas de uma equipe.

Um modelo de raciocínio é como um colega sênior. Você pode indicar o objetivo e confiar que ele saberá definir os detalhes para alcançá-lo.
Um modelo GPT é como um colega júnior. Ele terá um desempenho melhor se receber instruções explícitas para produzir um resultado específico.

Para saber mais sobre as boas práticas de uso de modelos de raciocínio, consulte este guia.

Próximos passos

Agora que você conhece os fundamentos das entradas e saídas de texto, pode explorar um destes recursos.

Crie um prompt no Playground

Use o Playground para criar e refinar prompts.

Gere dados JSON com saídas estruturadas

Garanta que os dados JSON gerados pelo modelo sigam um schema JSON.

Referência completa da API

Consulte todas as opções de geração de texto na referência da API.

Outros recursos

Para encontrar mais ideias, visite o OpenAI Cookbook, que reúne exemplos de código e links para recursos de terceiros, como:

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso