Skip to content

Using context outside a graph (Ad‑hoc sessions)

Sometimes you want a fully‑featured NodeContext without constructing a graph—e.g., quick scripts, notebooks, data prep, or admin tasks. AetherGraph exposes an async helper you can import from aethergraph.runtime:

  • open_session(...) – async context manager that yields a temporary, fully wired NodeContext and cleans up afterward.

These sessions are “single‑node” and aren’t scheduled like a graph run, but they provide the same services: context.llm(), context.artifacts(), context.memory(), context.kv(), context.logger(), context.rag, context.mcp(), and any custom services you’ve registered.

Quick Start

from aethergraph.runtime import open_session

# Recommended: context manager form (handles cleanup)
async with open_session(run_id="adhoc-demo", graph_id="adhoc", node_id="adhoc") as context:
    context.logger().info("hello from adhoc")
    txt, _ = await context.llm().chat([
        {"role": "user", "content": "Give me a haiku about photons."}
    ])
    print(txt)

Common parameters

  • run_id: str | None — logical session/run identifier (default: auto‑generated)
  • graph_id: str — namespace label for this session (default: "adhoc")
  • node_id: str — node label within the session (default: "adhoc")
  • **rt_overrides — advanced runtime knobs you can pass through (e.g., max_concurrency, service injections)

Tip: Start your sidecar server (start_server(...)) first if you plan to use external channels, resumable waits, or any service that relies on the sidecar’s wiring.

API Reference

open_session(run_id, graph_id, node_id, **rt_overrides)

Open an ad-hoc session context for advanced or scripting use.

This asynchronous context manager yields a temporary context that mimics a NodeContext without requiring a real graph run. It is intended for advanced scenarios where a lightweight, ephemeral execution environment is needed, such as scripting, testing, or prototyping.

Examples:

Basic usage to open an ad-hoc session: 

async with open_session() as ctx:
    # Use ctx as you would a NodeContext
    ...

Overriding runtime parameters: 

async with open_session(graph_id="mygraph", node_id="customnode", foo="bar") as ctx:
    ...

Parameters:

Name Type Description Default
run_id str | None

Optional unique identifier for the run. If None, a random or default value is used.

 None
graph_id str

Identifier for the graph context. Defaults to "adhoc".

 'adhoc'
node_id str

Identifier for the node context. Defaults to "adhoc".

 'adhoc'
**rt_overrides

Arbitrary keyword arguments to override runtime context parameters.

 {}

Yields:

Name Type Description
NodeContext

An ad-hoc context object suitable for advanced scripting or testing.
Note

This context does not persist state or artifacts beyond its lifetime. Use only for non-production, ephemeral tasks.

build_adhoc_context(run_id, graph_id, node_id, **rt_overrides)

Build an ad-hoc execution context for running a single node outside of a scheduled graph. This function creates a minimal runtime environment suitable for quick, one-off executions, such as testing or interactive exploration. It generates a temporary run and graph context, instantiates an ad-hoc node, and returns a node-specific execution context. Examples: Basic usage with default parameters: 

node_ctx = await build_adhoc_context()
Customizing the run and session IDs: 
node_ctx = await build_adhoc_context(run_id="test-run", session_id="dev-session")
Overriding runtime parameters: 
node_ctx = await build_adhoc_context(max_concurrency=4)
Args: run_id: Optional string to uniquely identify this run. If not provided, a random ID is generated. session_id: Optional string to associate this context with a session. graph_id: Identifier for the graph. Defaults to "adhoc". node_id: Identifier for the node. Defaults to "adhoc". **rt_overrides: Additional runtime overrides, such as max_concurrency. Returns: NodeExecutionContext: The execution context for the ad-hoc node, ready for use.

Notes & gotchas

  • open_session() gives you a real NodeContext bound to a throwaway run/graph/node. Treat it like a normal node.
  • If you rely on external adapters (Slack/Telegram/Web UI) or resumable waits, ensure the sidecar server is running.
  • For long‑lived scripting, prefer open_session(); reach for build_adhoc_context() only when you need total control.
  • Services which are not configured (e.g., RAG, MCP) will raise a clear RuntimeError. Wire them via your runtime config or server startup.