Engenharia de prompt

Com a API da OpenAI, você pode usar um modelo de linguagem de grande porte para gerar texto a partir de um prompt, assim como faria no ChatGPT. Os modelos podem gerar quase qualquer tipo de resposta em texto, como código, equações matemáticas, dados estruturados em JSON ou textos semelhantes aos escritos por pessoas.

Veja um exemplo simples usando a Responses API.

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, temos apenas uma saída, com este formato:

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 tokens de raciocínio gerados por modelos de raciocínio e outros itens. Não é seguro presumir que a saída de texto do modelo esteja em output[0].content[0].text.

Alguns dos nossos SDKs oficiais incluem, por conveniência, uma propriedade output_text nas respostas do modelo, que reúne todas as saídas de texto em uma única string. Ela pode ser útil como um atalho para acessar a saída de texto do modelo.

Além de texto simples, você também pode fazer o modelo retornar dados estruturados em formato JSON. Esse recurso se chama Saídas estruturadas.

Veja um exemplo simples usando 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, temos apenas uma saída, com este formato:

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, você também pode fazer o modelo retornar dados estruturados em formato JSON. Esse recurso se chama Saídas estruturadas.

Escolha de um modelo

Uma decisão importante ao gerar conteúdo pela API é qual modelo usar, definido pelo parâmetro model nos exemplos de código acima. Você encontra aqui a lista completa de modelos disponíveis. Veja alguns fatores a considerar 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 e se destacam na compreensão de tarefas complexas e no planejamento de várias etapas. Em geral, também são mais lentos e mais caros de usar do que os modelos GPT.
Modelos GPT são rápidos, econômicos e altamente inteligentes, mas se beneficiam de 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 compreensão de prompts e na resolução de problemas em diversas áreas, enquanto os modelos pequenos geralmente são mais rápidos e mais baratos de usar.

Em caso de dúvida, gpt-6-astra é uma boa escolha padrão para geração de texto de uso geral e refinamento de prompts.

Engenharia de prompt

Engenharia de prompt é o processo de escrever instruções eficazes para um modelo, de modo que ele gere, de forma consistente, conteúdo que atenda aos seus requisitos.

Como o conteúdo gerado por um modelo não é determinístico, criar prompts para obter a saída desejada é uma mistura de arte e ciência. Ainda assim, você pode aplicar técnicas e práticas recomendadas para obter bons resultados de forma consistente.

Algumas técnicas de engenharia de prompt funcionam com qualquer modelo, como o uso de papéis de mensagem. Porém, diferentes tipos de modelo, como os de raciocínio e os GPT, podem precisar de abordagens diferentes na criação de prompts para produzir os melhores resultados. Até mesmo snapshots diferentes de modelos da mesma família podem produzir resultados distintos. Por isso, à medida que você desenvolve aplicativos mais complexos, recomendamos fortemente:

Fixar snapshots específicos de modelos (como gpt-4.1-2025-04-14, por exemplo) nos seus aplicativos em produção para garantir um comportamento consistente
Criar testes e suítes de avaliação que meçam o comportamento dos prompts para acompanhar o desempenho à medida que você os refina ou quando troca ou atualiza as versões dos modelos

Agora, vamos examinar algumas ferramentas e técnicas disponíveis para criar prompts.

Papéis de mensagem e cumprimento de instruções

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

O parâmetro instructions fornece ao modelo instruções gerais sobre como ele deve se comportar ao gerar uma resposta, incluindo tom, objetivos e exemplos de respostas corretas. As instruções fornecidas dessa forma terão prioridade sobre um prompt no 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 é aproximadamente equivalente 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?"
            }
        ]
    }'

Observe que 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, as instruções de instructions usadas nas interações anteriores não estarão presentes no contexto.

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

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 diferentes níveis de prioridade a mensagens com papéis diferentes.

`developer`	`user`	`assistant`
Mensagens `developer` são instruções fornecidas pelo desenvolvedor do aplicativo e têm prioridade sobre mensagens `user`.	Mensagens `user` são instruções fornecidas por um usuário final e têm prioridade inferior à das mensagens `developer`.	As mensagens geradas pelo modelo têm o papel `assistant`.

