olbrain-python-sdk 0.3.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

olbrain/AGENTS.md

@@ -7,9 +7,20 @@ taken from the source. If it disagrees with the web docs, this file is right.
 Find it from Python with:
 `python -c "import olbrain, os; print(os.path.join(os.path.dirname(olbrain.__file__), 'AGENTS.md'))"`
 
-The Python SDK covers **conversational agents** only (`AgentClient`). Workflow
-runs, approvals and research agents are available only in the JavaScript SDK
-(`@olbrain/js-sdk`, class `Olbrain`).
+## Pick the right client
+
+| You want to… | Use | Auth |
+|---|---|---|
+| Chat with a conversational agent (send a message, get a reply) | `AgentClient` | `api_key="ak_…"` (the only kind issued today; `sk_live_`, `org_live_`, `sk_` and `org_` still pass validation) |
+| Trigger workflow agents, read/control runs, resolve approvals | `Olbrain` | `api_key="ak_…"` **or** `get_id_token` (Olbrain sign-in) |
+| Drive a research agent (sessions, streamed turns, plans, reports) | `Olbrain.research` | `get_id_token` only. An `ak_` key gets `NotFoundError` (`agent_not_found`) |
+
+These are two separate HTTP clients with different error rules. Both default
+to `https://webhook.olbrain.com`. The JavaScript SDK (`@olbrain/js-sdk`) has
+the same two clients plus a browser `ChatWidget`.
+
+Keep the `ak_` key on your server (an environment variable such as
+`OLBRAIN_API_KEY`). Never send it to a browser.
 
 ## Install and import
 
@@ -18,10 +29,14 @@ pip install olbrain-python-sdk   # import name: olbrain. Requires Python 3.7+ an
 ```
 
 ```python
-from olbrain import AgentClient, ChatResponse, OlbrainError
+from olbrain import AgentClient, Olbrain, OlbrainError
 ```
 
-## Quick start
+Both clients are synchronous and use `requests`.
+
+---
+
+## 1. `AgentClient` — conversational agents
 
 ```python
 import os
