Skip to content

armgit / letta

Public Imported from GitHub
0

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.py
index 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_text
diff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.py
index 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 None
for 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 refresh
in_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_method
async 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.py
index 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 None
for 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 clients
diff --git a/letta/llm_api/anthropic_client.py b/letta/llm_api/anthropic_client.py
index 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 level
if 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].text
data["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.py
index 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.model
diff --git a/letta/llm_api/bedrock_client.py b/letta/llm_api/bedrock_client.py
index 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.py
index 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 LLMClientBase
from letta.log import get_logger
from letta.otel.tracing import trace_method
from letta.schemas.enums import AgentType, ProviderCategory
+from letta.schemas.letta_message_content import TextContent
from letta.schemas.llm_config import LLMConfig
from letta.schemas.message import Message as PydanticMessage
from 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 format
input_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.py
index 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.py
index 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 models
if self.is_reasoning_model(llm_config):
diff --git a/letta/llm_api/google_vertex_client.py b/letta/llm_api/google_vertex_client.py
index 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_logger
from letta.otel.tracing import trace_method
from letta.schemas.agent import AgentType
from letta.schemas.enums import ProviderCategory
+from letta.schemas.letta_message_content import TextContent
from letta.schemas.llm_config import LLMConfig
from letta.schemas.message import Message as PydanticMessage
from 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.py
index 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.py
index 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.py
index 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: 1
diff --git a/letta/llm_api/openai_client.py b/letta/llm_api/openai_client.py
index 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_method
from letta.schemas.agent import AgentType
from letta.schemas.embedding_config import EmbeddingConfig
from letta.schemas.enums import ProviderCategory
-from letta.schemas.letta_message_content import MessageContentType
+from letta.schemas.letta_message_content import MessageContentType, TextContent
from letta.schemas.llm_config import LLMConfig
from letta.schemas.message import Message as PydanticMessage
from 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_method
def 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.py
index 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.py
index 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 default
diff --git a/letta/schemas/memory.py b/letta/schemas/memory.py
index 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.py
index 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 them
assistant_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_content
assert "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.py
new file mode 100644
index 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_text
diff --git a/tests/test_memory.py b/tests/test_memory.py
index 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 entries
with 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 out
assert "</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 ClientSkillSchema
m = 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 out
assert "<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 deduplicated
assert "<available_skills>" in out
@@ -416,7 +411,7 @@ def test_compile_git_structured_client_skills_omits_empty_description_location_t
ClientSkillSchema(name="blanky", description="", location=""),
]
- out = m.compile(client_skills=client_skills)
+ out = m.compile_available_skills(client_skills=client_skills)
assert "<available_skills>" in out
assert "<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 replacement
assert "<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_text
assert "`<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 end
structural_start = new_text.rfind("<available_skills>")
structural_end = new_text.rfind("</available_skills>")
assert structural_start > 0