Uma conversa com várias interações pode conter diversas mensagens desses tipos, além de outros tipos de conteúdo fornecidos tanto por você quanto pelo modelo. Saiba mais sobre como gerenciar o estado da conversa aqui.

Você pode pensar nas mensagens developer e user como uma função e seus argumentos em uma linguagem de programação.

Mensagens developer fornecem as regras e a lógica de negócio do sistema, como a definição de uma função.
Mensagens user fornecem entradas e configurações às quais se aplicam as instruções da mensagem developer, como argumentos de uma função.

Versione prompts no código

Armazene os prompts de produção no código do seu aplicativo em vez de criar objetos de prompt reutilizáveis. Gerenciar prompts no código permite 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 passará a ter menos destaque a partir de 3 de junho de 2026, e o encerramento de v1/prompts está previsto para 30 de novembro de 2026. Consulte a página de descontinuações para ver o cronograma atual.

Para novos trabalhos de engenharia de prompt:

Mantenha os construtores de prompts em um módulo pequeno, próximo à funcionalidade que atendem.
Use argumentos de função tipados ou esquemas para valores dinâmicos, como dados de clientes, arquivos ou opções de tarefas.
Passe os valores gerados de instructions e input diretamente para a Responses API.
Adicione dados de teste representativos, testes e verificações de avaliação antes de alterar os prompts de produção.
Disponibilize as alterações nos prompts pelo seu sistema de implantação, usando sinalizadores de funcionalidade ou configurações quando precisar de lançamentos em etapas.

Se sua integração já chama um prompt salvo usando um ID ou uma versão de prompt, use 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 ajudar o modelo a entender os limites lógicos do prompt e dos dados de contexto combinando a formatação Markdown com tags XML.

Títulos e listas em Markdown podem ajudar a delimitar as diferentes seções de um prompt e a comunicar a hierarquia ao modelo. Também podem facilitar a leitura dos prompts durante o desenvolvimento. Tags XML podem ajudar a delimitar onde um conteúdo começa e termina, como um documento de apoio usado como referência. Atributos XML também podem definir metadados sobre o conteúdo do prompt que suas instruções podem referenciar.

Em geral, uma mensagem do desenvolvedor contém as seções a seguir, normalmente nesta ordem (embora o conteúdo e a ordem ideais possam variar conforme o modelo usado):

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 o modelo deve fazer e o que nunca deve fazer? Esta seção pode conter várias subseções relevantes para seu caso de uso, como orientações sobre como o modelo deve chamar funções personalizadas.
Exemplos: Forneça exemplos de entradas possíveis, acompanhados da saída desejada do modelo.
Contexto: Forneça ao modelo as informações adicionais de que ele possa precisar para gerar uma resposta, como dados privados ou proprietários que não façam parte dos dados de treinamento, ou quaisquer outros dados que você saiba serem especialmente relevantes. Em geral, é melhor posicionar esse conteúdo perto do fim do prompt, pois você pode incluir contextos diferentes em cada solicitação de geração.

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

Uma mensagem do 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 criar uma mensagem, procure manter o conteúdo que você pretende reutilizar nas requisições à API no início do prompt e entre os primeiros parâmetros da API enviados no corpo JSON da requisição a Chat Completions ou Responses. Isso permite maximizar a redução de custos e latência proporcionada pelo cache de prompts.

Aprendizado few-shot

O aprendizado few-shot permite orientar um modelo de linguagem grande para uma nova tarefa incluindo alguns exemplos de entrada e saída no prompt, em vez de realizar o ajuste fino do modelo. O modelo assimila implicitamente o padrão desses exemplos e o aplica a um prompt. Ao fornecer exemplos, procure apresentar entradas variadas com as saídas desejadas.

Normalmente, você fornece exemplos como parte de uma mensagem developer na requisição à API. Veja uma mensagem developer com exemplos que mostram ao modelo como classificar avaliações de atendimento ao cliente como positivas ou negativas.

# 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, é útil incluir no prompt informações de contexto adicionais que o modelo possa usar para gerar uma resposta. Alguns motivos comuns para fazer isso são:

Dar ao modelo acesso a dados proprietários ou a quaisquer outros dados que não façam parte do conjunto usado em seu treinamento.
Restringir a resposta do modelo a um conjunto específico de recursos que você identificou como os mais úteis.

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

Planeje o uso da janela de contexto

Os modelos só conseguem processar uma quantidade limitada de dados no contexto que consideram durante uma solicitação de geração. Esse limite de memória é chamado de janela de contexto e é definido em tokens (fragmentos dos dados que você fornece, de texto a imagens).

Os modelos têm janelas de contexto de tamanhos diferentes, que vão de pouco mais de 100 mil tokens até um milhão de tokens nos modelos GPT-4.1 mais recentes. Consulte a documentação dos modelos para saber o tamanho específico da janela de contexto de cada modelo.

Criação de prompts para os modelos atuais

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

GPT-6 Astra prompting guide

Aproveite ao máximo a criação de prompts para o modelo mais recente com orientações atualizadas, exemplos práticos e notas de migração.

Práticas recomendadas de criação de prompts para o modelo mais recente

Para uma abordagem completa e atualizada, consulte as práticas recomendadas de criação de prompts para o modelo mais recente. Os lembretes práticos abaixo continuam válidos.

GPT-6 Astra

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

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

Aplicativos web do zero

O GPT-5 pode gerar aplicativos web de front-end a partir de 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

Para trabalhos de engenharia de front-end em bases de código maiores, constatamos que adicionar estas categorias de instruções aos prompts produz os melhores resultados:

Princípios: Estabeleça padrões de qualidade visual, use componentes modulares e reutilizáveis e mantenha a consistência do design.
UI/UX: Especifique tipografia, cores, espaçamento e layout, estados de interação (ao passar o cursor, vazio, carregando) e acessibilidade.
Estrutura: Defina a organização de arquivos e pastas para facilitar a integração.
Componentes: Forneça exemplos de componentes que encapsulem outros componentes de forma reutilizável e estratégias para separar as chamadas ao back-end.
Páginas: Forneça modelos para layouts comuns.
Instruções para o agente: Peça ao modelo que confirme as premissas de design, crie a estrutura inicial dos projetos, garanta o cumprimento dos padrões, integre APIs, teste os estados e documente o código.

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

Para execuções agênticas e de longa duração com gpt-6-astra, concentre seus prompts em três práticas essenciais: planejar as tarefas em detalhes para garantir sua resolução completa, fornecer preâmbulos claros para as principais decisões de uso de ferramentas e usar uma ferramenta de lista de tarefas para acompanhar o fluxo de trabalho e o progresso de forma organizada.

Planejamento e persistência Instrua o modelo a resolver toda a solicitação antes de devolver o controle, dividindo-a em subtarefas e refletindo após cada chamada de ferramenta para confirmar que tudo 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.

Mensagens introdutórias para dar transparência

Peça ao modelo que explique por que está chamando 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 um conjunto de critérios de avaliação para garantir um planejamento estruturado e evitar que etapas sejam esquecidas.

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

Criação de prompts para modelos de raciocínio

Há algumas diferenças a considerar ao criar prompts para um modelo de raciocínio em comparação com um modelo GPT. Em geral, os modelos de raciocínio apresentam melhores resultados em tarefas com apenas orientações gerais. Já os modelos GPT se beneficiam de instruções muito precisas.

Você pode pensar na diferença entre modelos de raciocínio e modelos GPT da seguinte forma.

Um modelo de raciocínio é como um colega de trabalho sênior. Você pode definir um objetivo e confiar que ele encontrará a melhor forma de alcançá-lo.
Um modelo GPT é como um colega de trabalho júnior. Ele terá um desempenho melhor com instruções explícitas para produzir um resultado específico.

Para saber mais sobre as práticas recomendadas ao usar modelos de raciocínio, consulte este guia.

Próximos passos

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

Crie um prompt no Playground

Use o Playground para desenvolver e aprimorar prompts.

Gere dados JSON com saídas estruturadas

Garanta que os dados JSON gerados por um modelo estejam em conformidade com um esquema JSON.

Referência completa da API

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

Outros recursos

Para mais inspiração, acesse o OpenAI Cookbook, que contém exemplos de código e links para recursos de terceiros, como:

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