@@ -36,57 +51,37 @@ with AgentClient(agent_id="your-agent-id", api_key=os.environ["OLBRAIN_API_KEY"]
         print("agent error:", reply.error)
 ```
 
-The client is synchronous and uses `requests`.
-
-## `AgentClient(agent_id, api_key, agent_url=None)`
+### `AgentClient(agent_id, api_key, agent_url=None)`
 
 - `agent_id`: required. An empty value raises `ValueError`.
-- `api_key`: must start with `sk_live_`, `org_live_`, `sk_` or `org_`, or the
-  constructor raises `ValueError`. `ak_` keys are **not** accepted here.
-- `agent_url`: optional. Defaults to `https://olbrain-agent-cloud-768934887465.us-central1.run.app`.
+- `api_key`: must start with `ak_`, `sk_live_`, `org_live_`, `sk_` or `org_`,
+  or the constructor raises `ValueError`.
+- `agent_url`: optional. Defaults to `https://webhook.olbrain.com`.
 
-Every call is a `POST {agent_url}/api/agent/webhook` with headers
-`Authorization: Bearer <api_key>` and `X-Agent-ID: <agent_id>`. The client is a
-context manager, and `__exit__` calls `close()`.
+Chat calls are `POST {agent_url}/api/agents/webhook/{agent_id}` with
+`Authorization: Bearer <api_key>`. Session reads are
+`GET {agent_url}/api/agents/{agent_id}/sessions/{session_id}[/messages]`. The
+client is a context manager, and `__exit__` calls `close()`.
 
 ### Methods
 
 | Method | Returns | Notes |
 |---|---|---|
-| `create_session(on_message=None, title=None, user_id=None, metadata=None, mode="production", description=None)` | `str` session id | Sends `title` (default `"New Session"`) to the agent **as the first message**. `mode` must be `"development"`, `"testing"` or `"production"`, otherwise `ValueError`. `description` is stored as `metadata["session_description"]`. If you pass `on_message`, it also calls `listen()`. Timeout 30 s. |
+| `create_session(on_message=None, title=None, user_id=None, metadata=None, mode="production", description=None)` | `str` session id | Sends `title` (default `"New Session"`) to the agent **as the first message**. `mode` must be `"development"`, `"testing"` or `"production"`, otherwise `ValueError`, but it is not sent: the API always serves the published agent. `description` is stored as `metadata["session_description"]`. If you pass `on_message`, it also calls `listen()`. Timeout 30 s. |
 | `send_and_wait(session_id, message, user_id=None, metadata=None, model=None, timeout=120)` | `ChatResponse` | Waits for the reply. `timeout` is in **seconds**. `model` overrides the agent's model. Empty or whitespace-only messages raise `ValueError`. |
 | `send(session_id, message, user_id=None, metadata=None, model=None, mode="production")` | `dict` (raw JSON) | Same request, but returns the raw response dict (`response`, `token_usage`, `success`, …). It still blocks, with a 120 s timeout. |
-| `listen(session_id, on_message)` | `None` | Starts a background daemon thread that reads SSE from `GET {agent_url}/sessions/{id}/stream`. It reconnects with backoff from 5 s up to 60 s. Calling it again for the same session does nothing. |
+| `listen(session_id, on_message)` | `None` | Starts a background daemon thread that polls the session's messages every 2 s and calls `on_message` once per **new** message (messages already there are skipped). Calling it again for the same session does nothing. |
 | `run()` | `None` | Blocks until Ctrl+C, then calls `close()`. Use it to keep a script alive for `listen` callbacks. |
-| `close()` | `None` | Stops all streams. |
-| `get_session(session_id)` | `SessionInfo` | Needs backend support (webhook `action: get_session_info`). |
-| `update_session(session_id, title=None, metadata=None, status=None)` | `SessionInfo` | `status` must be `"active"` or `"archived"`. |
-| `delete_session(session_id)` | `dict` | Also stops that session's stream. |
-| `get_session_stats(session_id)` | `dict` | |
-| `get_messages(session_id, limit=20, offset=0)` | `dict` | The messages list and pagination info, as the backend returns them. |
-
-The five session-management methods (`get_session` through `get_messages`)
-depend on webhook `action`s that not every backend implements. They raise if
-the backend refuses. Only `create_session`, `send_and_wait` and `send` are
-guaranteed to work.
+| `close()` | `None` | Stops all listeners. |
+| `get_session(session_id)` | `SessionInfo` | `SessionNotFoundError` if it doesn't exist (or belongs to another agent). |
+| `get_session_stats(session_id)` | `dict` | `message_count`, `token_usage`, `cost`, `created_at`, `last_message_at`. |
+| `get_messages(session_id, limit=20, offset=0)` | `dict` | `{"messages": [...], "limit", "offset"}`, oldest first; `limit` at most 200. |
+| `update_session(...)`, `delete_session(...)` | — | Always raise `OlbrainError`: the API has no endpoint for them. |
 
-### Streaming callback
+`on_message` gets each message as a raw dict (`role`, `content`, …). It runs
+on the listener thread, so keep it fast and don't raise from it.
 
-`on_message` gets the **raw dict** from each SSE frame that has a `content`
-key. Frames whose `type` is `ping` or `connected` are skipped. The callback
-runs on the stream thread, so keep it fast and don't raise from it.
-
-```python
-def on_message(msg: dict):
-    print(f"{msg.get('role')}: {msg['content']}")
-
-client = AgentClient(agent_id="…", api_key="sk_live_…")
-sid = client.create_session(on_message=on_message, title="Streaming chat")
-client.send(sid, "Tell me a story")
-client.run()  # blocks; Ctrl+C to stop
-```
-
-## Data classes (`olbrain.session`, re-exported from `olbrain`)
+### Data classes (`olbrain.session`, re-exported from `olbrain`)
 
 ```python
 @dataclass
@@ -126,12 +121,9 @@ class SessionInfo:
 `reply.success` too. A 200 response can carry `success=False` and an `error`.
 
 Avoid the exported `Message` and `Session` classes. Nothing in the client
-returns them, and `Session.get_stats()` always falls back to local data.
-
-## Errors (`olbrain.exceptions`)
+returns them.
 
-All of them subclass `OlbrainError`, which has `.message`, `.error_code` and
-`.details`.
+### Errors (`AgentClient`)
 
 | Condition | Raised |
 |---|---|
@@ -143,25 +135,130 @@ All of them subclass `OlbrainError`, which has `.message`, `.error_code` and
 | Any other non-200 (403, 5xx…) | `OlbrainError("Failed to <operation>: <status> - <detail>")` |
 | Connection error or timeout | `NetworkError` |
 
+---
+
+## 2. `Olbrain` — workflow agents, runs, approvals
+
+```python
+olbrain = Olbrain(api_key=os.environ["OLBRAIN_API_KEY"])           # server / script
+# olbrain = Olbrain(get_id_token=lambda: current_user_id_token())   # signed-in Olbrain user (Firebase ID token)
+```
+
+`Olbrain(api_key=None, get_id_token=None, base_url=None, timeout=30)`:
+`api_key` must start `ak_`; `get_id_token` is a callable returning the
+token and is called before **every** request; `base_url` defaults to
+`https://webhook.olbrain.com`; `timeout` is in seconds. Give **exactly one** of
+`api_key` or `get_id_token`, or the constructor raises `ValidationError`.
+
+Every method takes the agent id first and returns the API's JSON (snake_case
+dicts and lists).
+
+| Method | HTTP | Returns |
+|---|---|---|
+| `workflows.run(agent_id, payload=None, variables=None)` | `POST /api/workflows/{agent_id}/trigger` | `{"run_id", "status"}` |
+| `runs.list(agent_id, status=None, limit=None)` | `GET /api/agents/{agent_id}/runs` | list of runs |
+| `runs.get(agent_id, run_id)` | `GET …/runs/{run_id}` | run |
+| `runs.cancel / pause / retry / resume(agent_id, run_id)` | `POST …/runs/{run_id}/{verb}` | dict |
+| `approvals.list(agent_id, run_id)` | `GET …/runs/{run_id}/approvals` | list of approvals |
+| `approvals.resolve(agent_id, run_id, exception_id, resolution, modified_data=None)` | `POST …/approvals/resolve` | `{"exception_id", "resolution", "all_resolved", "resumed"}` |
+
+A run has `run_id`, `status`, and optionally `progress_percent`, `started_at`,
+`completed_at`, `duration_seconds`, `error` and `summary`
+(`total_processed`, `successful`, `failed`, `exceptions`, `skipped`). An
+approval has `exception_id`, `step_id`, `item_id`, `data`, `error`,
+`requires_human_review` and `blocking`. `resolution` is `"approved"`,
+`"rejected"` or `"modified"`; send `modified_data` only with `"modified"`.
+
+There is no SDK helper for waiting on a run, so poll `runs.get` yourself:
+
 ```python
-from olbrain import AgentClient, AuthenticationError, RateLimitError, NetworkError, OlbrainError
-import time
-
-def ask(client, sid, text, tries=3):
-    for i in range(tries):
-        try:
-            return client.send_and_wait(sid, text)
-        except RateLimitError as e:
-            time.sleep(e.retry_after or 2 ** i)
-        except NetworkError:
-            time.sleep(2 ** i)
-    raise OlbrainError("gave up")
+import os, time
+from olbrain import Olbrain
+
+olbrain = Olbrain(api_key=os.environ["OLBRAIN_API_KEY"])
+run_id = olbrain.workflows.run(agent_id, payload={"url": url})["run_id"]
+DONE = {"completed", "failed", "canceled", "cancelled"}
+run = olbrain.runs.get(agent_id, run_id)
+while run["status"] not in DONE:
+    for a in olbrain.approvals.list(agent_id, run_id):
+        olbrain.approvals.resolve(agent_id, run_id, a["exception_id"], "approved")
+    time.sleep(3)
+    run = olbrain.runs.get(agent_id, run_id)
 ```
 
