Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
Fix available_skills persistence drift in V2 system message (#10021)
Sarah Wooders3e2bccce5e39
diff --git a/letta/agents/base_agent.py b/letta/agents/base_agent.pyindex 20e8dedff..e9373b310 100644--- a/letta/agents/base_agent.py+++ b/letta/agents/base_agent.py@@ -136,7 +136,6 @@ class BaseAgent(ABC):sources=agent_state.sources,max_files_open=agent_state.max_files_open,llm_config=agent_state.llm_config,- client_skills=self.client_skills,)system_prompt_changed = agent_state.system not in curr_system_message_textdiff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.pyindex 7dd1ff502..ddee5f5f3 100644--- a/letta/agents/letta_agent_v2.py+++ b/letta/agents/letta_agent_v2.py@@ -511,12 +511,17 @@ class LettaAgentV2(BaseAgentV2):force_tool_call = valid_tools[0]["name"] if len(valid_tools) == 1 else Nonefor llm_request_attempt in range(summarizer_settings.max_summarizer_retries + 1):try:+ request_system_prompt = self.generate_request_system_prompt(+ client_skills=self.client_skills,+ current_system_message=messages[0],+ )request_data = self.llm_client.build_request_data(agent_type=self.agent_state.agent_type,messages=messages,llm_config=self.agent_state.llm_config,tools=valid_tools,force_tool_call=force_tool_call,+ system=request_system_prompt,)if dry_run:yield request_data@@ -753,8 +758,6 @@ class LettaAgentV2(BaseAgentV2):This avoids rebuilding the system prompt on every step due to dynamic metadata (e.g. message counts),which can bust prefix caching.2) Scrub inner thoughts from messages.- 3) If client_skills are present, surgically update just the <available_skills> section- without rebuilding the full system prompt (preserves prefix cache).Args:in_context_messages: Current in-context messages@@ -777,70 +780,22 @@ class LettaAgentV2(BaseAgentV2):except Exception:raise- # Surgically update the <available_skills> section when client_skills are- # present without triggering a full system prompt rebuild (preserves prefix cache).- if self.client_skills:- in_context_messages = await self._update_system_message_skills(in_context_messages)-# Always scrub inner thoughts regardless of system prompt refreshin_context_messages = scrub_inner_thoughts_from_messages(in_context_messages, self.agent_state.llm_config)return in_context_messages@trace_method- async def _update_system_message_skills(self, in_context_messages: list[Message]) -> list[Message]:- """Surgically update the <available_skills> section in the system message.-- This avoids a full system prompt rebuild (which would change timestamps and- bust prefix caching) by only replacing the skills portion of the prompt.- """- import re-- if not in_context_messages:- return in_context_messages-- system_message = in_context_messages[0]- old_text = system_message.content[0].text-- # Compile the new skills section from agent blocks + client skills- new_skills = self.agent_state.memory.compile_available_skills(client_skills=self.client_skills)-- # Replace the STRUCTURAL <available_skills>...</available_skills> block.- #- # Memory block content may contain literal <available_skills> and- # </available_skills> text references (e.g. docs about the skills system).- # A regex approach cannot reliably distinguish structural tags from text- # references because non-greedy matches absorb the structural closing tag.- #- # Instead we locate the structural block by position: it is always rendered- # AFTER the last </system/...> memory block closing tag. We find the- # <available_skills> that starts after that boundary using plain string search.- block_close_pattern = re.compile(r"</system/[^>]+>")- block_closes = list(block_close_pattern.finditer(old_text))- search_from = block_closes[-1].end() if block_closes else 0-- skills_open = old_text.find("<available_skills>", search_from)- skills_close = old_text.find("</available_skills>", skills_open) if skills_open >= 0 else -1-- if skills_open >= 0 and skills_close >= 0:- # Consume leading newlines before the tag- trim_start = skills_open- while trim_start > 0 and old_text[trim_start - 1] == "\n":- trim_start -= 1- new_text = old_text[:trim_start] + new_skills + old_text[skills_close + len("</available_skills>") :]- elif new_skills:- # No existing skills section — insert right before <memory_metadata>- if "<memory_metadata>" in old_text:- new_text = old_text.replace("<memory_metadata>", new_skills.lstrip("\n") + "\n\n<memory_metadata>")- else:- return in_context_messages-- if new_text == old_text:- return in_context_messages-- new_system_message = await self.message_manager.update_message_by_id_async(- system_message.id, message_update=MessageUpdate(content=new_text), actor=self.actor- )- return [new_system_message, *in_context_messages[1:]]+ def generate_request_system_prompt(+ self,+ client_skills: list[ClientSkillSchema] | None,+ current_system_message: Message,+ ) -> str:+ """Build request-scoped system prompt text without persisting request skills."""+ current_system_text = current_system_message.content[0].text+ request_skills_block = self.agent_state.memory.compile_available_skills(client_skills=client_skills)+ if not request_skills_block:+ return current_system_text+ return current_system_text.rstrip("\n") + "\n\n" + request_skills_block.lstrip("\n")@trace_methodasync def _rebuild_memory(@@ -881,7 +836,6 @@ class LettaAgentV2(BaseAgentV2):sources=agent_state.sources,max_files_open=agent_state.max_files_open,llm_config=agent_state.llm_config,- client_skills=self.client_skills,)# Skip rebuild unless explicitly forced and unless system/memory content actually changed.diff --git a/letta/agents/letta_agent_v3.py b/letta/agents/letta_agent_v3.pyindex b86ef6988..a62d9f4b7 100644--- a/letta/agents/letta_agent_v3.py+++ b/letta/agents/letta_agent_v3.py@@ -1081,6 +1081,10 @@ class LettaAgentV3(LettaAgentV2):force_tool_call = valid_tools[0]["name"] if len(valid_tools) == 1 and self._require_tool_call else Nonefor llm_request_attempt in range(summarizer_settings.max_summarizer_retries + 1):try:+ request_system_prompt = self.generate_request_system_prompt(+ client_skills=self.client_skills,+ current_system_message=messages[0],+ )request_data = active_llm_client.build_request_data(agent_type=self.agent_state.agent_type,messages=messages,@@ -1089,6 +1093,7 @@ class LettaAgentV3(LettaAgentV2):force_tool_call=force_tool_call,requires_subsequent_tool_call=self._require_tool_call,tool_return_truncation_chars=self._compute_tool_return_truncation_chars(),+ system=request_system_prompt,)# TODO: Extend to more providers, and also approval tool rules# TODO: this entire code block should be inside of the clientsdiff --git a/letta/llm_api/anthropic_client.py b/letta/llm_api/anthropic_client.pyindex 344c3000e..9587eb9c7 100644--- a/letta/llm_api/anthropic_client.py+++ b/letta/llm_api/anthropic_client.py@@ -506,6 +506,7 @@ class AnthropicClient(LLMClientBase):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:# TODO: This needs to get cleaned up. The logic here is pretty confusing.# TODO: I really want to get rid of prefixing, it's a recipe for disaster code maintenance wise@@ -664,7 +665,9 @@ class AnthropicClient(LLMClientBase):# Move 'system' to the top levelif messages[0].role != "system":raise RuntimeError(f"First message is not a system message, instead has role {messages[0].role}")- system_content = messages[0].content if isinstance(messages[0].content, str) else messages[0].content[0].text+ system_content = system+ if system_content is None:+ system_content = messages[0].content if isinstance(messages[0].content, str) else messages[0].content[0].textdata["system"] = self._add_cache_control_to_system_message(system_content)data["messages"] = PydanticMessage.to_anthropic_dicts_from_list(messages=messages[1:],diff --git a/letta/llm_api/baseten_client.py b/letta/llm_api/baseten_client.pyindex 4212fdf01..72c2a85ef 100644--- a/letta/llm_api/baseten_client.py+++ b/letta/llm_api/baseten_client.py@@ -46,8 +46,18 @@ class BasetenClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# model field is passed through from llm_config.modeldiff --git a/letta/llm_api/bedrock_client.py b/letta/llm_api/bedrock_client.pyindex a49dcfb25..bc4e1567d 100644--- a/letta/llm_api/bedrock_client.py+++ b/letta/llm_api/bedrock_client.py@@ -84,8 +84,18 @@ class BedrockClient(AnthropicClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# Swap the model name back to the Bedrock inference profile ID for the API call# The LLMConfig.model contains the Anthropic-style name (e.g., "claude-opus-4-5-20250918")diff --git a/letta/llm_api/chatgpt_oauth_client.py b/letta/llm_api/chatgpt_oauth_client.pyindex 1befe9b91..e508f83d2 100644--- a/letta/llm_api/chatgpt_oauth_client.py+++ b/letta/llm_api/chatgpt_oauth_client.py@@ -45,6 +45,7 @@ from letta.llm_api.llm_client_base import LLMClientBasefrom letta.log import get_loggerfrom letta.otel.tracing import trace_methodfrom letta.schemas.enums import AgentType, ProviderCategory+from letta.schemas.letta_message_content import TextContentfrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.message import Message as PydanticMessagefrom letta.schemas.openai.chat_completion_response import (@@ -178,6 +179,7 @@ class ChatGPTOAuthClient(LLMClientBase):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Build request data for ChatGPT backend API in Responses API format.@@ -187,9 +189,21 @@ class ChatGPTOAuthClient(LLMClientBase):- `role: "developer"` instead of `role: "system"`- Structured content arrays"""+ request_messages = messages+ if system is not None:+ from letta.schemas.letta_message_content import TextContent++ if not messages:+ raise RuntimeError("Cannot override system prompt because messages is empty")+ if messages[0].role != "system":+ raise RuntimeError(f"First message is not a system message, instead has role {messages[0].role}")+ system_message = messages[0].model_copy(deep=True)+ system_message.content = [TextContent(text=system)]+ request_messages = [system_message, *messages[1:]]+# Use the existing method to convert messages to Responses API formatinput_messages = PydanticMessage.to_openai_responses_dicts_from_list(- messages,+ request_messages,tool_return_truncation_chars=tool_return_truncation_chars,)diff --git a/letta/llm_api/deepseek_client.py b/letta/llm_api/deepseek_client.pyindex 5b2b6ef07..efe867186 100644--- a/letta/llm_api/deepseek_client.py+++ b/letta/llm_api/deepseek_client.py@@ -54,6 +54,7 @@ class DeepseekClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:# DeepSeek thinking mode surfaces reasoning_content; keep it for active turns, drop for new user turns.llm_config.put_inner_thoughts_in_kwargs = False@@ -66,6 +67,7 @@ class DeepseekClient(OpenAIClient):force_tool_call,requires_subsequent_tool_call,tool_return_truncation_chars,+ system,)if "messages" in data:diff --git a/letta/llm_api/fireworks_client.py b/letta/llm_api/fireworks_client.pyindex 52e34a53e..57cdf80c5 100644--- a/letta/llm_api/fireworks_client.py+++ b/letta/llm_api/fireworks_client.py@@ -37,8 +37,18 @@ class FireworksClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# Add thinking configuration for reasoning modelsif self.is_reasoning_model(llm_config):diff --git a/letta/llm_api/google_vertex_client.py b/letta/llm_api/google_vertex_client.pyindex 13dc59362..5a7511558 100644--- a/letta/llm_api/google_vertex_client.py+++ b/letta/llm_api/google_vertex_client.py@@ -40,6 +40,7 @@ from letta.log import get_loggerfrom letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentTypefrom letta.schemas.enums import ProviderCategory+from letta.schemas.letta_message_content import TextContentfrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.message import Message as PydanticMessagefrom letta.schemas.openai.chat_completion_request import Tool, Tool as OpenAITool@@ -433,6 +434,7 @@ class GoogleVertexClient(LLMClientBase):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Constructs a request object in the expected data format for this client.@@ -450,9 +452,21 @@ class GoogleVertexClient(LLMClientBase):formatted_tools = []tool_names = []+ request_messages = messages+ if system is not None:+ from letta.schemas.letta_message_content import TextContent++ if not messages:+ raise RuntimeError("Cannot override system prompt because messages is empty")+ if messages[0].role != "system":+ raise RuntimeError(f"First message is not a system message, instead has role {messages[0].role}")+ system_message = messages[0].model_copy(deep=True)+ system_message.content = [TextContent(text=system)]+ request_messages = [system_message, *messages[1:]]+contents = self.add_dummy_model_messages(PydanticMessage.to_google_dicts_from_list(- messages,+ request_messages,current_model=llm_config.model,put_inner_thoughts_in_kwargs=False if agent_type == AgentType.letta_v1_agent else True,native_content=True if agent_type == AgentType.letta_v1_agent else False,diff --git a/letta/llm_api/groq_client.py b/letta/llm_api/groq_client.pyindex 5f24669d0..709da4529 100644--- a/letta/llm_api/groq_client.py+++ b/letta/llm_api/groq_client.py@@ -32,8 +32,18 @@ class GroqClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# Groq only supports string values for tool_choice: "none", "auto", "required"# Convert object-format tool_choice (used for force_tool_call) to "required"diff --git a/letta/llm_api/llm_client_base.py b/letta/llm_api/llm_client_base.pyindex 080ab2df0..8fc294480 100644--- a/letta/llm_api/llm_client_base.py+++ b/letta/llm_api/llm_client_base.py@@ -299,6 +299,7 @@ class LLMClientBase:force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Constructs a request object in the expected data format for this client.diff --git a/letta/llm_api/minimax_client.py b/letta/llm_api/minimax_client.pyindex 797699426..4c853ed9f 100644--- a/letta/llm_api/minimax_client.py+++ b/letta/llm_api/minimax_client.py@@ -129,6 +129,7 @@ class MiniMaxClient(AnthropicClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Build request data for MiniMax API.@@ -144,6 +145,7 @@ class MiniMaxClient(AnthropicClient):force_tool_call,requires_subsequent_tool_call,tool_return_truncation_chars,+ system,)# MiniMax temperature range is (0.0, 1.0], recommended value: 1diff --git a/letta/llm_api/openai_client.py b/letta/llm_api/openai_client.pyindex 85824a02d..4ef2d6ede 100644--- a/letta/llm_api/openai_client.py+++ b/letta/llm_api/openai_client.py@@ -46,7 +46,7 @@ from letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentTypefrom letta.schemas.embedding_config import EmbeddingConfigfrom letta.schemas.enums import ProviderCategory-from letta.schemas.letta_message_content import MessageContentType+from letta.schemas.letta_message_content import MessageContentType, TextContentfrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.message import Message as PydanticMessagefrom letta.schemas.openai.chat_completion_request import (@@ -321,6 +321,23 @@ class OpenAIClient(LLMClientBase):if self._supports_extended_prompt_cache_retention(model):request_obj.prompt_cache_retention = "24h"+ @staticmethod+ def _apply_system_override(messages: List[PydanticMessage], system: Optional[str]) -> List[PydanticMessage]:+ if system is None:+ return messages++ if not messages:+ raise RuntimeError("Cannot override system prompt because messages is empty")++ if messages[0].role != "system":+ raise RuntimeError(f"First message is not a system message, instead has role {messages[0].role}")++ from letta.schemas.letta_message_content import TextContent++ system_message = messages[0].model_copy(deep=True)+ system_message.content = [TextContent(text=system)]+ return [system_message, *messages[1:]]+@trace_methoddef build_request_data_responses(self,@@ -331,6 +348,7 @@ class OpenAIClient(LLMClientBase):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Constructs a request object in the expected data format for the OpenAI Responses API.@@ -338,12 +356,15 @@ class OpenAIClient(LLMClientBase):if llm_config.put_inner_thoughts_in_kwargs:raise ValueError("Inner thoughts in kwargs are not supported for the OpenAI Responses API")+ request_messages = self._apply_system_override(messages, system)+openai_messages_list = PydanticMessage.to_openai_responses_dicts_from_list(- messages, tool_return_truncation_chars=tool_return_truncation_chars+ request_messages,+ tool_return_truncation_chars=tool_return_truncation_chars,)# Add multi-modal support for Responses API by rewriting user messages# into input_text/input_image parts.- openai_messages_list = fill_image_content_in_responses_input(openai_messages_list, messages)+ openai_messages_list = fill_image_content_in_responses_input(openai_messages_list, request_messages)if llm_config.model:model = llm_config.model@@ -472,7 +493,7 @@ class OpenAIClient(LLMClientBase):self._apply_prompt_cache_settings(llm_config=llm_config,model=model,- messages=messages,+ messages=request_messages,request_obj=data,)@@ -489,6 +510,7 @@ class OpenAIClient(LLMClientBase):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:"""Constructs a request object in the expected data format for the OpenAI API.@@ -503,6 +525,7 @@ class OpenAIClient(LLMClientBase):force_tool_call=force_tool_call,requires_subsequent_tool_call=requires_subsequent_tool_call,tool_return_truncation_chars=tool_return_truncation_chars,+ system=system,)if agent_type == AgentType.letta_v1_agent:@@ -526,10 +549,12 @@ class OpenAIClient(LLMClientBase):use_developer_message = accepts_developer_role(llm_config.model)+ request_messages = self._apply_system_override(messages, system)+openai_message_list = [cast_message_to_subtype(m)for m in PydanticMessage.to_openai_dicts_from_list(- messages,+ request_messages,put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,use_developer_message=use_developer_message,tool_return_truncation_chars=tool_return_truncation_chars,@@ -654,7 +679,7 @@ class OpenAIClient(LLMClientBase):self._apply_prompt_cache_settings(llm_config=llm_config,model=model,- messages=messages,+ messages=request_messages,request_obj=data,)diff --git a/letta/llm_api/xai_client.py b/letta/llm_api/xai_client.pyindex 072493209..64e4711cb 100644--- a/letta/llm_api/xai_client.py+++ b/letta/llm_api/xai_client.py@@ -32,8 +32,18 @@ class XAIClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# Specific bug for the mini models (as of Apr 14, 2025)# 400 - {'code': 'Client specified an invalid argument', 'error': 'Argument not supported on this model: presencePenalty'}diff --git a/letta/llm_api/zai_client.py b/letta/llm_api/zai_client.pyindex db7b77375..9a67653c8 100644--- a/letta/llm_api/zai_client.py+++ b/letta/llm_api/zai_client.py@@ -62,8 +62,18 @@ class ZAIClient(OpenAIClient):force_tool_call: Optional[str] = None,requires_subsequent_tool_call: bool = False,tool_return_truncation_chars: Optional[int] = None,+ system: Optional[str] = None,) -> dict:- data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)+ data = super().build_request_data(+ agent_type,+ messages,+ llm_config,+ tools,+ force_tool_call,+ requires_subsequent_tool_call,+ tool_return_truncation_chars,+ system,+ )# Add thinking configuration for ZAI GLM-4.5+ models# Must explicitly send type: "disabled" when reasoning is off, as GLM-4.7 has thinking on by defaultdiff --git a/letta/schemas/memory.py b/letta/schemas/memory.pyindex 60428fb8a..8fd2d2d07 100644--- a/letta/schemas/memory.py+++ b/letta/schemas/memory.py@@ -559,15 +559,9 @@ class Memory(BaseModel, validate_assignment=True):else:self._render_memory_blocks_standard(s)- # Render <available_skills> AFTER all memory blocks so it appears- # at the end of the memory section (right before <memory_metadata>).- # This prevents the surgical regex replacement in- # _update_system_message_skills() from accidentally matching literal- # <available_skills> text references inside memory block content.- if self.git_enabled:- skills_str = self.compile_available_skills(client_skills=client_skills)- if skills_str:- s.write(skills_str)+ # NOTE: available_skills is request-scoped and injected dynamically+ # by the agent at LLM request build time. It is intentionally NOT+ # persisted into compiled system prompt storage.if tool_usage_rules is not None:desc = getattr(tool_usage_rules, "description", None) or ""diff --git a/tests/integration_test_conversations_sdk.py b/tests/integration_test_conversations_sdk.pyindex 70e2fd2a1..de4471813 100644--- a/tests/integration_test_conversations_sdk.py+++ b/tests/integration_test_conversations_sdk.py@@ -192,7 +192,7 @@ class TestConversationsSDK:self._assert_system_metadata_identifiers(content=content, agent_id=agent.id, conversation_id=conversation.id)def test_client_skills_are_rendered_in_conversation_system_prompt(self, client: Letta, agent, server_url: str):- """Client skills should render into <available_skills> and remain stable across turns."""+ """Client skills are request-scoped: injected at LLM request time, never persisted to DB system message."""conversation = client.conversations.create(agent_id=agent.id)client_skills = [@@ -221,19 +221,14 @@ class TestConversationsSDK:))+ # Persisted system message should NOT contain skills (they are request-scoped only)retrieved_after_first_turn = client.conversations.retrieve(conversation_id=conversation.id)first_system_message_id = retrieved_after_first_turn.in_context_message_ids[0]first_system_content = self._get_system_message_content(server_url=server_url, message_id=first_system_message_id)- assert "<available_skills>" in first_system_content- assert "</available_skills>" in first_system_content- assert "debugging-checklist" in first_system_content- assert "Use this skill to debug stream wiring issues." in first_system_content- assert "/tmp/.skills/debugging-checklist/SKILL.md" in first_system_content- assert "api-ops" in first_system_content- assert "Operational API runbook." in first_system_content- assert "/tmp/.skills/api-ops/SKILL.md" in first_system_content+ assert "<available_skills>" not in first_system_content, "Skills should not be persisted in the DB system message"+ # Agent should still see skills at request time and respond about themassistant_messages = [m for m in response_messages if getattr(m, "message_type", None) == "assistant_message"]assert assistant_messages, "Expected at least one assistant message in response stream"@@ -241,6 +236,7 @@ class TestConversationsSDK:assert "debugging-checklist" in assistant_contentassert "api-ops" in assistant_content+ # Second turn: persisted system prompt should remain stable (no drift)list(client.conversations.messages.create(conversation_id=conversation.id,diff --git a/tests/test_letta_agent_v2_skills.py b/tests/test_letta_agent_v2_skills.pynew file mode 100644index 000000000..295d7ec07--- /dev/null+++ b/tests/test_letta_agent_v2_skills.py@@ -0,0 +1,219 @@+import re+import uuid+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from letta.agents.letta_agent_v2 import LettaAgentV2+from letta.schemas.agent import AgentState, AgentType+from letta.schemas.block import Block+from letta.schemas.embedding_config import EmbeddingConfig+from letta.schemas.enums import MessageRole+from letta.schemas.letta_message_content import TextContent+from letta.schemas.letta_request import ClientSkillSchema+from letta.schemas.llm_config import LLMConfig+from letta.schemas.memory import Memory+from letta.schemas.message import Message+from letta.schemas.user import User+++def _make_agent(memory: Memory) -> LettaAgentV2:+ actor = User(+ id=f"user-{uuid.uuid4()}",+ organization_id=f"org-{uuid.uuid4()}",+ name="test-user",+ )++ agent_state = AgentState(+ id=f"agent-{uuid.uuid4()}",+ name="skills-test-agent",+ agent_type=AgentType.letta_v1_agent,+ llm_config=LLMConfig.default_config("gpt-4o-mini"),+ embedding_config=EmbeddingConfig.default_config(provider="openai"),+ tags=[],+ memory=memory,+ system="You are a helpful assistant.",+ tools=[],+ sources=[],+ blocks=[],+ )++ with patch("letta.agents.letta_agent_v2.LLMClient.create", return_value=MagicMock()):+ return LettaAgentV2(agent_state=agent_state, actor=actor)+++def _build_memory_with_literal_tag_refs() -> Memory:+ return Memory(+ agent_type=AgentType.letta_v1_agent,+ git_enabled=True,+ blocks=[+ Block(label="system/human", value="human data", limit=500),+ Block(+ label="system/project/notes",+ value="Notes mention `<available_skills>` as literal documentation text.",+ limit=500,+ ),+ Block(label="system/persona", value="persona data", limit=500),+ ],+ )+++def _assert_one_structural_skills_block_at_tail(text: str) -> None:+ system_block_ends = [m.end() for m in re.finditer(r"</system/[^>]+>", text)]+ assert system_block_ends, "Expected system blocks in test prompt"+ tail = text[max(system_block_ends) :]+ assert tail.count("<available_skills>") == 1+ assert tail.count("</available_skills>") == 1+++def test_generate_request_system_prompt_appends_skills_and_preserves_literals():+ memory = _build_memory_with_literal_tag_refs()+ agent = _make_agent(memory=memory)+ old_text = memory.compile()++ new_skills = memory.compile_available_skills(+ client_skills=[ClientSkillSchema(name="fresh-skill", description="fresh", location="/tmp/fresh/SKILL.md")]+ )+ new_text = agent.generate_request_system_prompt(+ client_skills=[ClientSkillSchema(name="fresh-skill", description="fresh", location="/tmp/fresh/SKILL.md")],+ current_system_message=Message(role=MessageRole.system, content=[TextContent(text=old_text)], agent_id=agent.agent_state.id),+ )++ _assert_one_structural_skills_block_at_tail(new_text)+ assert "`<available_skills>`" in new_text+ assert "<name>fresh-skill</name>" in new_text+ assert new_text.rstrip().endswith(new_skills.rstrip())+++async def test_refresh_messages_does_not_repair_or_persist_system_prompt():+ memory = Memory(+ agent_type=AgentType.letta_v1_agent,+ git_enabled=True,+ blocks=[+ Block(label="system/human", value="human data", limit=500),+ Block(label="skills/agent-skill", value="agent skill data", description="agent skill", limit=500),+ ],+ )+ agent = _make_agent(memory=memory)++ stale_skills = [ClientSkillSchema(name="stale-client-skill", description="client", location="/tmp/client/SKILL.md")]+ bloated_text = memory.compile(client_skills=stale_skills)+ # Simulate historical accumulation of request-scoped skills in persisted message.+ bloated_text = bloated_text.rstrip("\n") + "\n\n" + memory.compile_available_skills(client_skills=stale_skills).lstrip("\n")+ bloated_text = bloated_text.rstrip("\n") + "\n\n" + memory.compile_available_skills(client_skills=stale_skills).lstrip("\n")++ system_message = Message(+ id=f"message-{uuid.uuid4()}",+ role=MessageRole.system,+ content=[TextContent(text=bloated_text)],+ agent_id=agent.agent_state.id,+ )+ user_message = Message(role=MessageRole.user, content=[TextContent(text="hello")], agent_id=agent.agent_state.id)++ agent.client_skills = stale_skills++ agent.message_manager.update_message_by_id_async = AsyncMock()++ refreshed_messages = await agent._refresh_messages([system_message, user_message])++ agent.message_manager.update_message_by_id_async.assert_not_called()++ final_system_text = refreshed_messages[0].content[0].text+ assert final_system_text == bloated_text+++def test_generate_request_system_prompt_includes_request_scoped_client_skills_without_mutating_storage():+ memory = _build_memory_with_literal_tag_refs()+ agent = _make_agent(memory=memory)++ old_text = memory.compile()++ system_message = Message(+ id=f"message-{uuid.uuid4()}",+ role=MessageRole.system,+ content=[TextContent(text=old_text)],+ agent_id=agent.agent_state.id,+ )++ request_system_text = agent.generate_request_system_prompt(+ client_skills=[ClientSkillSchema(name="fresh-skill", description="fresh", location="/tmp/fresh/SKILL.md")],+ current_system_message=system_message,+ )++ _assert_one_structural_skills_block_at_tail(request_system_text)+ assert "`<available_skills>`" in request_system_text+ assert "<name>fresh-skill</name>" in request_system_text+ # Ensure original persisted message object is unchanged (request-scoped only)+ assert system_message.content[0].text == old_text+++def test_generate_request_system_prompt_is_stable_for_same_stored_system_prompt():+ memory = _build_memory_with_literal_tag_refs()+ agent = _make_agent(memory=memory)++ stored_text = memory.compile()++ system_message = Message(+ id=f"message-{uuid.uuid4()}",+ role=MessageRole.system,+ content=[TextContent(text=stored_text)],+ agent_id=agent.agent_state.id,+ )++ # Repeated calls against the same stored prompt should be identical.+ request_system_text = None+ for _ in range(3):+ next_text = agent.generate_request_system_prompt(+ client_skills=[ClientSkillSchema(name="fresh-skill", description="fresh", location="/tmp/fresh/SKILL.md")],+ current_system_message=system_message,+ )+ if request_system_text is None:+ request_system_text = next_text+ else:+ assert next_text == request_system_text++ assert request_system_text is not None+ _assert_one_structural_skills_block_at_tail(request_system_text)+ assert request_system_text.count("<name>fresh-skill</name>") == 1+++async def test_rebuild_memory_does_not_persist_client_skill_block():+ memory = Memory(+ agent_type=AgentType.letta_v1_agent,+ git_enabled=True,+ blocks=[Block(label="system/human", value="human data", limit=500)],+ )+ agent = _make_agent(memory=memory)+ agent.client_skills = [ClientSkillSchema(name="client-only-skill", description="client", location="/tmp/client/SKILL.md")]++ system_message = Message(+ id=f"message-{uuid.uuid4()}",+ role=MessageRole.system,+ content=[TextContent(text="stale system prompt")],+ agent_id=agent.agent_state.id,+ )+ user_message = Message(role=MessageRole.user, content=[TextContent(text="hello")], agent_id=agent.agent_state.id)++ agent.agent_manager.refresh_memory_async = AsyncMock(return_value=agent.agent_state)+ agent.agent_manager.refresh_file_blocks = AsyncMock(return_value=agent.agent_state)+ agent.archive_manager.get_default_archive_for_agent_async = AsyncMock(return_value=None)++ async def _fake_update(message_id, message_update, actor):+ updated = system_message.model_copy(deep=True)+ updated.content = [TextContent(text=message_update.content)]+ return updated++ agent.message_manager.update_message_by_id_async = AsyncMock(side_effect=_fake_update)++ await agent._rebuild_memory(+ in_context_messages=[system_message, user_message],+ num_messages=2,+ num_archival_memories=0,+ force=True,+ )++ persisted_system_text = agent.message_manager.update_message_by_id_async.call_args.kwargs["message_update"].content+ assert "<available_skills>" not in persisted_system_text+ assert "client-only-skill" not in persisted_system_textdiff --git a/tests/test_memory.py b/tests/test_memory.pyindex e4f5fb6b5..95c7cd22d 100644--- a/tests/test_memory.py+++ b/tests/test_memory.py@@ -250,7 +250,7 @@ def test_compile_git_structured_core_memory_rendering():def test_compile_git_structured_skills_section():- """skills/ blocks should render in <available_skills> section as metadata-only entries.+ """skills/ blocks should render in compile_available_skills() as metadata-only entries.Nested skill files should NOT appear. Only top-level skill entrieswith name, description, and location.@@ -282,7 +282,7 @@ def test_compile_git_structured_skills_section():],)- out = m.compile()+ out = m.compile_available_skills()assert "<available_skills>" in outassert "</available_skills>" in out@@ -328,7 +328,7 @@ def test_compile_git_structured_archival_memory_section():def test_compile_git_structured_client_skills():- """client_skills should be merged with agent skills in <available_skills>."""+ """client_skills should be merged with agent skills in compile_available_skills()."""from letta.schemas.letta_request import ClientSkillSchemam = Memory(@@ -350,7 +350,7 @@ def test_compile_git_structured_client_skills():ClientSkillSchema(name="google", description="Google Workspace CLI.", location="skills/google/SKILL.md"),]- out = m.compile(client_skills=client_skills)+ out = m.compile_available_skills(client_skills=client_skills)# All skills (agent + client) merged in <available_skills>assert "<available_skills>" in out@@ -366,11 +366,6 @@ def test_compile_git_structured_client_skills():assert "<name>google</name>" in outassert "<description>Google Workspace CLI.</description>" in out- # <available_skills> should come after the filesystem tree- fs_end = out.find("</memory_filesystem>")- skills_start = out.find("<available_skills>")- assert skills_start > fs_end-def test_compile_git_structured_dedup_client_skills():"""client_skills with the same name as agent skills should be deduplicated (agent wins)."""@@ -389,7 +384,7 @@ def test_compile_git_structured_dedup_client_skills():ClientSkillSchema(name="my-skill", description="Client version of same skill.", location="skills/my-skill/SKILL.md"),]- out = m.compile(client_skills=client_skills)+ out = m.compile_available_skills(client_skills=client_skills)# Agent skill present, client duplicate deduplicatedassert "<available_skills>" in out@@ -416,7 +411,7 @@ def test_compile_git_structured_client_skills_omits_empty_description_location_tClientSkillSchema(name="blanky", description="", location=""),]- out = m.compile(client_skills=client_skills)+ out = m.compile_available_skills(client_skills=client_skills)assert "<available_skills>" in outassert "<name>blanky</name>" in out@@ -463,15 +458,8 @@ def test_compile_available_skills_standalone():assert m_empty.compile_available_skills(client_skills=[]) == ""-def test_compile_git_skills_rendered_after_all_blocks():- """<available_skills> must appear AFTER all memory block closing tags.-- Regression test: previously skills were rendered inside _render_memory_filesystem()- (right after </memory_filesystem>) which placed them BEFORE the memory blocks.- The surgical regex in _update_system_message_skills() could then match literal- <available_skills> text references inside block content and destroy intervening blocks.- """- from letta.schemas.letta_request import ClientSkillSchema+def test_compile_does_not_include_available_skills():+ """compile() output should never persist <available_skills> in system prompt storage."""m = Memory(agent_type=AgentType.letta_v1_agent,@@ -488,35 +476,13 @@ def test_compile_git_skills_rendered_after_all_blocks():],)- client_skills = [- ClientSkillSchema(name="test-skill", description="A test skill.", location="skills/test-skill/SKILL.md"),- ]-- out = m.compile(client_skills=client_skills)-- # All three blocks must be present with proper open+close tags- assert "<system/human.md>" in out- assert "</system/human.md>" in out- assert "<system/project/notes.md>" in out- assert "</system/project/notes.md>" in out- assert "<system/persona.md>" in out- assert "</system/persona.md>" in out-- # The structural <available_skills> block must appear AFTER the last block's closing tag- last_block_close = max(out.find("</system/human.md>"), out.find("</system/project/notes.md>"), out.find("</system/persona.md>"))- skills_start = out.rfind("<available_skills>")- assert skills_start > last_block_close, "<available_skills> should render after all memory block closing tags"-+ out = m.compile()+ assert "\n<available_skills>\n" not in out+ assert "\n</available_skills>" not in out-def test_surgical_skills_update_preserves_blocks_with_literal_skills_text():- """Simulates _update_system_message_skills() regex on a prompt where block content- contains literal <available_skills> and </available_skills> text references.- Regression test: pattern.sub() without count=1 replaced ALL matches, which- could span from a literal text reference in one block to another, destroying- all blocks in between.- """- import re+def test_append_available_skills_preserves_blocks_with_literal_skills_text():+ """Appending request-scoped skills preserves blocks with literal tag references."""from letta.schemas.letta_request import ClientSkillSchema@@ -553,27 +519,9 @@ def test_surgical_skills_update_preserves_blocks_with_literal_skills_text():ClientSkillSchema(name="test-skill", description="A test skill.", location="skills/test-skill/SKILL.md"),]- old_text = m.compile(client_skills=client_skills)-- # Verify the prompt has both literal text references AND the structural block- assert old_text.count("<available_skills>") >= 2, "Expected literal text refs + structural block"-- # Simulate the surgical update (same logic as _update_system_message_skills):- # find the structural <available_skills> by position — after all </system/...> tags.+ old_text = m.compile()new_skills = m.compile_available_skills(client_skills=client_skills)-- block_close_pattern = re.compile(r"</system/[^>]+>")- block_closes = list(block_close_pattern.finditer(old_text))- last_block_end = block_closes[-1].end() if block_closes else 0-- skills_open = old_text.find("<available_skills>", last_block_end)- skills_close = old_text.find("</available_skills>", skills_open) if skills_open >= 0 else -1- assert skills_open >= 0 and skills_close >= 0, "Should find structural <available_skills> after all blocks"-- trim_start = skills_open- while trim_start > 0 and old_text[trim_start - 1] == "\n":- trim_start -= 1- new_text = old_text[:trim_start] + new_skills + old_text[skills_close + len("</available_skills>") :]+ new_text = old_text.rstrip("\n") + "\n\n" + new_skills.lstrip("\n")# ALL blocks must survive the replacementassert "<system/human.md>" in new_text@@ -589,7 +537,7 @@ def test_surgical_skills_update_preserves_blocks_with_literal_skills_text():assert "`<available_skills>`" in new_textassert "`<available_skills>...</available_skills>`" in new_text- # The structural <available_skills> block must still be present at the end+ # The structural <available_skills> block must be present at the endstructural_start = new_text.rfind("<available_skills>")structural_end = new_text.rfind("</available_skills>")assert structural_start > 0