Module 03: Sessions

Understanding session creation and lifecycle in ACP.

What You’ll Learn

Creating sessions with NewSessionRequest
Working directory context and context documents
Multiple independent sessions

How Sessions Work

Sessions are workspaces for conversations. Each session has a unique ID assigned by the agent, a working directory context, and its own conversation history. Multiple sessions on the same connection are fully independent.

The Code

After initializing (Module 01/02), the next step is creating a session. NewSessionRequest takes a working directory path and an optional list of MCP server configs. The agent returns a session ID that you use for all subsequent prompts:

// Create a session with working directory context
var session = client.newSession(
    new NewSessionRequest("/workspace", List.of()));

System.out.println("Session ID: " + session.sessionId());
// Output: Session ID: 53d1a1ee-c7eb-4500-b25c-7bc2fdffa0e4

You can create multiple sessions on the same connection. Each maintains its own conversation history — prompts in one session don’t affect the other:

var session1 = client.newSession(new NewSessionRequest("/project-a", List.of()));
var session2 = client.newSession(new NewSessionRequest("/project-b", List.of()));

// Prompts in session1 don't affect session2
client.prompt(new PromptRequest(session1.sessionId(),
    List.of(new TextContent("Analyze this project"))));

Source Code

View on GitHub

Running the Example

export GEMINI_API_KEY=your-key-here
./mvnw exec:java -pl module-03-sessions

Next Module

Module 04: Prompts — prompt requests and response handling in depth.

02 protocol basics 04 prompts

Projects

AgentWorks

Agento

Supporting Projects

Migration

03 sessions

Module 03: Sessions

What You’ll Learn

How Sessions Work

The Code

Source Code

Running the Example

Next Module

​Module 03: Sessions

​What You’ll Learn

​How Sessions Work

​The Code

​Source Code

​Running the Example

​Next Module

Module 03: Sessions

What You’ll Learn

How Sessions Work

The Code

Source Code

Running the Example

Next Module