Configuración de agentes

La configuración de un agente define cómo se comporta. Puedes especificarla al crear una sesión o guardarla para reutilizarla. La sesión contiene la conversación y el trabajo realizado, mientras que el agente guardado conserva los ajustes reutilizables.

Define el comportamiento del agente

Empieza por el modelo y las instrucciones. Luego agrega las herramientas y los controles que necesites para tu tarea:

Modelo: qué modelo realiza el trabajo.
Instrucciones: qué debe hacer el agente y cómo debe comportarse.
Herramientas: qué acciones puede realizar el agente, como buscar en la web o llamar a tus funciones.
Razonamiento y salida: cuánto esfuerzo dedica el modelo al razonamiento y qué formato y nivel de detalle tienen sus respuestas.

Pasa estos ajustes en agent al crear una sesión. En este ejemplo se especifican el modelo, las instrucciones y el primer mensaje del usuario:

Configura un agente para una sesión

Python

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

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: "Answer the user clearly and concisely.",
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What can you help with?",
        },
      ],
    },
  ],
});

console.log(session);

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

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

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
32import (
	"context"
	"fmt"

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

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("Answer the user clearly and concisely."),
		},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions("Answer the user clearly and concisely.")
                        .build())
                .environmentNone()
                .input("What can you help with?")
                .build());
System.out.println(result);

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

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "Answer the user clearly and concisely."
  },
  environment: { type: "none" },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What can you help with?"
        }
      ]
    }
  ]
)
puts result

Consulta la referencia de la API de agentes para conocer los campos de configuración y sus valores. Para ver cómo configurar cada opción, consulta Funciones, Uso de la computadora, Conexiones MCP o Delegación entre agentes.

Tamaño de la configuración

Mantén el tamaño total de las instrucciones y la configuración de herramientas por debajo de 4 MiB (4 194 304 bytes) y deja un pequeño margen para los metadatos de la API de agentes. Si la sesión no se inicia porque la configuración es demasiado grande, reduce el tamaño de las instrucciones y de la configuración de herramientas y crea una sesión nueva.

Los archivos que subas al entorno tienen sus propios límites.

Reutiliza un agente en varias sesiones

Guarda un agente para reutilizar su configuración en varias sesiones. Créalo una sola vez y pasa su ID en agent_id al iniciar cada sesión:

Reutiliza un agente

Python

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

const client = new OpenAI();
const agent = await client.beta.agents.create({
  model: "gpt-6-astra",
  instructions: "Answer technical questions accurately.",
  reasoning: {
    summary: "auto",
  },
});
const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  environment: { type: "none" },
  input: "Explain how an agent connects to an MCP server.",
});
console.log(session);

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

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

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
28import (
	"context"
	"fmt"

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

ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
	openai.BetaAgentNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String("Answer technical questions accurately."),
		Reasoning:    openai.AgentReasoningParam{Summary: "auto"},
	})
if err != nil {
	panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String(agent.ID),
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input:       openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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
32import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
    client
        .beta()
        .agents()
        .create(
            AgentCreateParams.builder()
                .model("gpt-6-astra")
                .instructions("Answer technical questions accurately.")
                .reasoning(
                    AgentReasoningParam.builder()
                        .summary(AgentReasoningParam.Summary.of("auto"))
                        .build())
                .build());
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId(agent.id())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

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

client = OpenAI::Client.new
agent = client.beta.agents.create(
  model: "gpt-6-astra",
  instructions: "Answer technical questions accurately.",
  reasoning: { summary: "auto" }
)
result = client.beta.agents.sessions.create(
  agent_id: agent.id,
  environment: { type: "none" },
  input: "Explain how an agent connects to an MCP server."
)
puts result

Cada sesión mantiene su propia conversación y su propio trabajo. Consulta la referencia de la API de agentes para ver cómo listar, recuperar, actualizar o eliminar agentes guardados. Las credenciales se conservan en bóvedas, por separado de la configuración guardada.

Actualiza un agente guardado

Los cambios que hagas en un agente guardado solo se aplican a las sesiones nuevas. Al crear una sesión, esta copia la configuración guardada y conserva esos ajustes para los turnos posteriores. Para modificar una sesión existente, actualiza sus ajustes.

Al actualizar un agente guardado, ten en cuenta lo siguiente:

Los campos que omitas conservan sus valores guardados. Si solo cambias model, se conservan reasoning, service_tier y text.
Cada objeto que envíes reemplaza todo el valor del campo correspondiente. Si envías reasoning solo con effort, también se borra el valor guardado de summary.
null restablece los campos que aceptan ese valor. Por ejemplo, reasoning: null restablece el esfuerzo de razonamiento predeterminado del modelo.

En la misma solicitud, cambia o restablece los ajustes que el modelo nuevo no admita.

Sobrescribe los ajustes para una sesión

Incluye tanto agent_id como agent al crear una sesión para personalizar la configuración de un agente guardado. En el momento de la creación, la sesión copia del agente guardado los ajustes que omitas, incluido el modelo si no lo especificas.

Antes de ejecutar este ejemplo, reemplaza el valor de ejemplo agent_123 por el ID del agente guardado:

Sobrescribe la configuración de un agente para una sesión

Python

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// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
  agent_id: agentId,
  agent: {
    instructions: "Answer this question in one concise paragraph.",
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Explain how an agent connects to an MCP server.",
        },
      ],
    },
  ],
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

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// Replace the illustrative IDs and URLs below with your own resource values.
import (
	"context"
	"fmt"

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

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String("agent_123"),
		Agent:       openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId("agent_123")
                .agent(
                    SessionCreateParams.Agent.builder()
                        .instructions("Answer this question in one concise paragraph.")
                        .build())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent_id: "agent_123",
  agent: { instructions: "Answer this question in one concise paragraph." },
  environment: { type: "none" },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Explain how an agent connects to an MCP server."
        }
      ]
    }
  ]
)
puts result

