Agents
P2 · Advanced
Session Storage for Agents
Give AI agents persistent context, conversation history, checkpoints, and execution state.
A session is the memory of a piece of agent work: who it is for, what has been said, and which checkpoint is safe to return to.
Paths in the tables are relative to https://api.ultrahost.com/v1/projects/{projectId}. Pagination, idempotency, and errors are described in Conventions.
Create
| SDK | REST | Description |
|---|---|---|
sessions.create(config) | POST /sessions | Create a session |
sessions.get(id) | GET /sessions/{id} | Retrieve a session |
sessions.list(options?) | GET /sessions | List sessions |
sessions.update(id, data) | PATCH /sessions/{id} | Update session metadata |
sessions.delete(id) | DELETE /sessions/{id} | Delete a session |
sessions.clear(id) | POST /sessions/{id}/clear | Clear stored context |
sessions.fork(id) | POST /sessions/{id}/fork | Branch a session |
const session = await ultrahost.sessions.create({
agent: "research-assistant",
userId: user.id
});fork copies a session so a second line of work can continue without rewriting the original.
Configure
clear drops stored context and keeps the session id. delete removes the session.
Concurrent agents use optimistic concurrency on state. Updates carry a revision, or an equivalent token, and fail when the revision is stale. A lost update does not overwrite a newer one.
Checkpoints are the restore points. Create them at boundaries the agent can safely resume from, not after every token.
Use
| SDK | REST | Description |
|---|---|---|
sessions.getState(id) | GET /sessions/{id}/state | Current state |
sessions.setState(id, state) | PUT /sessions/{id}/state | Replace state |
sessions.patchState(id, patch) | PATCH /sessions/{id}/state | Partial state update |
sessions.appendMessage(id, message) | POST /sessions/{id}/messages | Append a message |
sessions.getMessages(id, options?) | GET /sessions/{id}/messages | Conversation history |
sessions.checkpoint(id) | POST /sessions/{id}/checkpoints | Save a checkpoint |
sessions.restore(id, checkpointId) | POST /sessions/{id}/restore | Restore a checkpoint |
sessions.listCheckpoints(id) | GET /sessions/{id}/checkpoints | List checkpoints |
await ultrahost.sessions.appendMessage(session.id, {
role: "user",
content: "Research competitors in the CRM market"
});
await ultrahost.sessions.checkpoint(session.id);useAgentSession(id) is the React hook for reading that state. Message history is cursor-paginated.