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(core): make preview endpoint match conversations message path exactly (#9891)

Sarah Woodersffbf23daf660
diff --git a/fern/openapi.json b/fern/openapi.json
index 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.py
index 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 request
diff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.py
index 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 LLM
diff --git a/letta/agents/letta_agent_v3.py b/letta/agents/letta_agent_v3.py
index 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 = 5000
return 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_method
async def step(
self,
diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.py
index 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.py
index 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, Optional
from uuid import uuid4
from 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.py
new file mode 100644
index 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"