Skip to main content
The session tools family contains a single tool — session_context — but it is the most important call in the entire workflow. It opens a traced research run, attaches the user’s question, and scopes every subsequent tool call the agent makes.

​
session_context

Open a traced research run and attach the user’s question. Every tool call after this one is recorded against the session and streamed live to the web UI via SSE.

​
Arguments

ArgumentTypeRequiredDescription
promptstringYesThe user’s natural-language question or research goal. Stored verbatim and displayed in the web UI.
titlestringNoA short human-readable title for the session. If omitted, one is derived from the first line of prompt.
session_idstringNoAn existing session ID to resume. If omitted, a new session is created.

​
What it does

  1. Creates a new session row (or resumes an existing one) scoped to the caller’s tenant_id.
  2. Stores the prompt verbatim — this is the canonical record of what the human asked.
  3. Returns a session_id that the agent includes in every subsequent tool call (either explicitly or implicitly via the MCP session context).
  4. Begins streaming trace events to the web UI via SSE so the human can watch the research unfold live.

​
Why it’s always called first

No other tool can be called before session_context. The MCP server rejects calls that arrive without an active session — there is no unscoped execution path. This is enforced at the server, not just by the agent’s instructions.
Every Ithaca tool call is traced. Tracing requires a session to attach events to. Without session_context, there is no session, and the server returns an error: 
{
  "error": "no_active_session",
  "message": "Call session_context before calling any other tool."
}
This guarantee is what makes the web UI’s live trace and replay possible — there is never a tool call that happens “outside” a session.

​
Return value

session_context returns a session descriptor:
FieldTypeDescription
session_idstring (UUID)The session identifier. Include this in subsequent calls.
tenant_idstring (UUID)The tenant the session belongs to. Echoed for transparency.
titlestringThe resolved session title.
created_atstring (ISO 8601)When the session was opened.
statusstringopen — the session is active and accepting tool calls.
trace_streamstring (URL)The SSE endpoint the web UI subscribes to.

​
Example call

{
  "prompt": "Research NVDA — pull price history, screen peers, check fundamentals and insider activity, propose a momentum strategy, and backtest it.",
  "title": "NVDA momentum research"
}

​
Example response

{
  "session_id": "sess_01HQKX2J3K4M5N6P7R8S9T0V1W",
  "tenant_id": "tnt_01HQKX2J3K4M5N6P7R8S9T0V1X",
  "title": "NVDA momentum research",
  "created_at": "2025-01-15T14:32:07.891Z",
  "status": "open",
  "trace_stream": "https://app.doomberg.me/api/sessions/sess_01HQKX2J3K4M5N6P7R8S9T0V1W/events/stream"
}

​
Resuming a session

Pass session_id to resume an existing session instead of creating a new one. This is useful when an agent is re-invoked to continue research from a previous turn: 
{
  "prompt": "Now compare the NVDA strategy against AMD using the same parameters.",
  "session_id": "sess_01HQKX2J3K4M5N6P7R8S9T0V1W"
}
The new prompt is appended to the session’s prompt history. The session’s status remains open and the trace stream continues from where it left off.
  • open — the session is active and accepting tool calls.
  • closed — the agent called session_close (or the session timed out). No further tool calls are accepted. The trace is still readable and replayable from the web UI.
  • archived — the session has been moved to cold storage after the retention window. Metadata is still queryable; raw trace events may take longer to load.
The human can close a session from the web UI at any time. When a session is closed, in-flight tool calls are allowed to finish but no new ones are accepted.