Configuración de agentes

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

Define el comportamiento del agente

Empieza con el modelo y las instrucciones; luego agrega las herramientas y los controles que necesite 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 razonamiento utiliza el modelo y el formato y nivel de detalle de sus respuestas.

Pasa estos ajustes en agent al crear una sesión. Este ejemplo proporciona un modelo, 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 los valores aceptados. Consulta Funciones y Conexiones MCP para configurar las herramientas, y Multiagente para conocer las opciones de delegación.

Reutiliza un agente en distintas sesiones

Guarda un agente para reutilizar su configuración en distintas sesiones. Créalo una vez y luego pasa su ID como 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 tiene su propia conversación y su propio trabajo. Consulta la Referencia de la API de agentes para listar, recuperar, actualizar o eliminar agentes guardados. Las credenciales permanecen en bóvedas, separadas de la configuración guardada.

Actualizar un agente guardado

Las actualizaciones de un agente guardado solo se aplican a las sesiones nuevas. Cada sesión copia la configuración guardada al crearla y la conserva para los turnos posteriores. Para modificar una sesión existente, actualiza su configuración.

Al actualizar un agente guardado:

Los campos omitidos conservan sus valores guardados. Si cambias solo model, se conservan reasoning, service_tier y text.
Los objetos proporcionados reemplazan todo el campo. Si proporcionas reasoning solo con effort, también se borra el valor guardado de summary.
null restablece los campos que lo aceptan. Por ejemplo, reasoning: null restaura el esfuerzo predeterminado del modelo.

En la misma solicitud, cambia o restablece cualquier ajuste que el nuevo modelo 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. Al crearse, la sesión copia del agente guardado los ajustes omitidos, incluido el modelo.

Reemplaza el valor de ejemplo agent_123 por el ID del agente guardado antes de ejecutar este ejemplo:

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 sobrescritos se aplican solo a esa sesión. No modifican el agente guardado ni otras sesiones. Los objetos y arreglos proporcionados reemplazan el campo completo en lugar de combinarse con el valor guardado. Por ejemplo, proporcionar tools reemplaza la lista de herramientas guardada.

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

Actualizar la configuración de una sesión existente

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

Los cambios se aplican a los turnos nuevos iniciados por mensajes enviados después de que se complete la actualización. Los mensajes que ya están en curso pueden usar la configuración anterior. Un turno activo conserva su configuración, incluso cuando envías un mensaje para reorientarlo. La sesión conserva su historial de conversación. El modelo seleccionado debe admitir la configuración resultante; de lo contrario, la actualización falla.

Los objetos agent y reasoning combinan los campos proporcionados con la configuración actual. Los campos omitidos permanecen sin cambios, incluido el resumen del razonamiento. Si cambias solo model, se conservan el esfuerzo de razonamiento y el nivel de servicio de la sesión.
reasoning.effort: null restablece el esfuerzo al valor predeterminado del modelo seleccionado.
service_tier: null restaura la selección automática del nivel de servicio.
Siempre debe haber un modelo configurado, por lo que no puedes proporcionar model: null. Los objetos agent y reasoning tampoco aceptan null.
metadata reemplaza el mapa completo. Omítelo 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 automáticamente el nivel de servicio:

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

Actualizar una sesión no modifica el agente guardado ni otras sesiones. Las actualizaciones posteriores del agente guardado no modifican la sesión.

No puedes actualizar reasoning.summary, text, tools, instructions ni multi_agent a través de este punto de acceso. Crea una sesión nueva para cambiar esos ajustes.

Configuración del entorno

Configura environment junto con agent al crear una sesión. Este ajuste 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 en OpenAI, configura los paquetes, los archivos iniciales y el acceso a la red que necesite la tarea. Puedes reutilizar una plantilla de entorno en distintas sesiones. Para un entorno autoalojado, 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. Consulta Artefactos de la sesión para conocer las opciones para los archivos que quieras conservar después de la ejecución.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Recursos

API heredadas

Elige un modelo

Texto y código

Diseño de prompts

Razonamiento

Imágenes y video

Tiempo real y audio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Búsqueda y recuperación

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Contenido multimedia

GPT-Live

Realtime API

Desarrollar con voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos fundamentales

Plan

Build

Test and publish

Conversion specs

Guías

Recursos

Primeros pasos

Guías

File Upload

API

Measurement

Advertiser API

Referencia de la API

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Referencia

Personalización

Archivo de configuración