Repository Public
1# Configuring Agents23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45An 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.67## Define the agent's behavior89Start with the model and instructions, then add the tools and controls your task needs:1011- **Model:** Which model does the work.12- **Instructions:** What the agent should do and how it should behave.13- **Tools:** What actions the agent can take, such as searching the web or calling your functions.14- **Reasoning and output:** How much reasoning the model uses and the format and detail of its responses.1516Pass these settings in `agent` when you create a session. This example supplies a model, instructions, and the first user message:1718Configure an agent for one session1920```javascript21import OpenAI from "openai";22const client = new OpenAI();2324const session = await client.beta.agents.sessions.create({25 agent: {26 model: "gpt-6-astra",27 instructions: "Answer the user clearly and concisely.",28 },29 environment: {30 type: "none",31 },32 input: [33 {34 role: "user",35 content: [36 {37 type: "input_text",38 text: "What can you help with?",39 },40 ],41 },42 ],43});4445console.log(session);46```4748```python49from openai import OpenAI5051client = OpenAI()5253session = client.beta.agents.sessions.create(54 agent={55 "model": "gpt-6-astra",56 "instructions": "Answer the user clearly and concisely.",57 },58 environment={"type": "none"},59 input=[60 {61 "role": "user",62 "content": [{"type": "input_text", "text": "What can you help with?"}],63 }64 ],65)66print(session.to_json())67```6869```go70import (71 "context"72 "fmt"7374 "github.com/openai/openai-go/v3"75)7677ctx := context.Background()78client := openai.NewClient()79result, err := client.Beta.Agents.Sessions.New(ctx,80 openai.BetaAgentSessionNewParams{81 Agent: openai.BetaAgentSessionNewParamsAgent{82 Model: openai.String("gpt-6-astra"),83 Instructions: openai.String("Answer the user clearly and concisely."),84 },85 Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},86 Input: openai.BetaAgentSessionNewParamsInputUnion{87 OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{88 {89 Content: []openai.InputContentParamUnion{90 {91 OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},92 },93 },94 },95 },96 },97 })98if err != nil {99 panic(err)100}101fmt.Println(result)102```103104```java105import com.openai.client.OpenAIClient;106import com.openai.client.okhttp.OpenAIOkHttpClient;107import com.openai.models.beta.agents.sessions.SessionCreateParams;108109OpenAIClient client = OpenAIOkHttpClient.fromEnv();110var result =111 client112 .beta()113 .agents()114 .sessions()115 .create(116 SessionCreateParams.builder()117 .agent(118 SessionCreateParams.Agent.builder()119 .model("gpt-6-astra")120 .instructions("Answer the user clearly and concisely.")121 .build())122 .environmentNone()123 .input("What can you help with?")124 .build());125System.out.println(result);126```127128```ruby129require "openai"130131client = OpenAI::Client.new132result = client.beta.agents.sessions.create(133 agent: {134 model: "gpt-6-astra",135 instructions: "Answer the user clearly and concisely."136 },137 environment: { type: "none" },138 input: [139 {140 role: "user",141 content: [142 {143 type: "input_text",144 text: "What can you help with?"145 }146 ]147 }148 ]149)150puts result151```152153154See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) for configuration fields and accepted values. See [Functions](https://developers.openai.com/api/docs/guides/agents-api/tools/functions) and [MCP connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp) for tool setup, and [Multi-agent](https://developers.openai.com/api/docs/guides/agents-api/multi-agent) for delegation.155156## Reuse an agent across sessions157158Save an agent to reuse its configuration across sessions. Create it once, then pass its ID as `agent_id` when starting each session:159160Reuse an agent161162```javascript163import OpenAI from "openai";164165const client = new OpenAI();166const agent = await client.beta.agents.create({167 model: "gpt-6-astra",168 instructions: "Answer technical questions accurately.",169 reasoning: {170 summary: "auto",171 },172});173const session = await client.beta.agents.sessions.create({174 agent_id: agent.id,175 environment: { type: "none" },176 input: "Explain how an agent connects to an MCP server.",177});178console.log(session);179```180181```python182from openai import OpenAI183184client = OpenAI()185agent = client.beta.agents.create(186 model="gpt-6-astra",187 instructions="Answer technical questions accurately.",188 reasoning={"summary": "auto"},189 timeout=360,190)191session = client.beta.agents.sessions.create(192 agent_id=agent.id,193 environment={"type": "none"},194 input="Explain how an agent connects to an MCP server.",195)196print(session.to_json())197```198199```go200import (201 "context"202 "fmt"203204 "github.com/openai/openai-go/v3"205)206207ctx := context.Background()208client := openai.NewClient()209agent, err := client.Beta.Agents.New(ctx,210 openai.BetaAgentNewParams{211 Model: "gpt-6-astra",212 Instructions: openai.String("Answer technical questions accurately."),213 Reasoning: openai.AgentReasoningParam{Summary: "auto"},214 })215if err != nil {216 panic(err)217}218result, err := client.Beta.Agents.Sessions.New(ctx,219 openai.BetaAgentSessionNewParams{220 AgentID: openai.String(agent.ID),221 Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},222 Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},223 })224if err != nil {225 panic(err)226}227fmt.Println(result)228```229230```java231import com.openai.client.OpenAIClient;232import com.openai.client.okhttp.OpenAIOkHttpClient;233import com.openai.models.beta.agents.AgentCreateParams;234import com.openai.models.beta.agents.AgentReasoningParam;235import com.openai.models.beta.agents.sessions.SessionCreateParams;236237OpenAIClient client = OpenAIOkHttpClient.fromEnv();238var agent =239 client240 .beta()241 .agents()242 .create(243 AgentCreateParams.builder()244 .model("gpt-6-astra")245 .instructions("Answer technical questions accurately.")246 .reasoning(247 AgentReasoningParam.builder()248 .summary(AgentReasoningParam.Summary.of("auto"))249 .build())250 .build());251var result =252 client253 .beta()254 .agents()255 .sessions()256 .create(257 SessionCreateParams.builder()258 .agentId(agent.id())259 .environmentNone()260 .input("Explain how an agent connects to an MCP server.")261 .build());262System.out.println(result);263```264265```ruby266require "openai"267268client = OpenAI::Client.new269agent = client.beta.agents.create(270 model: "gpt-6-astra",271 instructions: "Answer technical questions accurately.",272 reasoning: { summary: "auto" }273)274result = client.beta.agents.sessions.create(275 agent_id: agent.id,276 environment: { type: "none" },277 input: "Explain how an agent connects to an MCP server."278)279puts result280```281282283Each session has its own conversation and work. See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) to list, retrieve, update, or delete saved agents. Credentials stay in [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults), separate from the saved configuration.284285## Update a saved agent286287Saved-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](#update-settings-for-an-existing-session).288289When updating a saved agent:290291- Omitted fields keep their saved values. Changing only `model` preserves `reasoning`, `service_tier`, and `text`.292- Supplied objects replace the whole field. Supplying `reasoning` with only `effort` also clears the saved `summary`.293- `null` resets fields that accept it. For example, `reasoning: null` restores the model's default effort.294295Change or reset any settings the new model does not support in the same request.296297## Override settings for one session298299Include 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.300301Replace the illustrative `agent_123` value with the saved agent's ID before running this example:302303Override an agent for one session304305```javascript306// Replace the illustrative IDs and URLs below with your own resource values.307import OpenAI from "openai";308const client = new OpenAI();309310const agentId = "agent_123";311const session = await client.beta.agents.sessions.create({312 agent_id: agentId,313 agent: {314 instructions: "Answer this question in one concise paragraph.",315 },316 environment: {317 type: "none",318 },319 input: [320 {321 role: "user",322 content: [323 {324 type: "input_text",325 text: "Explain how an agent connects to an MCP server.",326 },327 ],328 },329 ],330});331332console.log(session);333```334335```python336# Replace the illustrative IDs and URLs below with your own resource values.337from openai import OpenAI338339client = OpenAI()340341agent_id = "agent_123"342session = client.beta.agents.sessions.create(343 agent_id=agent_id,344 agent={"instructions": "Answer this question in one concise paragraph."},345 environment={"type": "none"},346 input=[347 {348 "role": "user",349 "content": [350 {351 "type": "input_text",352 "text": "Explain how an agent connects to an MCP server.",353 }354 ],355 }356 ],357)358print(session.to_json())359```360361```go362// Replace the illustrative IDs and URLs below with your own resource values.363import (364 "context"365 "fmt"366367 "github.com/openai/openai-go/v3"368)369370ctx := context.Background()371client := openai.NewClient()372result, err := client.Beta.Agents.Sessions.New(ctx,373 openai.BetaAgentSessionNewParams{374 AgentID: openai.String("agent_123"),375 Agent: openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},376 Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},377 Input: openai.BetaAgentSessionNewParamsInputUnion{378 OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{379 {380 Content: []openai.InputContentParamUnion{381 {382 OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},383 },384 },385 },386 },387 },388 })389if err != nil {390 panic(err)391}392fmt.Println(result)393```394395```java396// Replace the illustrative IDs and URLs below with your own resource values.397import com.openai.client.OpenAIClient;398import com.openai.client.okhttp.OpenAIOkHttpClient;399import com.openai.models.beta.agents.sessions.SessionCreateParams;400401OpenAIClient client = OpenAIOkHttpClient.fromEnv();402var result =403 client404 .beta()405 .agents()406 .sessions()407 .create(408 SessionCreateParams.builder()409 .agentId("agent_123")410 .agent(411 SessionCreateParams.Agent.builder()412 .instructions("Answer this question in one concise paragraph.")413 .build())414 .environmentNone()415 .input("Explain how an agent connects to an MCP server.")416 .build());417System.out.println(result);418```419420```ruby421# Replace the illustrative IDs and URLs below with your own resource values.422require "openai"423424client = OpenAI::Client.new425result = client.beta.agents.sessions.create(426 agent_id: "agent_123",427 agent: { instructions: "Answer this question in one concise paragraph." },428 environment: { type: "none" },429 input: [430 {431 role: "user",432 content: [433 {434 type: "input_text",435 text: "Explain how an agent connects to an MCP server."436 }437 ]438 }439 ]440)441puts result442```443444445Overrides 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.446447See the [Create session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/create) for request fields.448449## Update settings for an existing session450451Send `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.452453Changes 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.454455- 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.456- `reasoning.effort: null` resets effort to the selected model's default.457- `service_tier: null` restores automatic tier selection.458- A model must remain set, so you cannot supply `model: null`. The `agent` and `reasoning` objects also reject `null`.459- `metadata` replaces the full map. Omit it to preserve metadata, or pass `null` or `{}` to clear it.460461For example, this request changes reasoning effort and lets the API select the service tier automatically:462463```json464{465 "agent": {466 "reasoning": { "effort": "low" },467 "service_tier": null468 }469}470```471472Updating a session does not change the saved agent or other sessions. Later saved-agent updates do not change the session.473474You cannot update `reasoning.summary`, `text`, `tools`, `instructions`, or `multi_agent` through this endpoint. Create a new session to change those settings.475476## Environment settings477478Set `environment` alongside `agent` when creating a session. It determines where the agent runs commands and works with files.479480481482483484485486487488489490491Choose `none`, `openai_hosted`, or `self_hosted`. [Architecture](https://developers.openai.com/api/docs/guides/agents-api/architecture) explains when to use each option and who manages the environment.492493For 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](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted).494495See the [Create session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/create) for environment fields and [Plugins](https://developers.openai.com/api/docs/guides/agents-api/tools/plugins) for skills, plugins, and templates. See [Session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files) for files you want to keep after execution.