Repository Public
1# Manage sessions23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Store each session ID with your application's data store. Use it to retrieve the session's current state, handle requests from the agent, or delete the session.678910## Find sessions1112List sessions in your project to browse previous work. SDK pagination helpers retrieve additional pages:1314List sessions and retrieve the next page1516```javascript17import OpenAI from "openai";1819const client = new OpenAI();20let page = await client.beta.agents.sessions.list({ limit: 20 });21console.log(page.data);22if (page.hasNextPage()) {23 page = await page.getNextPage();24 console.log(page.data);25}26```2728```python29from openai import OpenAI3031client = OpenAI()32page = client.beta.agents.sessions.list(limit=20)33print(page.to_json())34if page.has_next_page():35 page = page.get_next_page()36 print(page.to_json())37```3839```go40import (41 "context"42 "fmt"4344 "github.com/openai/openai-go/v3"45)4647ctx := context.Background()48client := openai.NewClient()49result, err := client.Beta.Agents.Sessions.List(ctx,50 openai.BetaAgentSessionListParams{Limit: openai.Int(20)})51if err != nil {52 panic(err)53}54fmt.Println(result.Data)55if result.HasMore {56 result, err = result.GetNextPage()57 if err != nil {58 panic(err)59 }60 fmt.Println(result.Data)61}62```6364```java65import com.openai.client.OpenAIClient;66import com.openai.client.okhttp.OpenAIOkHttpClient;67import com.openai.models.beta.agents.sessions.SessionListParams;6869OpenAIClient client = OpenAIOkHttpClient.fromEnv();70var result =71 client.beta().agents().sessions().list(SessionListParams.builder().limit(20L).build());72System.out.println(result.items());73if (result.hasNextPage()) {74 result = result.nextPage();75 System.out.println(result.items());76}77```7879```ruby80require "openai"8182client = OpenAI::Client.new83result = client.beta.agents.sessions.list(limit: 20)84puts result.data85if result.next_page?86 result = result.next_page87 puts result.data88end89```9091```bash92page=$(curl -sS --fail-with-body "https://api.openai.com/v1/agents/sessions?limit=20&order=desc" \93 -H "OpenAI-Beta: agents=v1" \94 -H "Authorization: Bearer $OPENAI_API_KEY")95after=$(printf '%s' "$page" | jq -r 'select(.has_more) | .last_id // empty')9697if [ -n "$after" ]; then98 curl --get "https://api.openai.com/v1/agents/sessions" \99 -H "OpenAI-Beta: agents=v1" \100 -H "Authorization: Bearer $OPENAI_API_KEY" \101 --data-urlencode "after=$after" \102 --data-urlencode "limit=20"103fi104```105106107108109110## Inspect a session111112Retrieve a session to read its status, agent configuration, environment, and `required_actions`. Pass your API client and the conversation's session ID:113114Retrieve a session115116```javascript117// Pass your saved session ID to this helper.118async function retrieveSession(client, sessionId) {119 return client.beta.agents.sessions.retrieve(sessionId);120}121```122123```python124# Pass your saved session ID to this helper.125def retrieve_session(client: OpenAI, session_id: str):126 return client.beta.agents.sessions.retrieve(session_id)127```128129```go130// Pass your saved session ID to this helper.131func retrieveSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSession, error) {132 return client.Beta.Agents.Sessions.Get(ctx, sessionID)133}134```135136```java137// Pass your saved session ID to this helper.138public static AgentSession retrieveSession(OpenAIClient client, String sessionId) {139 return client140 .beta()141 .agents()142 .sessions()143 .retrieve(SessionRetrieveParams.builder().sessionId(sessionId).build());144}145```146147```ruby148# Pass your saved session ID to this helper.149def retrieve_session(client, session_id)150 client.beta.agents.sessions.retrieve(session_id)151end152```153154```bash155curl \156 "https://api.openai.com/v1/agents/sessions/$session_id" \157 -H "OpenAI-Beta: agents=v1" \158 -H "Authorization: Bearer $OPENAI_API_KEY"159```160161162See the [Retrieve session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/retrieve) for the full response schema.163164### Handle required actions165166A session with status `requires_action` needs your application to act before work can continue. When you receive `agent.session.requires_action`, retrieve the session and inspect each entry in `required_actions`:167168- **`function_call`:** Run the function identified by `name` with its `arguments`. Return the result on the same session using the action's `turn_id` and `call_id`. See [Function tools](https://developers.openai.com/api/docs/guides/agents-api/tools/functions#return-the-result).169- **`environment_connection`:** Connect the environment identified by `environment_id`. See [Connect an environment](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted).170171The event tells your application when to check. The retrieved session tells it what to do. After a restart or stream disconnect, retrieve the session to find pending actions. After handling them, continue following events for the turn's outcome.172173174175176For saved messages, tool calls, and turn outcomes, see [Fetch items and turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#fetch-items-and-turns). To identify which agent ran a command, see [Observe delegation](https://developers.openai.com/api/docs/guides/agents-api/multi-agent#observe-delegation).177178## Delete a session179180Delete a session when your application no longer needs it. Deletion removes the session from the API. Physical cleanup may continue asynchronously.181182Delete a session183184```javascript185// Replace the illustrative IDs and URLs below with your own resource values.186import OpenAI from "openai";187188async function deleteSession(client, sessionId) {189 return client.beta.agents.sessions.delete(sessionId);190}191192const result = await deleteSession(new OpenAI(), "sess_123");193console.log(result);194```195196```python197# Replace the illustrative IDs and URLs below with your own resource values.198199from openai import OpenAI200201202def delete_session(client: OpenAI, session_id: str):203 return client.beta.agents.sessions.delete(session_id)204205206if __name__ == "__main__":207 result = delete_session(OpenAI(), "sess_123")208 print(result.to_json())209```210211```go212// Replace the illustrative IDs and URLs below with your own resource values.213package main214215import (216 "context"217 "fmt"218219 "github.com/openai/openai-go/v3"220)221222func deleteSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSessionDeleted, error) {223 return client.Beta.Agents.Sessions.Delete(ctx, sessionID)224}225226func main() {227 client := openai.NewClient()228 result, err := deleteSession(context.Background(), &client, "sess_123")229 if err != nil {230 panic(err)231 }232 fmt.Println(result)233}234```235236```java237// Replace the illustrative IDs and URLs below with your own resource values.238import com.openai.client.OpenAIClient;239import com.openai.client.okhttp.OpenAIOkHttpClient;240import com.openai.models.beta.agents.AgentSessionDeleted;241import com.openai.models.beta.agents.sessions.SessionDeleteParams;242243public final class AgentsApiSessionsDeleteSessionExample {244 public static AgentSessionDeleted deleteSession(OpenAIClient client, String sessionId) {245 return client246 .beta()247 .agents()248 .sessions()249 .delete(SessionDeleteParams.builder().sessionId(sessionId).build());250 }251252 public static void main(String[] args) {253 var result = deleteSession(OpenAIOkHttpClient.fromEnv(), "sess_123");254 System.out.println(result);255 }256}257```258259```ruby260# Replace the illustrative IDs and URLs below with your own resource values.261require "openai"262263def delete_session(client, session_id)264 client.beta.agents.sessions.delete(session_id)265end266267puts delete_session(OpenAI::Client.new, "sess_123")268```269270```bash271curl -X DELETE \272 "https://api.openai.com/v1/agents/sessions/$session_id" \273 -H "OpenAI-Beta: agents=v1" \274 -H "Authorization: Bearer $OPENAI_API_KEY"275```276277278To stop current work and keep the conversation, [cancel the active turn](https://developers.openai.com/api/docs/guides/agents-api/sessions#cancel-an-active-turn). See the [Delete session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/delete) for the deletion response.