-`ValidationError` and `StreamingError` are exported, but the client never
-raises them.
+The terminal status strings in that loop are an assumption. Check the values
+your agent actually returns.
+
+### Errors (`Olbrain`, including `research`)
+
+The error code and message come from the response body: `{error:{code,message}}`
+or FastAPI's `{detail}`.
+
+| Condition | Raised |
+|---|---|
+| code is `insufficient_funds`, `credit_limit_exceeded`, `subscription_suspended`, `subscription_inactive` or `billing_unavailable` (any status) | `BillingError` (`.status`, `.code`) |
+| 401 | `AuthenticationError` |
+| 404 | `NotFoundError` (`.status = 404`, `.code`, e.g. `agent_not_found`) |
+| 429 | `RateLimitError` (`.retry_after` seconds from the `Retry-After` header, or `None`) |
+| any other non-2xx (403, 409, 422, 5xx…) | `ApiError` (`.status`, `.code`, `.message`, `.detail` = raw `detail`) |
+| connection failure, timeout, or a dropped stream | `NetworkError` |
+
+`BillingError` and `NotFoundError` subclass `ApiError`, and every error class
+subclasses `OlbrainError`, so put the narrower `except` clauses first.
+
+---
+
+## 3. `Olbrain.research` — research agents (sign-ins only)
+
+```python
+olbrain = Olbrain(get_id_token=lambda: user_id_token)
+r = olbrain.research
+```
+
+All paths sit under `/api/agents/{agent_id}/research`. The agent must be a
+research agent that is bound to a screen in the user's org. Payloads are
+returned untyped (dicts and lists) because their shape belongs to the
+research-runtime service.
+
+| Method | |
+|---|---|
+| `sessions.create(agent_id)` | session (has `session_id`) |
+| `sessions.list(agent_id, include_archived=False)`, `sessions.get / delete(agent_id, session_id)` | |
+| `sessions.patch(agent_id, session_id, patch)` | partial session fields, passed through |
+| `sessions.models(agent_id, session_id)` | available models |
+| `sessions.set_model / set_review_model(agent_id, session_id, model)` | `None` resets to the default |
+| `sessions.stream_message(agent_id, session_id, content, attachments=None, effort=None, escalates_run_id=None, command=None, target_run_id=None)` | generator of frames |
+| `plans.approve(agent_id, session_id, message_id, body=None)`, `plans.approve_by_id(agent_id, session_id, plan_id, body=None)` | |
+| `attachments.add(agent_id, session_id, files)` | multipart upload of `(filename, file or bytes[, content_type])` tuples; returns refs to pass as `attachments` |
+| `attachments.upload_url(agent_id, session_id, storage_path)` | `{"url"}` |
+| `runs.cancel / retry(agent_id, run_id)`, `runs.active_job(agent_id, run_id)` (or `None`), `runs.resolve_claims(agent_id, run_id, resolutions)` | |
+| `reports.get(agent_id, run_id, version=None)`, `reports.artifact_url(agent_id, run_id, profile_id, fmt)`, `reports.evidence(agent_id, run_id)` | |
+| `reports.share.get / revoke(agent_id, run_id)`, `reports.share.set(agent_id, run_id, visibility)` | |
+| `review.get(agent_id, run_id)`; `review.run(agent_id, run_id)`, `review.apply(agent_id, run_id, finding_ids)` | the last two block, up to 600 s |
+| `review.stream(agent_id, run_id)`, `review.stream_apply(agent_id, run_id, finding_ids)` | generators of frames |
+| `templates.versions(agent_id)` | |
+| `messages.older(agent_id, session_id, before_ts)` | one page of older messages, oldest first |
+
+Stream frames come straight from research-runtime, unchanged: `{"type": "text_delta", "text"}`,
+`{"type": "tool_use_start", …}`, `{"type": "complete", …}` and `{"type": "error", …}`.
+The request is sent when you start iterating, and it can wait up to 600 s for
+its first frame while the agent searches. To cancel, stop iterating (`break`,
+or `.close()` the generator); the connection is closed.
+
+```python
+for ev in r.sessions.stream_message(agent_id, sid, "Size the Indian EV charger market"):
+    if ev.get("type") == "text_delta":
+        print(ev["text"], end="", flush=True)
+    elif ev.get("type") == "error":
+        raise RuntimeError(ev.get("message", "research error"))
+```
+
+The JavaScript SDK's `live.*` polling subscriptions are not in Python. Poll
+`sessions.get` / `reports.get` yourself.
+
+---
 
 ## Logging
 
