Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
fix(core): make preview endpoint match conversations message path exactly (#9891)
Sarah Woodersffbf23daf660
diff --git a/fern/openapi.json b/fern/openapi.jsonindex b88fbcf90..2dde1ada6 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -9240,6 +9240,69 @@}}},+ "/v1/conversations/{conversation_id}/messages/preview-raw-payload": {+ "post": {+ "tags": ["conversations"],+ "summary": "Preview Conversation Model Request",+ "description": "Inspect the raw LLM request payload for a conversation message without sending it.\n\nThis endpoint processes the message through the same path as send_conversation_message\n(including conversation-scoped messages, isolated blocks, model overrides, and\nclient tools/skills) but stops before the LLM call and returns the raw request\npayload. Useful for debugging and verifying what the LLM will actually see.",+ "operationId": "preview_conversation_model_request",+ "parameters": [+ {+ "name": "conversation_id",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "minLength": 1,+ "maxLength": 42,+ "pattern": "^(default|conv-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|agent-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$",+ "description": "The conversation identifier. Can be a conversation ID ('conv-<uuid4>'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-<uuid4>') for backwards compatibility (deprecated).",+ "examples": [+ "default",+ "conv-123e4567-e89b-42d3-8456-426614174000",+ "agent-123e4567-e89b-42d3-8456-426614174000"+ ],+ "title": "Conversation Id"+ },+ "description": "The conversation identifier. Can be a conversation ID ('conv-<uuid4>'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-<uuid4>') for backwards compatibility (deprecated)."+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ConversationMessageRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful Response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "additionalProperties": true,+ "title": "Response Preview Conversation Model Request"+ }+ }+ }+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ }+ }+ },"/v1/conversations/{conversation_id}/stream": {"post": {"tags": ["conversations"],diff --git a/letta/agents/base_agent_v2.py b/letta/agents/base_agent_v2.pyindex 2c89a3373..067917f5f 100644--- a/letta/agents/base_agent_v2.py+++ b/letta/agents/base_agent_v2.py@@ -37,6 +37,8 @@ class BaseAgentV2(ABC):self,input_messages: list[MessageCreate],client_skills: list["ClientSkillSchema"] | None = None,+ client_tools: list["ClientToolSchema"] | None = None,+ conversation_id: str | None = None,) -> dict:"""Execute the agent loop in dry_run mode, returning just the generated requestdiff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.pyindex 0d8020e2b..d5f93dc35 100644--- a/letta/agents/letta_agent_v2.py+++ b/letta/agents/letta_agent_v2.py@@ -138,7 +138,13 @@ class LettaAgentV2(BaseAgentV2):)@trace_method- async def build_request(self, input_messages: list[MessageCreate], client_skills: list[ClientSkillSchema] | None = None) -> dict:+ async def build_request(+ self,+ input_messages: list[MessageCreate],+ client_skills: list[ClientSkillSchema] | None = None,+ client_tools: list[ClientToolSchema] | None = None,+ conversation_id: str | None = None,+ ) -> dict:"""Build the request data for an LLM call without actually executing it.@@ -146,6 +152,9 @@ class LettaAgentV2(BaseAgentV2):Args:input_messages: List of new messages to process+ client_skills: Optional client-side skills to include in system prompt+ client_tools: Optional client-side tools to include in tool list (V2 ignores, V3 uses)+ conversation_id: Optional conversation ID (V2 ignores, V3 uses for scoped context)Returns:dict: The request data that would be sent to the LLMdiff --git a/letta/agents/letta_agent_v3.py b/letta/agents/letta_agent_v3.pyindex 92184ca43..068a840c2 100644--- a/letta/agents/letta_agent_v3.py+++ b/letta/agents/letta_agent_v3.py@@ -151,6 +151,70 @@ class LettaAgentV3(LettaAgentV2):cap = 5000return max(5000, cap)+ @trace_method+ async def build_request(+ self,+ input_messages: list[MessageCreate],+ client_skills: list[ClientSkillSchema] | None = None,+ client_tools: list[ClientToolSchema] | None = None,+ conversation_id: str | None = None,+ ) -> dict:+ """+ Build the request data for an LLM call without actually executing it.++ Overrides V2 to support conversation-scoped messages, conversation-isolated+ blocks, and client-side tools — matching the real execution path in step().++ Args:+ input_messages: List of new messages to process+ client_skills: Optional client-side skills to include in system prompt+ client_tools: Optional client-side tools to merge into tool list+ conversation_id: Optional conversation ID for conversation-scoped context++ Returns:+ dict: The request data that would be sent to the LLM+ """+ from letta.adapters.letta_llm_request_adapter import LettaLLMRequestAdapter++ self._initialize_state()+ self.client_tools = client_tools or []+ self.client_skills = client_skills or []+ self.conversation_id = conversation_id++ # Apply conversation-specific block overrides (same as step())+ if conversation_id:+ self.agent_state = await ConversationManager().apply_isolated_blocks_to_agent_state(+ agent_state=self.agent_state,+ conversation_id=conversation_id,+ actor=self.actor,+ )++ in_context_messages, input_messages_to_persist = await _prepare_in_context_messages_no_persist_async(+ input_messages, self.agent_state, self.message_manager, self.actor, None, conversation_id=conversation_id+ )++ response = self._step(+ run_id=None,+ messages=in_context_messages + input_messages_to_persist,+ llm_adapter=LettaLLMRequestAdapter(+ llm_client=self.llm_client,+ llm_config=self.agent_state.llm_config,+ call_type=LLMCallType.agent_step,+ agent_id=self.agent_state.id,+ agent_tags=self.agent_state.tags,+ org_id=self.actor.organization_id,+ user_id=self.actor.id,+ ),+ dry_run=True,+ enforce_run_id_set=False,+ )+ request = {}+ async for chunk in response:+ request = chunk+ break++ return request+@trace_methodasync def step(self,diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex eac433645..88b0325f0 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -2370,12 +2370,20 @@ async def preview_model_request("""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)agent = await server.agent_manager.get_agent_by_id_async(- agent_id, actor, include_relationships=["multi_agent_group", "memory", "sources"]+ agent_id,+ actor,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],)++ if request.override_model:+ override_llm_config = await server.get_llm_config_from_handle_async(actor=actor, handle=request.override_model)+ agent = agent.model_copy(update={"llm_config": override_llm_config})+agent_loop = AgentLoop.load(agent_state=agent, actor=actor)return await agent_loop.build_request(input_messages=request.messages,client_skills=request.client_skills,+ client_tools=request.client_tools,)diff --git a/letta/server/rest_api/routers/v1/conversations.py b/letta/server/rest_api/routers/v1/conversations.pyindex 5532bac1f..303020ef2 100644--- a/letta/server/rest_api/routers/v1/conversations.py+++ b/letta/server/rest_api/routers/v1/conversations.py@@ -1,5 +1,5 @@from datetime import timedelta-from typing import Annotated, List, Literal, Optional+from typing import Annotated, Any, Dict, List, Literal, Optionalfrom uuid import uuid4from fastapi import APIRouter, Body, Depends, HTTPException, Query, status@@ -479,6 +479,97 @@ async def send_conversation_message()+ "/{conversation_id}/messages/preview-raw-payload",+ response_model=Dict[str, Any],+ operation_id="preview_conversation_model_request",+)+async def preview_conversation_model_request(+ conversation_id: ConversationIdOrDefault,+ request: ConversationMessageRequest = Body(...),+ server: SyncServer = Depends(get_letta_server),+ headers: HeaderParams = Depends(get_headers),+):+ """+ Inspect the raw LLM request payload for a conversation message without sending it.++ This endpoint processes the message through the same path as send_conversation_message+ (including conversation-scoped messages, isolated blocks, model overrides, and+ client tools/skills) but stops before the LLM call and returns the raw request+ payload. Useful for debugging and verifying what the LLM will actually see.+ """+ actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)++ if not request.messages or len(request.messages) == 0:+ raise HTTPException(status_code=422, detail="Messages must not be empty")++ # Agent-direct mode (same logic as send_conversation_message)+ resolved_agent_id = None+ if conversation_id == "default" and request.agent_id:+ resolved_agent_id = request.agent_id+ elif conversation_id.startswith("agent-"):+ resolved_agent_id = conversation_id++ if resolved_agent_id:+ # Agent-direct mode: load agent directly, no conversation features+ agent = await server.agent_manager.get_agent_by_id_async(+ resolved_agent_id,+ actor,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],+ )++ if request.override_model:+ override_llm_config = await server.get_llm_config_from_handle_async(actor=actor, handle=request.override_model)+ agent = agent.model_copy(update={"llm_config": override_llm_config})++ agent_loop = AgentLoop.load(agent_state=agent, actor=actor)+ return await agent_loop.build_request(+ input_messages=request.messages,+ client_skills=request.client_skills,+ client_tools=request.client_tools,+ )++ # Normal conversation mode+ conversation = await conversation_manager.get_conversation_by_id(+ conversation_id=conversation_id,+ actor=actor,+ )++ agent = await server.agent_manager.get_agent_by_id_async(+ conversation.agent_id,+ actor,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],+ )++ # Apply conversation-level model override (same as send_conversation_message)+ if conversation.model and not request.override_model:+ conversation_llm_config = await server.get_llm_config_from_handle_async(+ actor=actor,+ handle=conversation.model,+ )+ if conversation.model_settings is not None:+ update_params = conversation.model_settings._to_legacy_config_params()+ if "max_output_tokens" not in conversation.model_settings.model_fields_set:+ update_params.pop("max_tokens", None)+ conversation_llm_config = conversation_llm_config.model_copy(update=update_params)+ agent = agent.model_copy(update={"llm_config": conversation_llm_config})++ if request.override_model:+ override_llm_config = await server.get_llm_config_from_handle_async(+ actor=actor,+ handle=request.override_model,+ )+ agent = agent.model_copy(update={"llm_config": override_llm_config})++ agent_loop = AgentLoop.load(agent_state=agent, actor=actor)+ return await agent_loop.build_request(+ input_messages=request.messages,+ client_skills=request.client_skills,+ client_tools=request.client_tools,+ conversation_id=conversation_id,+ )++@router.post("/{conversation_id}/stream",response_model=None,diff --git a/tests/test_preview_accuracy.py b/tests/test_preview_accuracy.pynew file mode 100644index 000000000..31a3b0f8a--- /dev/null+++ b/tests/test_preview_accuracy.py@@ -0,0 +1,273 @@+"""+Test that build_request() (preview) produces the exact same LLM request+payload as step() (actual message sending).++Verifies the invariant: the preview endpoint returns what the LLM would+actually receive during a real conversation message.+"""++import copy+import uuid++import pytest++from letta.agents.agent_loop import AgentLoop+from letta.agents.helpers import _prepare_in_context_messages_no_persist_async+from letta.config import LettaConfig+from letta.schemas.agent import CreateAgent+from letta.schemas.block import CreateBlock+from letta.schemas.conversation import CreateConversation+from letta.schemas.embedding_config import EmbeddingConfig+from letta.schemas.enums import LLMCallType, MessageRole+from letta.schemas.letta_request import ClientSkillSchema, ClientToolSchema+from letta.schemas.llm_config import LLMConfig+from letta.schemas.message import MessageCreate+from letta.server.server import SyncServer+from letta.services.conversation_manager import ConversationManager++[email protected](scope="module")+def server():+ config = LettaConfig.load()+ config.save()+ return SyncServer(init_with_default_org_and_user=False)+++async def default_organization(server):+ org = await server.organization_manager.create_default_organization_async()+ yield org+++async def default_user(server, default_organization):+ user = await server.user_manager.create_default_actor_async(org_id=default_organization.id)+ await server.tool_manager.upsert_base_tools_async(actor=user)+ yield user+++async def agent_with_conversation(server, default_user):+ """Create a letta_v1_agent (V3) with memory blocks, tools, and a conversation."""+ agent_state = await server.agent_manager.create_agent_async(+ agent_create=CreateAgent(+ name=f"preview_test_{uuid.uuid4().hex[:8]}",+ agent_type="letta_v1_agent",+ memory_blocks=[+ CreateBlock(label="human", value="Test user named Alice"),+ CreateBlock(label="persona", value="I am a helpful test assistant."),+ ],+ llm_config=LLMConfig.default_config("gpt-4o-mini"),+ embedding_config=EmbeddingConfig.default_config(provider="openai"),+ include_base_tools=True,+ ),+ actor=default_user,+ )++ conversation_manager = ConversationManager()+ conversation = await conversation_manager.create_conversation(+ agent_id=agent_state.id,+ conversation_create=CreateConversation(),+ actor=default_user,+ )++ yield agent_state, conversation++ await server.agent_manager.delete_agent_async(agent_id=agent_state.id, actor=default_user)+++class TestPreviewAccuracy:+ """Verify that build_request() produces the same LLM payload as step()."""++ @pytest.mark.asyncio+ async def test_preview_matches_step_request_data(self, server, default_user, agent_with_conversation):+ """+ Call build_request() (the preview path) and then replicate the exact+ setup that step() performs before calling _step(dry_run=True).+ Both should produce identical request payloads.++ This validates that build_request() faithfully mirrors step()'s+ agent state setup: conversation isolation, client_tools, client_skills,+ conversation-scoped messages, and _initialize_state().+ """+ agent_state, conversation = agent_with_conversation++ # Load agent with the same relationships the router loads+ agent = await server.agent_manager.get_agent_by_id_async(+ agent_state.id,+ default_user,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],+ )++ input_messages = [MessageCreate(role=MessageRole.user, content="Hello, what can you do?")]+ client_skills = [+ ClientSkillSchema(name="test-skill", description="A test skill for debugging", location="/tmp/test-skill/SKILL.md"),+ ]+ client_tools = [+ ClientToolSchema(+ name="client_search",+ description="Search the web",+ parameters={"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]},+ ),+ ]++ # ── 1. Preview path: build_request() ──+ from letta.adapters.letta_llm_request_adapter import LettaLLMRequestAdapter++ preview_loop = AgentLoop.load(agent_state=copy.deepcopy(agent), actor=default_user)+ preview_payload = await preview_loop.build_request(+ input_messages=input_messages,+ client_skills=client_skills,+ client_tools=client_tools,+ conversation_id=conversation.id,+ )++ # ── 2. Step path: replicate step()'s setup, then dry_run ──+ # This mirrors what LettaAgentV3.step() does before entering _step().+ step_loop = AgentLoop.load(agent_state=copy.deepcopy(agent), actor=default_user)+ step_loop._initialize_state()+ step_loop.client_tools = client_tools or []+ step_loop.client_skills = client_skills or []+ step_loop.conversation_id = conversation.id++ # Apply conversation-specific block overrides (same as step())+ step_loop.agent_state = await ConversationManager().apply_isolated_blocks_to_agent_state(+ agent_state=step_loop.agent_state,+ conversation_id=conversation.id,+ actor=default_user,+ )++ # Load conversation-scoped messages (same as step())+ in_context_messages, input_messages_to_persist = await _prepare_in_context_messages_no_persist_async(+ input_messages,+ step_loop.agent_state,+ step_loop.message_manager,+ default_user,+ None,+ conversation_id=conversation.id,+ )++ # Call _step with dry_run=True — identical to what step() would do+ # right before the LLM call+ step_response = step_loop._step(+ run_id=None,+ messages=in_context_messages + input_messages_to_persist,+ llm_adapter=LettaLLMRequestAdapter(+ llm_client=step_loop.llm_client,+ llm_config=step_loop.agent_state.llm_config,+ call_type=LLMCallType.agent_step,+ agent_id=step_loop.agent_state.id,+ agent_tags=step_loop.agent_state.tags,+ org_id=default_user.organization_id,+ user_id=default_user.id,+ ),+ dry_run=True,+ enforce_run_id_set=False,+ )+ step_payload = {}+ async for chunk in step_response:+ step_payload = chunk+ break++ # ── 3. Compare ──+ assert preview_payload == step_payload, (+ "Preview payload diverged from step payload. build_request() must mirror step()'s agent state setup exactly."+ )++ @pytest.mark.asyncio+ async def test_preview_contains_client_skills_and_tools(self, server, default_user, agent_with_conversation):+ """+ Verify the preview payload actually includes client_skills in the system+ prompt and client_tools in the tool list.+ """+ agent_state, conversation = agent_with_conversation++ agent = await server.agent_manager.get_agent_by_id_async(+ agent_state.id,+ default_user,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],+ )++ input_messages = [MessageCreate(role=MessageRole.user, content="Hello")]+ client_skills = [+ ClientSkillSchema(name="my-special-skill", description="Does special things", location="/skills/my-special-skill/SKILL.md"),+ ]+ client_tools = [+ ClientToolSchema(+ name="my_client_tool",+ description="A tool the client provides",+ parameters={"type": "object", "properties": {"arg": {"type": "string"}}},+ ),+ ]++ agent_loop = AgentLoop.load(agent_state=copy.deepcopy(agent), actor=default_user)+ payload = await agent_loop.build_request(+ input_messages=input_messages,+ client_skills=client_skills,+ client_tools=client_tools,+ conversation_id=conversation.id,+ )++ # Verify client_skills appear in the system message+ messages = payload.get("messages", [])+ assert len(messages) > 0, "Payload should contain messages"++ system_message = messages[0]+ system_content = ""+ if isinstance(system_message.get("content"), str):+ system_content = system_message["content"]+ elif isinstance(system_message.get("content"), list):+ system_content = " ".join(+ block.get("text", "") for block in system_message["content"] if isinstance(block, dict) and block.get("type") == "text"+ )++ assert "my-special-skill" in system_content, "Client skill should appear in system prompt"+ assert "<available_skills>" in system_content, "Skills section should be present in system prompt"++ # Verify client_tools appear in the tool list+ tools = payload.get("tools", [])+ tool_names = [t.get("function", {}).get("name") or t.get("name", "") for t in tools]+ assert "my_client_tool" in tool_names, f"Client tool should appear in tool list, got: {tool_names}"++ @pytest.mark.asyncio+ async def test_preview_without_conversation_uses_agent_messages(self, server, default_user, agent_with_conversation):+ """+ When no conversation_id is passed, build_request() should load messages+ from the agent's message_ids (not conversation-scoped).+ """+ agent_state, _ = agent_with_conversation++ agent = await server.agent_manager.get_agent_by_id_async(+ agent_state.id,+ default_user,+ include_relationships=["memory", "multi_agent_group", "sources", "tool_exec_environment_variables", "tools", "tags"],+ )++ input_messages = [MessageCreate(role=MessageRole.user, content="Hello")]++ # Preview without conversation_id+ agent_loop = AgentLoop.load(agent_state=copy.deepcopy(agent), actor=default_user)+ payload = await agent_loop.build_request(+ input_messages=input_messages,+ conversation_id=None, # No conversation — uses agent-scoped messages+ )++ messages = payload.get("messages", [])+ assert len(messages) >= 2, "Should have at least system message + user message"++ # Preview with conversation_id+ _, conversation = agent_with_conversation+ agent_loop2 = AgentLoop.load(agent_state=copy.deepcopy(agent), actor=default_user)+ payload_with_conv = await agent_loop2.build_request(+ input_messages=input_messages,+ conversation_id=conversation.id,+ )++ messages_with_conv = payload_with_conv.get("messages", [])+ assert len(messages_with_conv) >= 2, "Should have at least system message + user message"++ # The system messages should differ because conversation-scoped system+ # messages include CONVERSATION_ID in metadata+ system_no_conv = str(messages[0])+ system_with_conv = str(messages_with_conv[0])+ assert system_no_conv != system_with_conv, "Conversation-scoped system message should differ from agent-scoped"