An agent configuration defines how the agent behaves. You can supply it when creating a session or save it for reuse. The session holds the conversation and work, while the saved agent holds reusable settings.
Start with the model and instructions, then add the tools and controls your task needs:
- Model: Which model does the work.
- Instructions: What the agent should do and how it should behave.
- Tools: What actions the agent can take, such as searching the web or calling your functions.
- Reasoning and output: How much reasoning the model uses and the format and detail of its responses.
Pass these settings in agent when you create a session. This example supplies a model, instructions, and the first user message:
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
See the Agents API reference for configuration fields and accepted values. See Functions and MCP connections for tool setup, and Multi-agent for delegation.
Save an agent to reuse its configuration across sessions. Create it once, then pass its ID as agent_id when starting each session:
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
Each session has its own conversation and work. See the Agents API reference to list, retrieve, update, or delete saved agents. Credentials stay in vaults, separate from the saved configuration.
Saved-agent updates apply only to new sessions. Each session copies the saved configuration when you create it and keeps those settings for later turns. To change an existing session, update its settings.
When updating a saved agent:
- Omitted fields keep their saved values. Changing only
model preserves reasoning, service_tier, and text.
- Supplied objects replace the whole field. Supplying
reasoning with only effort also clears the saved summary.
null resets fields that accept it. For example, reasoning: null restores the model’s default effort.
Change or reset any settings the new model does not support in the same request.
Include both agent_id and agent when creating a session to customize a saved agent’s configuration. The session copies omitted settings, including the model, from the saved agent at creation time.
Replace the illustrative agent_123 value with the saved agent’s ID before running this example:
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
Overrides apply only to that session. They do not change the saved agent or other sessions. Supplied objects and arrays replace the entire field rather than merging with the saved value. For example, supplying tools replaces the saved tool list.
See the Create session reference for request fields.
Send POST /v1/agents/sessions/{session_id} with an agent object to change model, reasoning.effort, or service_tier for one session. These settings are available in the beta and GA API contracts. You can update metadata in the same request.
Changes apply to new turns started by messages sent after the update completes. Messages already in flight can use the previous settings. An active turn keeps its settings, including when you send a steering message. The session keeps its conversation history. The selected model must support the resulting settings, or the update fails.
- The
agent and reasoning objects merge supplied fields into the current settings. Omitted fields stay unchanged, including reasoning summary. Changing only model preserves the session’s reasoning effort and service tier.
reasoning.effort: null resets effort to the selected model’s default.service_tier: null restores automatic tier selection.- A model must remain set, so you cannot supply
model: null. The agent and reasoning objects also reject null.
metadata replaces the full map. Omit it to preserve metadata, or pass null or {} to clear it.
For example, this request changes reasoning effort and lets the API select the service tier automatically:
123456{
"agent": {
"reasoning": { "effort": "low" },
"service_tier": null
}
}
Updating a session does not change the saved agent or other sessions. Later saved-agent updates do not change the session.
You cannot update reasoning.summary, text, tools, instructions, or multi_agent through this endpoint. Create a new session to change those settings.
Set environment alongside agent when creating a session. It determines where the agent runs commands and works with files.
Choose none, openai_hosted, or self_hosted. Architecture explains when to use each option and who manages the environment.
For an OpenAI-hosted environment, configure the packages, initial files, and network access the task needs. You can reuse an environment template across sessions. For a self-hosted environment, prepare your compute and connect an executor.
See the Create session reference for environment fields and Plugins for skills, plugins, and templates. See Session artifacts for files you want to keep after execution.
