openhands-sdk 1.3.0__tar.gz → 1.4.1__tar.gz

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.3.0
+Version: 1.4.1
 Summary: OpenHands SDK - Core functionality for building AI agents
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0
 Requires-Dist: fastmcp>=2.11.3
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: litellm>=1.77.7.dev9
+Requires-Dist: litellm>=1.80.7
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: python-json-logger>=3.3.0

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/__init__.py

@@ -21,11 +21,13 @@ from openhands.sdk.llm import (
     LLM,
     ImageContent,
     LLMRegistry,
+    LLMStreamChunk,
     Message,
     RedactedThinkingBlock,
     RegistryEvent,
     TextContent,
     ThinkingBlock,
+    TokenCallbackType,
 )
 from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp import (
@@ -58,6 +60,8 @@ except PackageNotFoundError:
 __all__ = [
     "LLM",
     "LLMRegistry",
+    "LLMStreamChunk",
+    "TokenCallbackType",
     "ConversationStats",
     "RegistryEvent",
     "Message",

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/agent/agent.py

@@ -13,6 +13,7 @@ from openhands.sdk.agent.utils import (
 from openhands.sdk.conversation import (
     ConversationCallbackType,
     ConversationState,
+    ConversationTokenCallbackType,
     LocalConversation,
 )
 from openhands.sdk.conversation.state import ConversationExecutionStatus
@@ -27,6 +28,7 @@ from openhands.sdk.event import (
 )
 from openhands.sdk.event.condenser import Condensation, CondensationRequest
 from openhands.sdk.llm import (
+    LLMResponse,
     Message,
     MessageToolCall,
     ReasoningItemModel,
@@ -135,6 +137,7 @@ class Agent(AgentBase):
         self,
         conversation: LocalConversation,
         on_event: ConversationCallbackType,
+        on_token: ConversationTokenCallbackType | None = None,
     ) -> None:
         state = conversation.state
         # Check for pending actions (implicit confirmation)
@@ -167,7 +170,10 @@ class Agent(AgentBase):
 
         try:
             llm_response = make_llm_completion(
-                self.llm, _messages, tools=list(self.tools_map.values())
+                self.llm,
+                _messages,
+                tools=list(self.tools_map.values()),
+                on_token=on_token,
             )
         except FunctionCallValidationError as e:
             logger.warning(f"LLM generated malformed function call: {e}")
@@ -197,6 +203,17 @@ class Agent(AgentBase):
         # LLMResponse already contains the converted message and metrics snapshot
         message: Message = llm_response.message
 
+        # Check if this is a reasoning-only response (e.g., from reasoning models)
+        # or a message-only response without tool calls
+        has_reasoning = (
+            message.responses_reasoning_item is not None
+            or message.reasoning_content is not None
+            or (message.thinking_blocks and len(message.thinking_blocks) > 0)
+        )
+        has_content = any(
+            isinstance(c, TextContent) and c.text.strip() for c in message.content
+        )
+
         if message.tool_calls and len(message.tool_calls) > 0:
             if not all(isinstance(c, TextContent) for c in message.content):
                 logger.warning(
@@ -236,29 +253,30 @@ class Agent(AgentBase):
             if action_events:
                 self._execute_actions(conversation, action_events, on_event)
 
-        else:
+            # Emit VLLM token ids if enabled before returning
+            self._maybe_emit_vllm_tokens(llm_response, on_event)
+            return
+
+        # No tool calls - emit message event for reasoning or content responses
+        if not has_reasoning and not has_content:
+            logger.warning("LLM produced empty response - continuing agent loop")
+
+        msg_event = MessageEvent(
+            source="agent",
+            llm_message=message,
+            llm_response_id=llm_response.id,
+        )
+        on_event(msg_event)
+
+        # Emit VLLM token ids if enabled
+        self._maybe_emit_vllm_tokens(llm_response, on_event)
+
+        # Finish conversation if LLM produced content (awaits user input)
+        # Continue if only reasoning without content (e.g., GPT-5 codex thinking)
+        if has_content:
             logger.debug("LLM produced a message response - awaits user input")
             state.execution_status = ConversationExecutionStatus.FINISHED
-            msg_event = MessageEvent(
-                source="agent",
-                llm_message=message,
-                llm_response_id=llm_response.id,
-            )
-            on_event(msg_event)
-
-        # If using VLLM, we can get the raw prompt and response tokens
-        # that can be useful for RL training.
-        if (
-            "return_token_ids" in self.llm.litellm_extra_body
-        ) and self.llm.litellm_extra_body["return_token_ids"]:
-            token_event = TokenEvent(
-                source="agent",
-                prompt_token_ids=llm_response.raw_response["prompt_token_ids"],
-                response_token_ids=llm_response.raw_response["choices"][0][
-                    "provider_specific_fields"
-                ]["token_ids"],
-            )
-            on_event(token_event)
+            return
 
     def _requires_user_confirmation(
         self, state: ConversationState, action_events: list[ActionEvent]
@@ -483,3 +501,18 @@ class Agent(AgentBase):
         if tool.name == FinishTool.name:
             state.execution_status = ConversationExecutionStatus.FINISHED
         return obs_event
+
+    def _maybe_emit_vllm_tokens(
+        self, llm_response: LLMResponse, on_event: ConversationCallbackType
+    ) -> None:
+        if (
+            "return_token_ids" in self.llm.litellm_extra_body
+        ) and self.llm.litellm_extra_body["return_token_ids"]:
+            token_event = TokenEvent(
+                source="agent",
+                prompt_token_ids=llm_response.raw_response["prompt_token_ids"],
+                response_token_ids=llm_response.raw_response["choices"][0][
+                    "provider_specific_fields"
+                ]["token_ids"],
+            )
+            on_event(token_event)

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/agent/base.py

@@ -20,7 +20,10 @@ from openhands.sdk.utils.pydantic_diff import pretty_pydantic_diff
 
 if TYPE_CHECKING:
     from openhands.sdk.conversation import ConversationState, LocalConversation
-    from openhands.sdk.conversation.types import ConversationCallbackType
+    from openhands.sdk.conversation.types import (
+        ConversationCallbackType,
+        ConversationTokenCallbackType,
+    )
 
 
 logger = get_logger(__name__)
@@ -239,6 +242,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         self,
         conversation: "LocalConversation",
         on_event: "ConversationCallbackType",
+        on_token: "ConversationTokenCallbackType | None" = None,
     ) -> None:
         """Taking a step in the conversation.
 
@@ -250,6 +254,9 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         4.1 If conversation is finished, set state.execution_status to FINISHED
         4.2 Otherwise, just return, Conversation will kick off the next step
 
+        If the underlying LLM supports streaming, partial deltas are forwarded to
+        ``on_token`` before the full response is returned.
+
         NOTE: state will be mutated in-place.
         """
 

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/agent/prompts/system_prompt.j2

@@ -90,20 +90,10 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
   1. Step back and reflect on 5-7 different possible sources of the problem
   2. Assess the likelihood of each possible cause
   3. Methodically address the most likely causes, starting with the highest probability
-  4. Document your reasoning process
+  4. Explain your reasoning process in your response to the user
 * When you run into any major issue while executing a plan from the user, please don't try to directly work around it. Instead, propose a new plan and confirm with the user before proceeding.
 </TROUBLESHOOTING>
 
-<DOCUMENTATION>
-* When explaining changes or solutions to the user:
-  - Include explanations in your conversation responses rather than creating separate documentation files
-  - If you need to create documentation files for reference, do NOT include them in version control unless explicitly requested
-  - Never create multiple versions of documentation files with different suffixes
-* If the user asks for documentation:
-  - Confirm whether they want it as a separate file or just in the conversation
-  - Ask if they want documentation files to be included in version control
-</DOCUMENTATION>
-
 <PROCESS_MANAGEMENT>
 * When terminating processes:
   - Do NOT use general keywords with commands like `pkill -f server` or `pkill -f python` as this might accidentally kill other important servers or processes

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/agent/utils.py

@@ -12,6 +12,7 @@ from typing import (
 
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.context.view import View
+from openhands.sdk.conversation.types import ConversationTokenCallbackType
 from openhands.sdk.event.base import Event, LLMConvertibleEvent
 from openhands.sdk.event.condenser import Condensation
 from openhands.sdk.llm import LLM, LLMResponse, Message
@@ -182,6 +183,7 @@ def make_llm_completion(
     llm: LLM,
     messages: list[Message],
     tools: list[ToolDefinition] | None = None,
+    on_token: ConversationTokenCallbackType | None = None,
 ) -> LLMResponse:
     """Make an LLM completion call with the provided messages and tools.
 
@@ -189,6 +191,7 @@ def make_llm_completion(
         llm: The LLM instance to use for completion
         messages: The messages to send to the LLM
         tools: Optional list of tools to provide to the LLM
+        on_token: Optional callback for streaming token updates
 
     Returns:
         LLMResponse from the LLM completion call
@@ -200,10 +203,12 @@ def make_llm_completion(
             include=None,
             store=False,
             add_security_risk_prediction=True,
+            on_token=on_token,
         )
     else:
         return llm.completion(
             messages=messages,
             tools=tools or [],
             add_security_risk_prediction=True,
+            on_token=on_token,
         )

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/context/agent_context.py

@@ -6,6 +6,7 @@ from openhands.sdk.context.prompts import render_template
 from openhands.sdk.context.skills import (
     Skill,
     SkillKnowledge,
+    load_public_skills,
     load_user_skills,
 )
 from openhands.sdk.llm import Message, TextContent
@@ -56,6 +57,14 @@ class AgentContext(BaseModel):
             "and ~/.openhands/microagents/ (for backward compatibility). "
         ),
     )
+    load_public_skills: bool = Field(
+        default=False,
+        description=(
+            "Whether to automatically load skills from the public OpenHands "
+            "skills repository at https://github.com/OpenHands/skills. "
+            "This allows you to get the latest skills without SDK updates."
+        ),
+    )
 
     @field_validator("skills")
     @classmethod
@@ -93,6 +102,27 @@ class AgentContext(BaseModel):
 
         return self
 
+    @model_validator(mode="after")
+    def _load_public_skills(self):
+        """Load public skills from OpenHands skills repository if enabled."""
+        if not self.load_public_skills:
+            return self
+        try:
+            public_skills = load_public_skills()
+            # Merge public skills with explicit skills, avoiding duplicates
+            existing_names = {skill.name for skill in self.skills}
+            for public_skill in public_skills:
+                if public_skill.name not in existing_names:
+                    self.skills.append(public_skill)
+                else:
+                    logger.warning(
+                        f"Skipping public skill '{public_skill.name}' "
+                        f"(already in existing skills)"
+                    )
+        except Exception as e:
+            logger.warning(f"Failed to load public skills: {str(e)}")
+        return self
+
     def get_system_message_suffix(self) -> str | None:
         """Get the system message with repo skill content and custom suffix.
 

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/context/skills/__init__.py

@@ -1,6 +1,7 @@
 from openhands.sdk.context.skills.exceptions import SkillValidationError
 from openhands.sdk.context.skills.skill import (
     Skill,
+    load_public_skills,
     load_skills_from_dir,
     load_user_skills,
 )
@@ -20,5 +21,6 @@ __all__ = [
     "SkillKnowledge",
     "load_skills_from_dir",
     "load_user_skills",
+    "load_public_skills",
     "SkillValidationError",
 ]

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/context/skills/skill.py

@@ -1,5 +1,7 @@
 import io
 import re
+import shutil
+import subprocess
 from itertools import chain
 from pathlib import Path
 from typing import Annotated, ClassVar, Union
@@ -15,10 +17,15 @@ from openhands.sdk.context.skills.trigger import (
 )
 from openhands.sdk.context.skills.types import InputMetadata
 from openhands.sdk.logger import get_logger
+from openhands.sdk.utils import maybe_truncate
 
 
 logger = get_logger(__name__)
 
+# Maximum characters for third-party skill files (e.g., AGENTS.md, CLAUDE.md, GEMINI.md)
+# These files are always active, so we want to keep them reasonably sized
+THIRD_PARTY_SKILL_MAX_CHARS = 10_000
+
 # Union type for all trigger types
 TriggerType = Annotated[
     KeywordTrigger | TaskTrigger,
@@ -71,6 +78,8 @@ class Skill(BaseModel):
         ".cursorrules": "cursorrules",
         "agents.md": "agents",
         "agent.md": "agents",
+        "claude.md": "claude",
+        "gemini.md": "gemini",
     }
 
     @classmethod
@@ -80,9 +89,30 @@ class Skill(BaseModel):
 
         # Create Skill with None trigger (always active) if we recognized the file type
         if skill_name is not None:
+            # Truncate content if it exceeds the limit
+            # Third-party files are always active, so we want to keep them
+            # reasonably sized
+            truncated_content = maybe_truncate(
+                file_content,
+                truncate_after=THIRD_PARTY_SKILL_MAX_CHARS,
+                truncate_notice=(
+                    f"\n\n<TRUNCATED><NOTE>The file {path} exceeded the "
+                    f"maximum length ({THIRD_PARTY_SKILL_MAX_CHARS} "
+                    f"characters) and has been truncated. Only the "
+                    f"beginning and end are shown. You can read the full "
+                    f"file if needed.</NOTE>\n\n"
+                ),
+            )
+
+            if len(file_content) > THIRD_PARTY_SKILL_MAX_CHARS:
+                logger.warning(
+                    f"Third-party skill file {path} ({len(file_content)} chars) "
+                    f"exceeded limit ({THIRD_PARTY_SKILL_MAX_CHARS} chars), truncating"
+                )
+
             return Skill(
                 name=skill_name,
-                content=file_content,
+                content=truncated_content,
                 source=str(path),
                 trigger=None,
             )
@@ -366,3 +396,174 @@ def load_user_skills() -> list[Skill]:
         f"Loaded {len(all_skills)} user skills: {[s.name for s in all_skills]}"
     )
     return all_skills
+
+
+# Public skills repository configuration
+PUBLIC_SKILLS_REPO = "https://github.com/OpenHands/skills"
+PUBLIC_SKILLS_BRANCH = "main"
+
+
+def _get_skills_cache_dir() -> Path:
+    """Get the local cache directory for public skills repository.
+
+    Returns:
+        Path to the skills cache directory (~/.openhands/cache/skills).
+    """
+    cache_dir = Path.home() / ".openhands" / "cache" / "skills"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def _update_skills_repository(
+    repo_url: str,
+    branch: str,
+    cache_dir: Path,
+) -> Path | None:
+    """Clone or update the local skills repository.
+
+    Args:
+        repo_url: URL of the skills repository.
+        branch: Branch name to use.
+        cache_dir: Directory where the repository should be cached.
+
+    Returns:
+        Path to the local repository if successful, None otherwise.
+    """
+    repo_path = cache_dir / "public-skills"
+
+    try:
+        if repo_path.exists() and (repo_path / ".git").exists():
+            logger.debug(f"Updating skills repository at {repo_path}")
+            try:
+                subprocess.run(
+                    ["git", "fetch", "origin"],
+                    cwd=repo_path,
+                    check=True,
+                    capture_output=True,
+                    timeout=30,
+                )
+                subprocess.run(
+                    ["git", "reset", "--hard", f"origin/{branch}"],
+                    cwd=repo_path,
+                    check=True,
+                    capture_output=True,
+                    timeout=10,
+                )
+                logger.debug("Skills repository updated successfully")
+            except subprocess.TimeoutExpired:
+                logger.warning("Git pull timed out, using existing cached repository")
+            except subprocess.CalledProcessError as e:
+                logger.warning(
+                    f"Failed to update repository: {e.stderr.decode()}, "
+                    f"using existing cached version"
+                )
+        else:
+            logger.info(f"Cloning public skills repository from {repo_url}")
+            if repo_path.exists():
+                shutil.rmtree(repo_path)
+
+            subprocess.run(
+                [
+                    "git",
+                    "clone",
+                    "--depth",
+                    "1",
+                    "--branch",
+                    branch,
+                    repo_url,
+                    str(repo_path),
+                ],
+                check=True,
+                capture_output=True,
+                timeout=60,
+            )
+            logger.debug(f"Skills repository cloned to {repo_path}")
+
+        return repo_path
+
+    except subprocess.TimeoutExpired:
+        logger.warning(f"Git operation timed out for {repo_url}")
+        return None
+    except subprocess.CalledProcessError as e:
+        logger.warning(
+            f"Failed to clone/update repository {repo_url}: {e.stderr.decode()}"
+        )
+        return None
+    except Exception as e:
+        logger.warning(f"Error managing skills repository: {str(e)}")
+        return None
+
+
+def load_public_skills(
+    repo_url: str = PUBLIC_SKILLS_REPO,
+    branch: str = PUBLIC_SKILLS_BRANCH,
+) -> list[Skill]:
+    """Load skills from the public OpenHands skills repository.
+
+    This function maintains a local git clone of the public skills registry at
+    https://github.com/OpenHands/skills. On first run, it clones the repository
+    to ~/.openhands/skills-cache/. On subsequent runs, it pulls the latest changes
+    to keep the skills up-to-date. This approach is more efficient than fetching
+    individual files via HTTP.
+
+    Args:
+        repo_url: URL of the skills repository. Defaults to the official
+            OpenHands skills repository.
+        branch: Branch name to load skills from. Defaults to 'main'.
+
+    Returns:
+        List of Skill objects loaded from the public repository.
+        Returns empty list if loading fails.
+
+    Example:
+        >>> from openhands.sdk.context import AgentContext
+        >>> from openhands.sdk.context.skills import load_public_skills
+        >>>
+        >>> # Load public skills
+        >>> public_skills = load_public_skills()
+        >>>
+        >>> # Use with AgentContext
+        >>> context = AgentContext(skills=public_skills)
+    """
+    all_skills = []
+
+    try:
+        # Get or update the local repository
+        cache_dir = _get_skills_cache_dir()
+        repo_path = _update_skills_repository(repo_url, branch, cache_dir)
+
+        if repo_path is None:
+            logger.warning("Failed to access public skills repository")
+            return all_skills
+
+        # Load skills from the local repository
+        skills_dir = repo_path / "skills"
+        if not skills_dir.exists():
+            logger.warning(f"Skills directory not found in repository: {skills_dir}")
+            return all_skills
+
+        # Find all .md files in the skills directory
+        md_files = [f for f in skills_dir.rglob("*.md") if f.name != "README.md"]
+
+        logger.info(f"Found {len(md_files)} skill files in public skills repository")
+
+        # Load each skill file
+        for skill_file in md_files:
+            try:
+                skill = Skill.load(
+                    path=skill_file,
+                    skill_dir=repo_path,
+                )
+                all_skills.append(skill)
+                logger.debug(f"Loaded public skill: {skill.name}")
+            except Exception as e:
+                logger.warning(f"Failed to load skill from {skill_file.name}: {str(e)}")
+                continue
+
+    except Exception as e:
+        logger.warning(f"Failed to load public skills from {repo_url}: {str(e)}")
+
+    logger.info(
+        f"Loaded {len(all_skills)} public skills: {[s.name for s in all_skills]}"
+    )
+    return all_skills

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/conversation/__init__.py

@@ -11,7 +11,10 @@ from openhands.sdk.conversation.state import (
     ConversationState,
 )
 from openhands.sdk.conversation.stuck_detector import StuckDetector
-from openhands.sdk.conversation.types import ConversationCallbackType
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationTokenCallbackType,
+)
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
@@ -24,6 +27,7 @@ __all__ = [
     "ConversationState",
     "ConversationExecutionStatus",
     "ConversationCallbackType",
+    "ConversationTokenCallbackType",
     "DefaultConversationVisualizer",
     "ConversationVisualizerBase",
     "SecretRegistry",

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/conversation/base.py

@@ -1,12 +1,16 @@
 from abc import ABC, abstractmethod
 from collections.abc import Iterable, Mapping
 from pathlib import Path
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, TypeVar, cast
 
 from openhands.sdk.conversation.conversation_stats import ConversationStats
 from openhands.sdk.conversation.events_list_base import EventsListBase
 from openhands.sdk.conversation.secret_registry import SecretValue
-from openhands.sdk.conversation.types import ConversationCallbackType, ConversationID
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    ConversationTokenCallbackType,
+)
 from openhands.sdk.llm.llm import LLM
 from openhands.sdk.llm.message import Message
 from openhands.sdk.observability.laminar import (
@@ -27,6 +31,13 @@ if TYPE_CHECKING:
     from openhands.sdk.conversation.state import ConversationExecutionStatus
 
 
+CallbackType = TypeVar(
+    "CallbackType",
+    ConversationCallbackType,
+    ConversationTokenCallbackType,
+)
+
+
 class ConversationStateProtocol(Protocol):
     """Protocol defining the interface for conversation state objects."""
 
@@ -235,9 +246,7 @@ class BaseConversation(ABC):
         ...
 
     @staticmethod
-    def compose_callbacks(
-        callbacks: Iterable[ConversationCallbackType],
-    ) -> ConversationCallbackType:
+    def compose_callbacks(callbacks: Iterable[CallbackType]) -> CallbackType:
         """Compose multiple callbacks into a single callback function.
 
         Args:
@@ -252,4 +261,4 @@ class BaseConversation(ABC):
                 if cb:
                     cb(event)
 
-        return composed
+        return cast(CallbackType, composed)

{openhands_sdk-1.3.0 → openhands_sdk-1.4.1}/openhands/sdk/conversation/conversation.py

@@ -4,7 +4,11 @@ from typing import TYPE_CHECKING, Self, overload
 from openhands.sdk.agent.base import AgentBase
 from openhands.sdk.conversation.base import BaseConversation
 from openhands.sdk.conversation.secret_registry import SecretValue
-from openhands.sdk.conversation.types import ConversationCallbackType, ConversationID
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    ConversationTokenCallbackType,
+)
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
@@ -49,6 +53,7 @@ class Conversation:
         persistence_dir: str | Path | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         visualizer: (
@@ -65,6 +70,7 @@ class Conversation:
         workspace: RemoteWorkspace,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         visualizer: (
@@ -81,6 +87,7 @@ class Conversation:
         persistence_dir: str | Path | None = None,
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         visualizer: (
@@ -104,6 +111,7 @@ class Conversation:
                 agent=agent,
                 conversation_id=conversation_id,
                 callbacks=callbacks,
+                token_callbacks=token_callbacks,
                 max_iteration_per_run=max_iteration_per_run,
                 stuck_detection=stuck_detection,
                 visualizer=visualizer,
@@ -115,6 +123,7 @@ class Conversation:
             agent=agent,
             conversation_id=conversation_id,
             callbacks=callbacks,
+            token_callbacks=token_callbacks,
             max_iteration_per_run=max_iteration_per_run,
             stuck_detection=stuck_detection,
             visualizer=visualizer,