-The SDK logs through `logging.getLogger("olbrain")`. Turn on
-`logging.basicConfig(level=logging.DEBUG)` to see requests and stream events.
+`AgentClient` logs through `logging.getLogger("olbrain")`. Turn on
+`logging.basicConfig(level=logging.DEBUG)` to see requests and listener events.

olbrain/__init__.py

@@ -1,6 +1,6 @@
 """
 Olbrain Python SDK
-Simple client for Olbrain AI agents with real-time message streaming
+AgentClient for conversational agents; Olbrain for workflow runs, approvals and research agents
 
 Full offline API reference: AGENTS.md next to this file.
 
@@ -23,6 +23,7 @@ Example:
 """
 
 from .client import AgentClient
+from .olbrain import Olbrain
 from .session import ChatResponse, SessionInfo, TokenUsage, Message, Session
 from .exceptions import (
     OlbrainError,
@@ -32,16 +33,20 @@ from .exceptions import (
     SessionNotFoundError,
     RateLimitError,
     ValidationError,
-    StreamingError
+    StreamingError,
+    ApiError,
+    NotFoundError,
+    BillingError,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.5.0"
 __author__ = "Olbrain Team"
 __email__ = "support@olbrain.com"
 
 __all__ = [
     # Main client
     'AgentClient',
+    'Olbrain',
     # Data classes
     'ChatResponse',
     'SessionInfo',
@@ -56,5 +61,8 @@ __all__ = [
     'SessionNotFoundError',
     'RateLimitError',
     'ValidationError',
-    'StreamingError'
+    'StreamingError',
+    'ApiError',
+    'NotFoundError',
+    'BillingError',
 ]

olbrain/client.py

@@ -12,6 +12,7 @@ FIXES:
 import requests
 import logging
 import time
+from urllib.parse import quote
 from typing import Callable, Optional, Dict, Any, List
 
 logger = logging.getLogger(__name__)
@@ -148,7 +149,7 @@ class AgentClient:
 
         Args:
             agent_id: Agent identifier
-            api_key: API key (must start with 'sk_live_', 'org_live_', 'sk_', or 'org_')
+            api_key: Access key (ak_…); 'sk_live_', 'org_live_', 'sk_' and 'org_' are also accepted
             agent_url: Optional agent URL (auto-constructed if not provided)
 
         Raises:
@@ -157,10 +158,10 @@ class AgentClient:
         if not agent_id:
             raise ValueError("agent_id is required")
 
-        valid_prefixes = ('sk_live_', 'org_live_', 'sk_', 'org_')
+        valid_prefixes = ('ak_', 'sk_live_', 'org_live_', 'sk_', 'org_')
         if not api_key or not api_key.startswith(valid_prefixes):
             raise ValueError(
-                "Invalid API key - must start with 'sk_live_', 'org_live_', 'sk_', or 'org_'"
+                "Invalid API key - must start with 'ak_', 'sk_live_', 'org_live_', 'sk_', or 'org_'"
             )
 
         self.agent_id = agent_id
@@ -170,8 +171,8 @@ class AgentClient:
         if agent_url:
             self.agent_url = agent_url.rstrip('/')
         else:
-            # Use Olbrain shared agent URL
-            self.agent_url = "https://olbrain-agent-cloud-768934887465.us-central1.run.app"
+            # The Olbrain API. The old run.app host this SDK defaulted to no longer exists.
+            self.agent_url = "https://webhook.olbrain.com"
 
         self._streams = {}  # session_id -> MessageStream
         self._running = False
@@ -198,7 +199,7 @@ class AgentClient:
             title: Optional title for the session
             user_id: Optional user identifier for tracking
             metadata: Optional metadata dict
-            mode: Session mode - 'development', 'testing', or 'production' (default)
+            mode: Kept for compatibility and not sent: the Olbrain API always serves the published agent
             description: Optional session description
 
         Returns:
@@ -219,8 +220,7 @@ class AgentClient:
 
             payload = {
                 'message': title or "New Session",
-                'response_mode': 'sync',
-                'mode': mode
+                'response_mode': 'sync'
             }
             if user_id:
                 payload['user_id'] = user_id
@@ -229,7 +229,7 @@ class AgentClient:
 
             # Create session via webhook endpoint
             response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
+                self._chat_url(),
                 headers={
                     'Authorization': f'Bearer {self.api_key}',
                     'Content-Type': 'application/json',
@@ -278,7 +278,7 @@ class AgentClient:
             user_id: Optional user identifier
             metadata: Optional message metadata
             model: Optional model override (e.g., 'gpt-4', 'claude-3-opus')
-            mode: Session mode - 'development', 'testing', or 'production'
+            mode: Kept for compatibility and not sent: the Olbrain API always serves the published agent
 
         Returns:
             Response dict with success, response, token_usage, etc.
@@ -294,8 +294,7 @@ class AgentClient:
             payload = {
                 'session_id': session_id,
                 'message': message.strip(),
-                'response_mode': 'sync',
-                'mode': mode
+                'response_mode': 'sync'
             }
             if user_id:
                 payload['user_id'] = user_id
@@ -305,7 +304,7 @@ class AgentClient:
                 payload['model'] = model
 
             response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
+                self._chat_url(),
                 headers={
                     'Authorization': f'Bearer {self.api_key}',
                     'Content-Type': 'application/json',
@@ -378,7 +377,7 @@ class AgentClient:
                 payload['model'] = model
 
             response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",  # FIXED: was /sessions/{id}/messages
+                self._chat_url(),
                 headers={
                     'Authorization': f'Bearer {self.api_key}',
                     'Content-Type': 'application/json',
@@ -489,209 +488,52 @@ class AgentClient:
         """
         Get session details.
 
-        FIXED: Uses webhook to query session info instead of /sessions/{id}
-
-        Args:
-            session_id: Session identifier
-
-        Returns:
-            SessionInfo with session details
-
         Raises:
-            SessionNotFoundError: If session doesn't exist
-            OlbrainError: If request fails
+            SessionNotFoundError: If the session doesn't exist (or belongs to another agent)
         """
-        try:
-            # Query session info via webhook
-            response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
-                headers={
-                    'Authorization': f'Bearer {self.api_key}',
-                    'Content-Type': 'application/json',
-                    **({'X-Agent-ID': self.agent_id} if self.agent_id else {})
-                },
-                json={
-                    'session_id': session_id,
-                    'action': 'get_session_info'
-                },
-                timeout=30
-            )
-
-            self._handle_response_errors(response, "get session")
+        return SessionInfo.from_dict(self._get(self._session_url(session_id), "get session"))
 
-            data = response.json()
-            return SessionInfo.from_dict(data)
-
-        except requests.exceptions.RequestException as e:
-            raise NetworkError(f"Network error getting session: {e}")
-
-    def update_session(
-        self,
-        session_id: str,
-        title: str = None,
-        metadata: Dict[str, Any] = None,
-        status: str = None
-    ) -> SessionInfo:
-        """
-        Update session details via webhook.
-
-        Args:
-            session_id: Session identifier
-            title: New session title (optional)
-            metadata: New metadata dict (optional)
-            status: New status - 'active' or 'archived' (optional)
-
-        Returns:
-            Updated SessionInfo
-        """
-        try:
-            update_data = {}
-            if title is not None:
-                update_data['title'] = title
-            if metadata is not None:
-                update_data['metadata'] = metadata
-            if status is not None:
-                if status not in ['active', 'archived']:
-                    raise ValueError("status must be 'active' or 'archived'")
-                update_data['status'] = status
-
-            response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
-                headers={
-                    'Authorization': f'Bearer {self.api_key}',
-                    'Content-Type': 'application/json',
-                    **({'X-Agent-ID': self.agent_id} if self.agent_id else {})
-                },
-                json={
-                    'session_id': session_id,
-                    'action': 'update_session',
-                    **update_data
-                },
-                timeout=30
-            )
-
-            self._handle_response_errors(response, "update session")
-
-            data = response.json()
-            return SessionInfo.from_dict(data)
-
-        except requests.exceptions.RequestException as e:
-            raise NetworkError(f"Network error updating session: {e}")
+    def update_session(self, session_id: str, title: str = None, metadata: Dict[str, Any] = None,
+                       status: str = None) -> SessionInfo:
+        """Not supported: the Olbrain API has no endpoint to change a session."""
+        raise OlbrainError("update_session is not supported: the Olbrain API has no endpoint to change a session")
 
     def delete_session(self, session_id: str) -> Dict[str, Any]:
-        """
-        Archive/delete a session via webhook.
-
-        Args:
-            session_id: Session identifier
-
-        Returns:
-            Dict with success status
-        """
-        try:
-            # Stop listening if we have an active stream
-            if session_id in self._streams:
-                self._streams[session_id].stop()
-                del self._streams[session_id]
-
-            response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
-                headers={
-                    'Authorization': f'Bearer {self.api_key}',
-                    'Content-Type': 'application/json',
-                    **({'X-Agent-ID': self.agent_id} if self.agent_id else {})
-                },
-                json={
-                    'session_id': session_id,
-                    'action': 'delete_session'
-                },
-                timeout=30
-            )
-
-            self._handle_response_errors(response, "delete session")
-
-            return response.json()
-
-        except requests.exceptions.RequestException as e:
-            raise NetworkError(f"Network error deleting session: {e}")
+        """Not supported: the Olbrain API has no endpoint to delete a session."""
+        raise OlbrainError("delete_session is not supported: the Olbrain API has no endpoint to delete a session")
 
     def get_session_stats(self, session_id: str) -> Dict[str, Any]:
         """
-        Get session statistics via webhook.
-
-        Args:
-            session_id: Session identifier
-
-        Returns:
-            Dict with session statistics
+        Session statistics: message_count, token_usage, cost, created_at and last_message_at.
         """
-        try:
-            response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
-                headers={
-                    'Authorization': f'Bearer {self.api_key}',
-                    'Content-Type': 'application/json',
-                    **({'X-Agent-ID': self.agent_id} if self.agent_id else {})
-                },
-                json={
-                    'session_id': session_id,
-                    'action': 'get_stats'
-                },
-                timeout=30
-            )
-
-            self._handle_response_errors(response, "get session stats")
-
-            return response.json()
+        return self._get(self._session_url(session_id), "get session stats")
 
-        except requests.exceptions.RequestException as e:
-            raise NetworkError(f"Network error getting session stats: {e}")
-
-    def get_messages(
-        self,
-        session_id: str,
-        limit: int = 20,
-        offset: int = 0
-    ) -> Dict[str, Any]:
+    def get_messages(self, session_id: str, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
         """
-        Get message history via webhook.
-
-        Args:
-            session_id: Session identifier
-            limit: Maximum messages to return (default: 20)
-            offset: Number of messages to skip (default: 0)
-
-        Returns:
-            Dict with messages list and pagination info
+        Message history, oldest first: {"messages": [...], "limit", "offset"} (limit at most 200).
         """
-        try:
-            response = requests.post(
-                f"{self.agent_url}/api/agent/webhook",
-                headers={
-                    'Authorization': f'Bearer {self.api_key}',
-                    'Content-Type': 'application/json',
-                    **({'X-Agent-ID': self.agent_id} if self.agent_id else {})
-                },
-                json={
-                    'session_id': session_id,
-                    'action': 'get_messages',
-                    'limit': limit,
-                    'offset': offset
-                },
-                timeout=30
-            )
-
-            self._handle_response_errors(response, "get messages")
-
-            return response.json()
-
-        except requests.exceptions.RequestException as e:
-            raise NetworkError(f"Network error getting messages: {e}")
+        return self._get(f"{self._session_url(session_id)}/messages", "get messages",
+                         params={'limit': limit, 'offset': offset})
 
     # -------------------------------------------------------------------------
     # Helper Methods
     # -------------------------------------------------------------------------
 
+    def _chat_url(self) -> str:
+        return f"{self.agent_url}/api/agents/webhook/{quote(self.agent_id, safe='')}"
+
+    def _session_url(self, session_id: str) -> str:
+        return f"{self.agent_url}/api/agents/{quote(self.agent_id, safe='')}/sessions/{quote(session_id, safe='')}"
+
+    def _get(self, url: str, operation: str, params: Dict[str, Any] = None) -> Dict[str, Any]:
+        try:
+            response = requests.get(url, headers={'Authorization': f'Bearer {self.api_key}'},
+                                    params=params, timeout=30)
+        except requests.exceptions.RequestException as e:
+            raise NetworkError(f"Network error ({operation}): {e}")
+        self._handle_response_errors(response, operation)
+        return response.json()
+
     def _handle_response_errors(self, response: requests.Response, operation: str):
         """Handle HTTP response errors and raise appropriate exceptions."""
         if response.status_code == 200: