letta-nightly 0.7.30.dev20250603104343__py3-none-any.whl → 0.8.0.dev20250604201135__py3-none-any.whl

letta/services/files_agents_manager.py

@@ -0,0 +1,184 @@
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from sqlalchemy import and_, func, select, update
+
+from letta.orm.errors import NoResultFound
+from letta.orm.files_agents import FileAgent as FileAgentModel
+from letta.schemas.file import FileAgent as PydanticFileAgent
+from letta.schemas.user import User as PydanticUser
+from letta.server.db import db_registry
+from letta.tracing import trace_method
+from letta.utils import enforce_types
+
+
+class FileAgentManager:
+    """High-level helpers for CRUD / listing on the `files_agents` join table."""
+
+    @enforce_types
+    @trace_method
+    async def attach_file(
+        self,
+        *,
+        agent_id: str,
+        file_id: str,
+        actor: PydanticUser,
+        is_open: bool = True,
+        visible_content: Optional[str] = None,
+    ) -> PydanticFileAgent:
+        """
+        Idempotently attach *file_id* to *agent_id*.
+
+        • If the row already exists → update `is_open`, `visible_content`
+          and always refresh `last_accessed_at`.
+        • Otherwise create a brand-new association.
+        """
+        async with db_registry.async_session() as session:
+            query = select(FileAgentModel).where(
+                and_(
+                    FileAgentModel.agent_id == agent_id,
+                    FileAgentModel.file_id == file_id,
+                    FileAgentModel.organization_id == actor.organization_id,
+                )
+            )
+            existing = await session.scalar(query)
+
+            now_ts = datetime.now(timezone.utc)
+
+            if existing:
+                # update only the fields that actually changed
+                if existing.is_open != is_open:
+                    existing.is_open = is_open
+
+                if visible_content is not None and existing.visible_content != visible_content:
+                    existing.visible_content = visible_content
+
+                existing.last_accessed_at = now_ts
+
+                await existing.update_async(session, actor=actor)
+                return existing.to_pydantic()
+
+            assoc = FileAgentModel(
+                agent_id=agent_id,
+                file_id=file_id,
+                organization_id=actor.organization_id,
+                is_open=is_open,
+                visible_content=visible_content,
+                last_accessed_at=now_ts,
+            )
+            await assoc.create_async(session, actor=actor)
+            return assoc.to_pydantic()
+
+    @enforce_types
+    @trace_method
+    async def update_file_agent(
+        self,
+        *,
+        agent_id: str,
+        file_id: str,
+        actor: PydanticUser,
+        is_open: Optional[bool] = None,
+        visible_content: Optional[str] = None,
+    ) -> PydanticFileAgent:
+        """Patch an existing association row."""
+        async with db_registry.async_session() as session:
+            assoc = await self._get_association(session, agent_id, file_id, actor)
+
+            if is_open is not None:
+                assoc.is_open = is_open
+            if visible_content is not None:
+                assoc.visible_content = visible_content
+
+            # touch timestamp
+            assoc.last_accessed_at = datetime.now(timezone.utc)
+
+            await assoc.update_async(session, actor=actor)
+            return assoc.to_pydantic()
+
+    @enforce_types
+    @trace_method
+    async def detach_file(self, *, agent_id: str, file_id: str, actor: PydanticUser) -> None:
+        """Hard-delete the association."""
+        async with db_registry.async_session() as session:
+            assoc = await self._get_association(session, agent_id, file_id, actor)
+            await assoc.hard_delete_async(session, actor=actor)
+
+    @enforce_types
+    @trace_method
+    async def get_file_agent(self, *, agent_id: str, file_id: str, actor: PydanticUser) -> Optional[PydanticFileAgent]:
+        async with db_registry.async_session() as session:
+            try:
+                assoc = await self._get_association(session, agent_id, file_id, actor)
+                return assoc.to_pydantic()
+            except NoResultFound:
+                return None
+
+    @enforce_types
+    @trace_method
+    async def list_files_for_agent(
+        self,
+        agent_id: str,
+        actor: PydanticUser,
+        is_open_only: bool = False,
+    ) -> List[PydanticFileAgent]:
+        """Return associations for *agent_id* (filtering by `is_open` if asked)."""
+        async with db_registry.async_session() as session:
+            conditions = [
+                FileAgentModel.agent_id == agent_id,
+                FileAgentModel.organization_id == actor.organization_id,
+            ]
+            if is_open_only:
+                conditions.append(FileAgentModel.is_open.is_(True))
+
+            rows = (await session.execute(select(FileAgentModel).where(and_(*conditions)))).scalars().all()
+            return [r.to_pydantic() for r in rows]
+
+    @enforce_types
+    @trace_method
+    async def list_agents_for_file(
+        self,
+        file_id: str,
+        actor: PydanticUser,
+        is_open_only: bool = False,
+    ) -> List[PydanticFileAgent]:
+        """Return associations for *file_id* (filtering by `is_open` if asked)."""
+        async with db_registry.async_session() as session:
+            conditions = [
+                FileAgentModel.file_id == file_id,
+                FileAgentModel.organization_id == actor.organization_id,
+            ]
+            if is_open_only:
+                conditions.append(FileAgentModel.is_open.is_(True))
+
+            rows = (await session.execute(select(FileAgentModel).where(and_(*conditions)))).scalars().all()
+            return [r.to_pydantic() for r in rows]
+
+    @enforce_types
+    @trace_method
+    async def mark_access(self, *, agent_id: str, file_id: str, actor: PydanticUser) -> None:
+        """Update only `last_accessed_at = now()` without loading the row."""
+        async with db_registry.async_session() as session:
+            stmt = (
+                update(FileAgentModel)
+                .where(
+                    FileAgentModel.agent_id == agent_id,
+                    FileAgentModel.file_id == file_id,
+                    FileAgentModel.organization_id == actor.organization_id,
+                )
+                .values(last_accessed_at=func.now())
+            )
+            await session.execute(stmt)
+            await session.commit()
+
+    async def _get_association(self, session, agent_id: str, file_id: str, actor: PydanticUser) -> FileAgentModel:
+        q = select(FileAgentModel).where(
+            and_(
+                FileAgentModel.agent_id == agent_id,
+                FileAgentModel.file_id == file_id,
+                FileAgentModel.organization_id == actor.organization_id,
+            )
+        )
+        assoc = await session.scalar(q)
+        if not assoc:
+            raise NoResultFound(f"FileAgent(agent_id={agent_id}, file_id={file_id}) not found in org {actor.organization_id}")
+        return assoc

letta/services/group_manager.py

@@ -1,5 +1,6 @@
 from typing import List, Optional
 
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from letta.orm.agent import Agent as AgentModel
@@ -51,6 +52,13 @@ class GroupManager:
             group = GroupModel.read(db_session=session, identifier=group_id, actor=actor)
             return group.to_pydantic()
 
+    @trace_method
+    @enforce_types
+    async def retrieve_group_async(self, group_id: str, actor: PydanticUser) -> PydanticGroup:
+        async with db_registry.async_session() as session:
+            group = await GroupModel.read_async(db_session=session, identifier=group_id, actor=actor)
+            return group.to_pydantic()
+
     @trace_method
     @enforce_types
     def create_group(self, group: GroupCreate, actor: PydanticUser) -> PydanticGroup:
@@ -97,6 +105,51 @@ class GroupManager:
             new_group.create(session, actor=actor)
             return new_group.to_pydantic()
 
+    @enforce_types
+    async def create_group_async(self, group: GroupCreate, actor: PydanticUser) -> PydanticGroup:
+        async with db_registry.async_session() as session:
+            new_group = GroupModel()
+            new_group.organization_id = actor.organization_id
+            new_group.description = group.description
+
+            match group.manager_config.manager_type:
+                case ManagerType.round_robin:
+                    new_group.manager_type = ManagerType.round_robin
+                    new_group.max_turns = group.manager_config.max_turns
+                case ManagerType.dynamic:
+                    new_group.manager_type = ManagerType.dynamic
+                    new_group.manager_agent_id = group.manager_config.manager_agent_id
+                    new_group.max_turns = group.manager_config.max_turns
+                    new_group.termination_token = group.manager_config.termination_token
+                case ManagerType.supervisor:
+                    new_group.manager_type = ManagerType.supervisor
+                    new_group.manager_agent_id = group.manager_config.manager_agent_id
+                case ManagerType.sleeptime:
+                    new_group.manager_type = ManagerType.sleeptime
+                    new_group.manager_agent_id = group.manager_config.manager_agent_id
+                    new_group.sleeptime_agent_frequency = group.manager_config.sleeptime_agent_frequency
+                    if new_group.sleeptime_agent_frequency:
+                        new_group.turns_counter = -1
+                case ManagerType.voice_sleeptime:
+                    new_group.manager_type = ManagerType.voice_sleeptime
+                    new_group.manager_agent_id = group.manager_config.manager_agent_id
+                    max_message_buffer_length = group.manager_config.max_message_buffer_length
+                    min_message_buffer_length = group.manager_config.min_message_buffer_length
+                    # Safety check for buffer length range
+                    self.ensure_buffer_length_range_valid(max_value=max_message_buffer_length, min_value=min_message_buffer_length)
+                    new_group.max_message_buffer_length = max_message_buffer_length
+                    new_group.min_message_buffer_length = min_message_buffer_length
+                case _:
+                    raise ValueError(f"Unsupported manager type: {group.manager_config.manager_type}")
+
+            await self._process_agent_relationship_async(session=session, group=new_group, agent_ids=group.agent_ids, allow_partial=False)
+
+            if group.shared_block_ids:
+                await self._process_shared_block_relationship_async(session=session, group=new_group, block_ids=group.shared_block_ids)
+
+            await new_group.create_async(session, actor=actor)
+            return new_group.to_pydantic()
+
     @trace_method
     @enforce_types
     def modify_group(self, group_id: str, group_update: GroupUpdate, actor: PydanticUser) -> PydanticGroup:
@@ -313,6 +366,38 @@ class GroupManager:
         else:
             raise ValueError("Extend relationship is not supported for groups.")
 
+    async def _process_agent_relationship_async(self, session, group: GroupModel, agent_ids: List[str], allow_partial=False, replace=True):
+        if not agent_ids:
+            if replace:
+                setattr(group, "agents", [])
+                setattr(group, "agent_ids", [])
+            return
+
+        if group.manager_type == ManagerType.dynamic and len(agent_ids) != len(set(agent_ids)):
+            raise ValueError("Duplicate agent ids found in list")
+
+        # Retrieve models for the provided IDs
+        query = select(AgentModel).where(AgentModel.id.in_(agent_ids))
+        result = await session.execute(query)
+        found_items = result.scalars().all()
+
+        # Validate all items are found if allow_partial is False
+        if not allow_partial and len(found_items) != len(agent_ids):
+            missing = set(agent_ids) - {item.id for item in found_items}
+            raise NoResultFound(f"Items not found in agents: {missing}")
+
+        if group.manager_type == ManagerType.dynamic:
+            names = [item.name for item in found_items]
+            if len(names) != len(set(names)):
+                raise ValueError("Duplicate agent names found in the provided agent IDs.")
+
+        if replace:
+            # Replace the relationship
+            setattr(group, "agents", found_items)
+            setattr(group, "agent_ids", agent_ids)
+        else:
+            raise ValueError("Extend relationship is not supported for groups.")
+
     def _process_shared_block_relationship(
         self,
         session: Session,
@@ -340,6 +425,39 @@ class GroupManager:
                 for block in blocks:
                     session.add(BlocksAgents(agent_id=manager_agent.id, block_id=block.id, block_label=block.label))
 
+    async def _process_shared_block_relationship_async(
+        self,
+        session,
+        group: GroupModel,
+        block_ids: List[str],
+    ):
+        """Process shared block relationships for a group and its agents."""
+        from letta.orm import Agent, Block, BlocksAgents
+
+        # Add blocks to group
+        query = select(Block).where(Block.id.in_(block_ids))
+        result = await session.execute(query)
+        blocks = result.scalars().all()
+        group.shared_blocks = blocks
+
+        # Add blocks to all agents
+        if group.agent_ids:
+            query = select(Agent).where(Agent.id.in_(group.agent_ids))
+            result = await session.execute(query)
+            agents = result.scalars().all()
+            for agent in agents:
+                for block in blocks:
+                    session.add(BlocksAgents(agent_id=agent.id, block_id=block.id, block_label=block.label))
+
+        # Add blocks to manager agent if exists
+        if group.manager_agent_id:
+            query = select(Agent).where(Agent.id == group.manager_agent_id)
+            result = await session.execute(query)
+            manager_agent = result.scalar_one_or_none()
+            if manager_agent:
+                for block in blocks:
+                    session.add(BlocksAgents(agent_id=manager_agent.id, block_id=block.id, block_label=block.label))
+
     @staticmethod
     def ensure_buffer_length_range_valid(
         max_value: Optional[int],

letta/services/helpers/agent_manager_helper.py

@@ -1,7 +1,8 @@
 import datetime
 from typing import List, Literal, Optional
 
-from sqlalchemy import and_, asc, desc, exists, or_, select
+from sqlalchemy import and_, asc, desc, or_, select
+from sqlalchemy.sql.expression import exists
 
 from letta import system
 from letta.constants import IN_CONTEXT_MEMORY_KEYWORD, STRUCTURED_OUTPUT_MODELS
@@ -17,7 +18,6 @@ from letta.schemas.enums import MessageRole
 from letta.schemas.letta_message_content import TextContent
 from letta.schemas.memory import Memory
 from letta.schemas.message import Message, MessageCreate
-from letta.schemas.passage import Passage as PydanticPassage
 from letta.schemas.tool_rule import ToolRule
 from letta.schemas.user import User
 from letta.system import get_initial_boot_messages, get_login_event, package_function_response
@@ -68,6 +68,50 @@ def _process_relationship(
         current_relationship.extend(new_items)
 
 
+@trace_method
+async def _process_relationship_async(
+    session, agent: AgentModel, relationship_name: str, model_class, item_ids: List[str], allow_partial=False, replace=True
+):
+    """
+    Generalized function to handle relationships like tools, sources, and blocks using item IDs.
+
+    Args:
+        session: The database session.
+        agent: The AgentModel instance.
+        relationship_name: The name of the relationship attribute (e.g., 'tools', 'sources').
+        model_class: The ORM class corresponding to the related items.
+        item_ids: List of IDs to set or update.
+        allow_partial: If True, allows missing items without raising errors.
+        replace: If True, replaces the entire relationship; otherwise, extends it.
+
+    Raises:
+        ValueError: If `allow_partial` is False and some IDs are missing.
+    """
+    current_relationship = getattr(agent, relationship_name, [])
+    if not item_ids:
+        if replace:
+            setattr(agent, relationship_name, [])
+        return
+
+    # Retrieve models for the provided IDs
+    result = await session.execute(select(model_class).where(model_class.id.in_(item_ids)))
+    found_items = result.scalars().all()
+
+    # Validate all items are found if allow_partial is False
+    if not allow_partial and len(found_items) != len(item_ids):
+        missing = set(item_ids) - {item.id for item in found_items}
+        raise NoResultFound(f"Items not found in {relationship_name}: {missing}")
+
+    if replace:
+        # Replace the relationship
+        setattr(agent, relationship_name, found_items)
+    else:
+        # Extend the relationship (only add new items)
+        current_ids = {item.id for item in current_relationship}
+        new_items = [item for item in found_items if item.id not in current_ids]
+        current_relationship.extend(new_items)
+
+
 def _process_tags(agent: AgentModel, tags: List[str], replace=True):
     """
     Handles tags for an agent.
@@ -94,16 +138,32 @@ def _process_tags(agent: AgentModel, tags: List[str], replace=True):
 def derive_system_message(agent_type: AgentType, enable_sleeptime: Optional[bool] = None, system: Optional[str] = None):
     if system is None:
         # TODO: don't hardcode
+
         if agent_type == AgentType.voice_convo_agent:
             system = gpt_system.get_system_text("voice_chat")
+
         elif agent_type == AgentType.voice_sleeptime_agent:
             system = gpt_system.get_system_text("voice_sleeptime")
+
+        # MemGPT v1, both w/ and w/o sleeptime
         elif agent_type == AgentType.memgpt_agent and not enable_sleeptime:
-            system = gpt_system.get_system_text("memgpt_chat")
+            system = gpt_system.get_system_text("memgpt_v2_chat")
         elif agent_type == AgentType.memgpt_agent and enable_sleeptime:
-            system = gpt_system.get_system_text("memgpt_sleeptime_chat")
+            # NOTE: same as the chat one, since the chat one says that you "may" have the tools
+            system = gpt_system.get_system_text("memgpt_v2_chat")
+
+        # MemGPT v2, both w/ and w/o sleeptime
+        elif agent_type == AgentType.memgpt_v2_agent and not enable_sleeptime:
+            system = gpt_system.get_system_text("memgpt_v2_chat")
+        elif agent_type == AgentType.memgpt_v2_agent and enable_sleeptime:
+            # NOTE: same as the chat one, since the chat one says that you "may" have the tools
+            system = gpt_system.get_system_text("memgpt_v2_chat")
+
+        # Sleeptime
         elif agent_type == AgentType.sleeptime_agent:
-            system = gpt_system.get_system_text("sleeptime")
+            # v2 drops references to specific blocks, and instead relies on the block description injections
+            system = gpt_system.get_system_text("sleeptime_v2")
+
         else:
             raise ValueError(f"Invalid agent type: {agent_type}")
 
@@ -115,7 +175,6 @@ def compile_memory_metadata_block(
     memory_edit_timestamp: datetime.datetime,
     previous_message_count: int = 0,
     archival_memory_size: int = 0,
-    recent_passages: List[PydanticPassage] = None,
 ) -> str:
     # Put the timestamp in the local timezone (mimicking get_local_time())
     timestamp_str = memory_edit_timestamp.astimezone().strftime("%Y-%m-%d %I:%M:%S %p %Z%z").strip()
@@ -123,15 +182,12 @@ def compile_memory_metadata_block(
     # Create a metadata block of info so the agent knows about the metadata of out-of-context memories
     memory_metadata_block = "\n".join(
         [
-            f"### Current Time: {get_local_time_fast()}" f"### Memory [last modified: {timestamp_str}]",
-            f"{previous_message_count} previous messages between you and the user are stored in recall memory (use functions to access them)",
-            f"{archival_memory_size} total memories you created are stored in archival memory (use functions to access them)",
-            (
-                f"Most recent archival passages {len(recent_passages)} recent passages: {[passage.text for passage in recent_passages]}"
-                if recent_passages is not None
-                else ""
-            ),
-            "\nCore memory shown below (limited in size, additional information stored in archival / recall memory):",
+            "<memory_metadata>",
+            f"- The current time is: {get_local_time_fast()}",
+            f"- Memory blocks were last modified: {timestamp_str}",
+            f"- {previous_message_count} previous messages between you and the user are stored in recall memory (use tools to access them)",
+            f"- {archival_memory_size} total memories you created are stored in archival memory (use tools to access them)",
+            "</memory_metadata>",
         ]
     )
     return memory_metadata_block
@@ -167,7 +223,6 @@ def compile_system_message(
     template_format: Literal["f-string", "mustache", "jinja2"] = "f-string",
     previous_message_count: int = 0,
     archival_memory_size: int = 0,
-    recent_passages: Optional[List[PydanticPassage]] = None,
 ) -> str:
     """Prepare the final/full system message that will be fed into the LLM API
 
@@ -192,9 +247,8 @@ def compile_system_message(
             memory_edit_timestamp=in_context_memory_last_edit,
             previous_message_count=previous_message_count,
             archival_memory_size=archival_memory_size,
-            recent_passages=recent_passages,
         )
-        full_memory_string = memory_metadata_string + "\n" + in_context_memory.compile()
+        full_memory_string = in_context_memory.compile() + "\n\n" + memory_metadata_string
 
         # Add to the variables list to inject
         variables[IN_CONTEXT_MEMORY_KEYWORD] = full_memory_string
@@ -206,7 +260,7 @@ def compile_system_message(
             if memory_variable_string not in system_prompt:
                 # In this case, append it to the end to make sure memory is still injected
                 # warnings.warn(f"{IN_CONTEXT_MEMORY_KEYWORD} variable was missing from system prompt, appending instead")
-                system_prompt += "\n" + memory_variable_string
+                system_prompt += "\n\n" + memory_variable_string
 
         # render the variables using the built-in templater
         try:
@@ -437,12 +491,13 @@ def _apply_tag_filter(query, tags: Optional[List[str]], match_all_tags: bool):
     Returns:
         The modified query with tag filters applied.
     """
+
     if tags:
         if match_all_tags:
             for tag in tags:
                 query = query.filter(exists().where((AgentsTags.agent_id == AgentModel.id) & (AgentsTags.tag == tag)))
-            else:
-                query = query.where(exists().where((AgentsTags.agent_id == AgentModel.id) & (AgentsTags.tag.in_(tags))))
+        else:
+            query = query.where(exists().where((AgentsTags.agent_id == AgentModel.id) & (AgentsTags.tag.in_(tags))))
     return query
 
 

letta/services/helpers/tool_execution_helper.py

@@ -60,6 +60,9 @@ def run_subprocess(command: list, env: Optional[Dict[str, str]] = None, fail_msg
     except subprocess.CalledProcessError as e:
         logger.error(f"{fail_msg}\nSTDOUT:\n{e.stdout}\nSTDERR:\n{e.stderr}")
         raise RuntimeError(f"{fail_msg}: {e.stderr.strip()}") from e
+    except Exception as e:
+        logger.error(f"{fail_msg}: {e}")
+        raise RuntimeError(f"{fail_msg}: {e}")
 
 
 def ensure_pip_is_up_to_date(python_exec: str, env: Optional[Dict[str, str]] = None):

letta/services/helpers/tool_parser_helper.py

@@ -0,0 +1,100 @@
+import ast
+import base64
+import pickle
+from typing import Any
+
+from letta.constants import REQUEST_HEARTBEAT_DESCRIPTION, REQUEST_HEARTBEAT_PARAM, SEND_MESSAGE_TOOL_NAME
+from letta.schemas.agent import AgentState
+from letta.schemas.response_format import ResponseFormatType, ResponseFormatUnion
+from letta.types import JsonDict, JsonValue
+
+
+def parse_stdout_best_effort(text: str | bytes) -> tuple[Any, AgentState | None]:
+    """
+    Decode and unpickle the result from the function execution if possible.
+    Returns (function_return_value, agent_state).
+    """
+    if not text:
+        return None, None
+    if isinstance(text, str):
+        text = base64.b64decode(text)
+    result = pickle.loads(text)
+    agent_state = result["agent_state"]
+    return result["results"], agent_state
+
+
+def parse_function_arguments(source_code: str, tool_name: str):
+    """Get arguments of a function from its source code"""
+    tree = ast.parse(source_code)
+    args = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name == tool_name:
+            for arg in node.args.args:
+                args.append(arg.arg)
+    return args
+
+
+def convert_param_to_str_value(param_type: str, raw_value: JsonValue) -> str:
+    """
+    Convert parameter to Python code representation based on JSON schema type.
+    TODO (cliandy): increase sanitization checks here to fail at the right place
+    """
+
+    valid_types = {"string", "integer", "boolean", "number", "array", "object"}
+    if param_type not in valid_types:
+        raise TypeError(f"Unsupported type: {param_type}, raw_value={raw_value}")
+    if param_type == "string":
+        # Safely handle python string
+        return repr(raw_value)
+    if param_type == "integer":
+        return str(int(raw_value))
+    if param_type == "boolean":
+        if isinstance(raw_value, bool):
+            return str(raw_value)
+        if isinstance(raw_value, int) and raw_value in (0, 1):
+            return str(bool(raw_value))
+        if isinstance(raw_value, str) and raw_value.strip().lower() in ("true", "false"):
+            return raw_value.strip().lower().capitalize()
+        raise ValueError(f"Invalid boolean value: {raw_value}")
+    if param_type == "array":
+        pass  # need more testing here
+        # if isinstance(raw_value, str):
+        #     if raw_value.strip()[0] != "[" or raw_value.strip()[-1] != "]":
+        #         raise ValueError(f'Invalid array value: "{raw_value}"')
+        #     return raw_value.strip()
+    return str(raw_value)
+
+
+def runtime_override_tool_json_schema(
+    tool_list: list[JsonDict],
+    response_format: ResponseFormatUnion | None,
+    request_heartbeat: bool = True,
+) -> list[JsonDict]:
+    """Override the tool JSON schemas at runtime if certain conditions are met.
+
+    Cases:
+        1. We will inject `send_message` tool calls with `response_format` if provided
+        2. Tools will have an additional `request_heartbeat` parameter added.
+    """
+    for tool_json in tool_list:
+        if tool_json["name"] == SEND_MESSAGE_TOOL_NAME and response_format and response_format.type != ResponseFormatType.text:
+            if response_format.type == ResponseFormatType.json_schema:
+                tool_json["parameters"]["properties"]["message"] = response_format.json_schema["schema"]
+            if response_format.type == ResponseFormatType.json_object:
+                tool_json["parameters"]["properties"]["message"] = {
+                    "type": "object",
+                    "description": "Message contents. All unicode (including emojis) are supported.",
+                    "additionalProperties": True,
+                    "properties": {},
+                }
+        if request_heartbeat:
+            # TODO (cliandy): see support for tool control loop parameters
+            if tool_json["name"] != SEND_MESSAGE_TOOL_NAME:
+                tool_json["parameters"]["properties"][REQUEST_HEARTBEAT_PARAM] = {
+                    "type": "boolean",
+                    "description": REQUEST_HEARTBEAT_DESCRIPTION,
+                }
+                if REQUEST_HEARTBEAT_PARAM not in tool_json["parameters"]["required"]:
+                    tool_json["parameters"]["required"].append(REQUEST_HEARTBEAT_PARAM)
+
+    return tool_list