Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add credit verification before agent message endpoints [LET-XXXX] (#9433)
Ari Webb0a8a8fda54b8
diff --git a/fern/openapi.json b/fern/openapi.jsonindex 51602e951..2d3d3831b 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -43877,6 +43877,7 @@"no_tool_call","tool_rule","cancelled",+ "insufficient_credits","requires_approval","context_window_overflow_in_system_prompt"],diff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.pyindex 2c0bf6ca7..02ed2e469 100644--- a/letta/agents/letta_agent_v2.py+++ b/letta/agents/letta_agent_v2.py@@ -20,7 +20,7 @@ from letta.agents.helpers import (generate_step_id,)from letta.constants import DEFAULT_MAX_STEPS, NON_USER_MSG_PREFIX, REQUEST_HEARTBEAT_PARAM-from letta.errors import ContextWindowExceededError, LLMError+from letta.errors import ContextWindowExceededError, InsufficientCreditsError, LLMErrorfrom letta.helpers import ToolRulesSolverfrom letta.helpers.datetime_helpers import get_utc_time, get_utc_timestamp_ns, ns_to_msfrom letta.helpers.reasoning_helper import scrub_inner_thoughts_from_messages@@ -58,6 +58,7 @@ from letta.server.rest_api.utils import (from letta.services.agent_manager import AgentManagerfrom letta.services.archive_manager import ArchiveManagerfrom letta.services.block_manager import BlockManager+from letta.services.credit_verification_service import CreditVerificationServicefrom letta.services.helpers.tool_parser_helper import runtime_override_tool_json_schemafrom letta.services.message_manager import MessageManagerfrom letta.services.passage_manager import PassageManager@@ -70,7 +71,7 @@ from letta.services.tool_executor.tool_execution_manager import ToolExecutionManfrom letta.settings import model_settings, settings, summarizer_settingsfrom letta.system import package_function_responsefrom letta.types import JsonDict-from letta.utils import log_telemetry, safe_create_task, united_diff, validate_function_response+from letta.utils import log_telemetry, safe_create_task, safe_create_task_with_return, united_diff, validate_function_responseclass LettaAgentV2(BaseAgentV2):@@ -106,6 +107,7 @@ class LettaAgentV2(BaseAgentV2):self.passage_manager = PassageManager()self.step_manager = StepManager()self.telemetry_manager = TelemetryManager()+ self.credit_verification_service = CreditVerificationService()## TODO: Expand to more# if summarizer_settings.enable_summarization and model_settings.openai_api_key:@@ -209,9 +211,18 @@ class LettaAgentV2(BaseAgentV2):)in_context_messages = in_context_messages + input_messages_to_persistresponse_letta_messages = []+ credit_task = Nonefor i in range(max_steps):remaining_turns = max_steps - i - 1+ # Await credit check from previous iteration before running next step+ if credit_task is not None:+ if not await credit_task:+ self.should_continue = False+ self.stop_reason = LettaStopReason(stop_reason=StopReasonType.insufficient_credits)+ break+ credit_task = None+response = self._step(messages=in_context_messages + self.response_messages,input_messages_to_persist=input_messages_to_persist,@@ -238,6 +249,9 @@ class LettaAgentV2(BaseAgentV2):if not self.should_continue:break+ # Fire credit check to run in parallel with loop overhead / next step setup+ credit_task = safe_create_task_with_return(self._check_credits())+input_messages_to_persist = []# Rebuild context window after stepping@@ -332,7 +346,16 @@ class LettaAgentV2(BaseAgentV2):input_messages, self.agent_state, self.message_manager, self.actor, run_id)in_context_messages = in_context_messages + input_messages_to_persist+ credit_task = Nonefor i in range(max_steps):+ # Await credit check from previous iteration before running next step+ if credit_task is not None:+ if not await credit_task:+ self.should_continue = False+ self.stop_reason = LettaStopReason(stop_reason=StopReasonType.insufficient_credits)+ break+ credit_task = None+response = self._step(messages=in_context_messages + self.response_messages,input_messages_to_persist=input_messages_to_persist,@@ -351,6 +374,9 @@ class LettaAgentV2(BaseAgentV2):if not self.should_continue:break+ # Fire credit check to run in parallel with loop overhead / next step setup+ credit_task = safe_create_task_with_return(self._check_credits())+input_messages_to_persist = []if self.stop_reason is None:@@ -676,6 +702,15 @@ class LettaAgentV2(BaseAgentV2):self.last_function_response = Noneself.response_messages = []+ async def _check_credits(self) -> bool:+ """Check if the organization still has credits. Returns True if OK or not configured."""+ try:+ await self.credit_verification_service.verify_credits(self.actor.organization_id)+ return True+ except InsufficientCreditsError:+ self.logger.warning(f"Insufficient credits for organization {self.actor.organization_id}, stopping agent loop")+ return False+@trace_methodasync def _check_run_cancellation(self, run_id) -> bool:try:diff --git a/letta/agents/letta_agent_v3.py b/letta/agents/letta_agent_v3.pyindex db1a7df52..480c9e747 100644--- a/letta/agents/letta_agent_v3.py+++ b/letta/agents/letta_agent_v3.py@@ -1,4 +1,3 @@-import asyncioimport jsonimport uuidfrom typing import Any, AsyncGenerator, Dict, Literal, Optional@@ -65,7 +64,7 @@ from letta.services.summarizer.summarizer_config import CompactionSettingsfrom letta.services.summarizer.summarizer_sliding_window import count_tokensfrom letta.settings import settings, summarizer_settingsfrom letta.system import package_function_response, package_summarize_message_no_counts-from letta.utils import log_telemetry, validate_function_response+from letta.utils import log_telemetry, safe_create_task_with_return, validate_function_responsedef extract_compaction_stats_from_message(message: Message) -> CompactionStats | None:@@ -237,11 +236,20 @@ class LettaAgentV3(LettaAgentV2):user_id=self.actor.id,)+ credit_task = Nonefor i in range(max_steps):if i == 1 and follow_up_messages:input_messages_to_persist = follow_up_messagesfollow_up_messages = []+ # Await credit check from previous iteration before running next step+ if credit_task is not None:+ if not await credit_task:+ self.should_continue = False+ self.stop_reason = LettaStopReason(stop_reason=StopReasonType.insufficient_credits)+ break+ credit_task = None+response = self._step(# we append input_messages_to_persist since they aren't checkpointed as in-context until the end of the step (may be rolled back)messages=list(self.in_context_messages + input_messages_to_persist),@@ -289,6 +297,9 @@ class LettaAgentV3(LettaAgentV2):if not self.should_continue:break+ # Fire credit check to run in parallel with loop overhead / next step setup+ credit_task = safe_create_task_with_return(self._check_credits())+# input_messages_to_persist = []if i == max_steps - 1 and self.stop_reason is None:@@ -453,10 +464,20 @@ class LettaAgentV3(LettaAgentV2):input_messages_to_persist = [input_messages_to_persist[0]]self.in_context_messages = in_context_messages+ credit_task = Nonefor i in range(max_steps):if i == 1 and follow_up_messages:input_messages_to_persist = follow_up_messagesfollow_up_messages = []++ # Await credit check from previous iteration before running next step+ if credit_task is not None:+ if not await credit_task:+ self.should_continue = False+ self.stop_reason = LettaStopReason(stop_reason=StopReasonType.insufficient_credits)+ break+ credit_task = None+response = self._step(# we append input_messages_to_persist since they aren't checkpointed as in-context until the end of the step (may be rolled back)messages=list(self.in_context_messages + input_messages_to_persist),@@ -486,6 +507,9 @@ class LettaAgentV3(LettaAgentV2):if not self.should_continue:break+ # Fire credit check to run in parallel with loop overhead / next step setup+ credit_task = safe_create_task_with_return(self._check_credits())+if i == max_steps - 1 and self.stop_reason is None:self.stop_reason = LettaStopReason(stop_reason=StopReasonType.max_steps.value)diff --git a/letta/errors.py b/letta/errors.pyindex ccf98125f..5795ef696 100644--- a/letta/errors.py+++ b/letta/errors.py@@ -451,6 +451,16 @@ class AgentFileImportError(Exception):"""Exception raised during agent file import operations"""+class InsufficientCreditsError(LettaError):+ """Raised when an organization has no remaining credits."""++ def __init__(self):+ super().__init__(+ message="Insufficient credits to process this request.",+ details={"error_code": "INSUFFICIENT_CREDITS"},+ )++class RunCancelError(LettaError):"""Error raised when a run cannot be cancelled."""diff --git a/letta/schemas/letta_stop_reason.py b/letta/schemas/letta_stop_reason.pyindex abb28aa7e..81c8ac3ec 100644--- a/letta/schemas/letta_stop_reason.py+++ b/letta/schemas/letta_stop_reason.py@@ -17,6 +17,7 @@ class StopReasonType(str, Enum):no_tool_call = "no_tool_call"tool_rule = "tool_rule"cancelled = "cancelled"+ insufficient_credits = "insufficient_credits"requires_approval = "requires_approval"context_window_overflow_in_system_prompt = "context_window_overflow_in_system_prompt"@@ -42,6 +43,8 @@ class StopReasonType(str, Enum):return RunStatus.failedelif self == StopReasonType.cancelled:return RunStatus.cancelled+ elif self == StopReasonType.insufficient_credits:+ return RunStatus.failedelse:raise ValueError("Unknown StopReasonType")diff --git a/letta/services/credit_verification_service.py b/letta/services/credit_verification_service.pynew file mode 100644index 000000000..cf4977e7f--- /dev/null+++ b/letta/services/credit_verification_service.py@@ -0,0 +1,56 @@+import logging+import os++import httpx++from letta.errors import InsufficientCreditsError++logger = logging.getLogger(__name__)+++class CreditVerificationService:+ """Service for verifying organization credit balance before agent execution."""++ def __init__(self):+ self.endpoint = os.getenv("STEP_ORCHESTRATOR_ENDPOINT")+ self.auth_key = os.getenv("STEP_COMPLETE_KEY")++ async def verify_credits(self, organization_id: str) -> bool:+ """+ Check if an organization has enough credits to proceed.++ Returns True if credits are available or if the service is not configured.+ Raises InsufficientCreditsError if no credits remain.+ """+ if not self.endpoint or not self.auth_key:+ return True++ try:+ headers = {}+ if self.auth_key:+ headers["Authorization"] = f"Bearer {self.auth_key}"++ async with httpx.AsyncClient(timeout=5.0) as client:+ response = await client.get(+ f"{self.endpoint}/validate/core-organizations/{organization_id}",+ headers=headers,+ )+ response.raise_for_status()++ data = response.json()+ if not data.get("hasMoreCredits", True):+ raise InsufficientCreditsError()++ return True++ except InsufficientCreditsError:+ raise+ except httpx.TimeoutException:+ logger.warning(f"Timeout verifying credits for organization {organization_id}")+ return True+ except httpx.HTTPStatusError as e:+ logger.warning(f"HTTP error verifying credits for organization {organization_id}: {e.response.status_code}")+ return True+ except Exception as e:+ logger.error(f"Unexpected error verifying credits for organization {organization_id}: {e}")+ return True