Los ajustes que sobrescribas solo se aplican a esa sesión. No modifican el agente guardado ni las demás sesiones. Los objetos y los arreglos que envíes reemplazan todo el valor del campo sin combinarse con el valor guardado. Por ejemplo, si envías tools, se reemplaza la lista de herramientas guardada.

Consulta la referencia de creación de sesiones para conocer los campos de la solicitud.

Actualiza los ajustes de una sesión existente

Envía una solicitud POST /v1/agents/sessions/{session_id} con un objeto agent para cambiar tools, model, reasoning.effort o service_tier en una sola sesión. Estos ajustes están disponibles en los contratos de la API tanto en beta como en disponibilidad general. Puedes actualizar metadata en la misma solicitud.

Los cambios en el modelo, el esfuerzo de razonamiento y el nivel de servicio se aplican a los turnos nuevos que se inicien con mensajes enviados después de que se complete la actualización. Los mensajes que ya estén en curso pueden usar los ajustes anteriores. Un turno activo conserva esos ajustes incluso si envías un mensaje para reorientarlo. La sesión conserva el historial de la conversación. Si el modelo seleccionado no admite los ajustes resultantes, la actualización falla.

Los objetos agent y reasoning incorporan los campos que envíes a la configuración actual. Los campos que omitas conservan sus valores, incluido el resumen del razonamiento. Si solo cambias model, la sesión conserva su esfuerzo de razonamiento y su nivel de servicio.
tools reemplaza la lista completa de herramientas. Los cambios en las funciones y los servidores MCP se aplican en la siguiente llamada al modelo. Los cambios en las herramientas integradas se aplican a más tardar en el siguiente turno. Omite tools para conservar las herramientas actuales o pasa null o [] para vaciar la lista.
reasoning.effort: null restablece el esfuerzo de razonamiento al valor predeterminado del modelo seleccionado.
service_tier: null restablece la selección automática del nivel de servicio.
Siempre debe haber un modelo definido, por lo que no puedes enviar model: null. Los objetos agent y reasoning tampoco aceptan null.
metadata reemplaza todo el mapa de metadatos. Omite este campo para conservar los metadatos o pasa null o {} para borrarlos.

Por ejemplo, esta solicitud cambia el esfuerzo de razonamiento y permite que la API seleccione el nivel de servicio de forma automática:

123456{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

Actualizar una sesión no modifica el agente guardado ni las demás sesiones. Los cambios posteriores en el agente guardado tampoco modifican esa sesión.

No puedes actualizar reasoning.summary, text, instructions ni multi_agent mediante este punto de acceso. Crea una sesión nueva para cambiar esos ajustes. Consulta la referencia de actualización de sesiones para conocer los campos de la solicitud.

Revisión automática de acciones

Asigna al campo de sesión review el valor "auto_review" para que la API revise automáticamente las solicitudes de aprobación compatibles. Incluye el campo al mismo nivel que agent o agent_id, fuera de la configuración del agente. Si omites review al crear una sesión, el valor predeterminado es "none".

La revisión automática también cambia los permisos de ejecución. Consulta los requisitos previos del entorno antes de habilitarla.

Puedes actualizar review cuando la tarea principal esté inactiva y haya finalizado el envío de datos de entrada. El nuevo ajuste se aplica a las operaciones posteriores de ejecución y recuperación. Si solicitas el cambio de modo antes de que se cumplan ambas condiciones, la API devuelve 409 Conflict y no aplica ningún cambio. Usa un proyecto que tenga habilitada la revisión automática y una sesión que la admita. Consulta Revisión automática para ver cómo configurarla y cómo gestionar las solicitudes de aprobación.

Configuración del entorno

Especifica environment junto con agent al crear una sesión. El entorno determina dónde ejecuta comandos el agente y dónde trabaja con archivos.

Elige none, openai_hosted o self_hosted. En Arquitectura se explica cuándo usar cada opción y quién administra el entorno.

Para un entorno alojado por OpenAI, elige el tamaño del contenedor y configura los paquetes, los archivos iniciales y el acceso a la red que requiera la tarea. Puedes reutilizar una plantilla de entorno en varias sesiones. Para un entorno alojado en tu propia infraestructura, prepara tus recursos de cómputo y conecta un ejecutor.

Consulta la referencia de creación de sesiones para conocer los campos del entorno y Complementos para obtener información sobre habilidades, complementos y plantillas. Si quieres conservar archivos después de la ejecución, consulta Artefactos de sesión.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración