> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# One server, many conversations

> One AgentClient per server, one retained AgentSession per conversation, continued later with runAsync()

> [!WARNING]
>
> **On main, not yet released — 0.32.1-SNAPSHOT, checked against agent-client main f89fc6b5.** This tutorial uses the asynchronous lifecycle API built from `main` (at or after commit `4de205db`). None of it is in 0.32.0. Snapshot content changes as `main` moves, so name the `main` commit you built against.

> [accordion] Add the snapshot repository
>
> Resolve `0.32.1-SNAPSHOT` from the Central snapshot repository, with snapshots enabled:
>
> ```xml theme={null}
> <repositories>
>     <repository>
>         <id>central-snapshots</id>
>         <url>https://central.sonatype.com/repository/maven-snapshots/</url>
>         <releases><enabled>false</enabled></releases>
>         <snapshots><enabled>true</enabled></snapshots>
>     </repository>
> </repositories>
>
> <dependencies>
>     <dependency>
>         <groupId>io.github.markpollack</groupId>
>         <artifactId>agent-client-core</artifactId>
>         <version>0.32.1-SNAPSHOT</version>
>     </dependency>
>     <dependency>
>         <groupId>io.github.markpollack</groupId>
>         <artifactId>agent-client-claude</artifactId>
>         <version>0.32.1-SNAPSHOT</version>
>     </dependency>
> </dependencies>
> ```
>
> `agent-client-claude` supplies `ClaudeClientProvider`, the Claude Code lifecycle provider these examples run against.
> See [Using development snapshots from main](https://lab.pollack.ai/docs/development-snapshots.md) for pinning one build and reading its provenance.

> [card] [Source on GitHub main](https://github.com/markpollack/agent-client/blob/main/docs/examples/tutorials/ConversationServer.java)
>
> `docs/examples/tutorials/ConversationServer.java`, compiled and run offline by the agent-client build

A server process creates one `AgentClient` at startup and closes it at shutdown. HTTP requests never build their own
client. Each conversation is a retained `AgentSession`. The application keeps the map from its own conversation id to
the session, so a later request can find the conversation and continue it.

```java theme={null}
/** Create once at startup. The Client runs each execution on its own virtual thread. */
public ConversationServer(AgentExecutionProvider provider) {
    this.client = AgentClient.builder(provider).defaultTimeout(Duration.ofMinutes(5)).build();
}
```

The Client runs each execution on its own virtual thread, so there is no executor to configure. Start a conversation
in its workspace and remember its id:

```java theme={null}
/** Starts a conversation in its own workspace and returns its id. */
public String start(Path workspace) {
    AgentSession conversation = this.client.sessions().create(spec -> spec.workingDirectory(workspace));
    this.conversations.put(conversation.id(), conversation);
    return conversation.id();
}
```

A later HTTP request names the conversation. Look it up and continue it with `runAsync()`; the turn joins the same
history. An id the server does not know is an error, never a silent new conversation:

```java theme={null}
/**
 * A later HTTP request: find the conversation by id and continue it. An unknown id is an
 * error; it never silently becomes a new conversation.
 */
public AgentExecution send(String conversationId, String text) {
    AgentSession conversation = this.conversations.get(conversationId);
    if (conversation == null)
        throw new NoSuchElementException("No conversation " + conversationId);
    return conversation.goal(text).runAsync();
}
```

At shutdown, closing the Client closes every conversation it still owns:

```java theme={null}
public void close() {
    this.client.close();
}
```

`runAsync()` returns at once with an `AgentExecution`. Call `result()` to wait for the answer, or hand the execution to
whatever streams the reply back. One conversation runs one turn at a time; for several users in one conversation, see
[the shared conversation tutorial](https://lab.pollack.ai/docs/agent-client/tutorial/async/02-shared-conversation-arrival-order.md).

The full class is [ConversationServer.java](https://github.com/markpollack/agent-client/blob/main/docs/examples/tutorials/ConversationServer.java). Its `main` runs it against
Claude Code with `ClaudeClientProvider`.

The build compiles this tutorial from `docs/examples/tutorials` and runs it against `OfflineProvider`, an offline
stand-in that makes no model call (`agent-client-tutorials`, `ConversationServerTest`). A live Claude Code run is not part of the build.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.