Merge branch 'main' into voyageai_context_and_multimodal

Author: fzowl

.github/workflows/core-unit-test.yml

@@ -47,6 +47,7 @@ jobs:
               {"test_suite": "test_llm_clients.py"},
               {"test_suite": "test_letta_agent_batch.py"},
               {"test_suite": "test_providers.py"},
+              {"test_suite": "test_server_providers.py"},
               {"test_suite": "test_sources.py"},
               {"test_suite": "sdk/"},
               {"test_suite": "mcp_tests/"},

.github/workflows/send-message-integration-tests.yml

@@ -37,8 +37,8 @@ jobs:
           "matrix": {
             "config_file": [
               "openai-gpt-4o-mini.json",
+              "claude-4-5-sonnet.json",
               "claude-4-sonnet-extended.json",
-              "claude-3-5-sonnet.json",
               "claude-3-7-sonnet-extended.json",
               "gemini-1.5-pro.json",
               "gemini-2.5-pro.json",

README.md

@@ -43,13 +43,14 @@ In the example below, we'll create a stateful agent with two memory blocks, one
 ### Python
 ```python
 from letta_client import Letta
+import os
 
-client = Letta(token="LETTA_API_KEY")
-# client = Letta(base_url="http://localhost:8283")  # if self-hosting, set your base_url
+# Connect to Letta Cloud (get your API key at https://app.letta.com/api-keys)
+client = Letta(token=os.getenv("LETTA_API_KEY"))
+# client = Letta(base_url="http://localhost:8283", embedding="openai/text-embedding-3-small")  # if self-hosting, set base_url and embedding
 
 agent_state = client.agents.create(
     model="openai/gpt-4.1",
-    embedding="openai/text-embedding-3-small",
     memory_blocks=[
         {
           "label": "human",
@@ -85,12 +86,12 @@ for message in response.messages:
 ```typescript
 import { LettaClient } from '@letta-ai/letta-client'
 
-const client = new LettaClient({ token: "LETTA_API_KEY" });
-// const client = new LettaClient({ baseUrl: "http://localhost:8283" });  // if self-hosting, set your baseUrl
+// Connect to Letta Cloud (get your API key at https://app.letta.com/api-keys)
+const client = new LettaClient({ token: process.env.LETTA_API_KEY });
+// const client = new LettaClient({ baseUrl: "http://localhost:8283", embedding: "openai/text-embedding-3-small" });  // if self-hosting
 
 const agentState = await client.agents.create({
     model: "openai/gpt-4.1",
-    embedding: "openai/text-embedding-3-small",
     memoryBlocks: [
         {
           label: "human",
@@ -150,7 +151,6 @@ shared_block = client.blocks.create(
 # create a supervisor agent
 supervisor_agent = client.agents.create(
     model="anthropic/claude-3-5-sonnet-20241022",
-    embedding="openai/text-embedding-3-small",
     # blocks created for this agent
     memory_blocks=[{"label": "persona", "value": "I am a supervisor"}],
     # pre-existing shared block that is "attached" to this agent
@@ -160,7 +160,6 @@ supervisor_agent = client.agents.create(
 # create a worker agent
 worker_agent = client.agents.create(
     model="openai/gpt-4.1-mini",
-    embedding="openai/text-embedding-3-small",
     # blocks created for this agent
     memory_blocks=[{"label": "persona", "value": "I am a worker"}],
     # pre-existing shared block that is "attached" to this agent
@@ -180,7 +179,6 @@ const sharedBlock = await client.blocks.create({
 // create a supervisor agent
 const supervisorAgent = await client.agents.create({
     model: "anthropic/claude-3-5-sonnet-20241022",
-    embedding: "openai/text-embedding-3-small",
     // blocks created for this agent
     memoryBlocks: [{ label: "persona", value: "I am a supervisor" }],
     // pre-existing shared block that is "attached" to this agent
@@ -190,7 +188,6 @@ const supervisorAgent = await client.agents.create({
 // create a worker agent
 const workerAgent = await client.agents.create({
     model: "openai/gpt-4.1-mini",
-    embedding: "openai/text-embedding-3-small",
     // blocks created for this agent
     memoryBlocks: [{ label: "persona", value: "I am a worker" }],
     // pre-existing shared block that is "attached" to this agent
@@ -277,7 +274,6 @@ tool = client.tools.add_mcp_tool(
 # Create agent with MCP tool attached
 agent_state = client.agents.create(
     model="openai/gpt-4o-mini",
-    embedding="openai/text-embedding-3-small",
     tool_ids=[tool.id]
 )
 
@@ -310,7 +306,6 @@ const tool = await client.tools.addMcpTool("weather-server", "get_weather");
 // Create agent with MCP tool
 const agentState = await client.agents.create({
     model: "openai/gpt-4o-mini",
-    embedding: "openai/text-embedding-3-small",
     toolIds: [tool.id]
 });
 
@@ -333,17 +328,12 @@ Once you attach a folder to an agent, the agent will be able to use filesystem t
 
 <details>
 <summary>View code snippets</summary>
-  
+
 ### Python
 ```python
-# get an available embedding_config
-embedding_configs = client.embedding_models.list()
-embedding_config = embedding_configs[0]
-
-# create the folder
+# create the folder (embeddings managed automatically by Letta Cloud)
 folder = client.folders.create(
-    name="my_folder",
-    embedding_config=embedding_config
+    name="my_folder"
 )
 
 # upload a file into the folder
@@ -381,14 +371,9 @@ for message in response.messages:
 
 ### TypeScript / Node.js
 ```typescript
-// get an available embedding_config
-const embeddingConfigs = await client.embeddingModels.list()
-const embeddingConfig = embeddingConfigs[0];
-
-// create the folder
+// create the folder (embeddings managed automatically by Letta Cloud)
 const folder = await client.folders.create({
-    name: "my_folder",
-    embeddingConfig: embeddingConfig
+    name: "my_folder"
 });
 
 // upload a file into the folder
@@ -445,7 +430,7 @@ When agents need to execute multiple tool calls or perform complex operations (l
 
 <details>
 <summary>View code snippets</summary>
-  
+
 ### Python
 ```python
 stream = client.agents.messages.create_stream(
@@ -530,7 +515,7 @@ Letta is an open source project built by over a hundred contributors. There are
 
 * [**Join the Discord**](https://discord.gg/letta): Chat with the Letta devs and other AI developers.
 * [**Chat on our forum**](https://forum.letta.com/): If you're not into Discord, check out our developer forum.
-* **Follow our socials**: [Twitter/X](https://twitter.com/Letta_AI), [LinkedIn](https://www.linkedin.com/in/letta), [YouTube](https://www.youtube.com/@letta-ai) 
+* **Follow our socials**: [Twitter/X](https://twitter.com/Letta_AI), [LinkedIn](https://www.linkedin.com/in/letta), [YouTube](https://www.youtube.com/@letta-ai)
 
 ---
 

WEBHOOK_SETUP.md

@@ -0,0 +1,194 @@
+# Step Completion Webhook
+
+This feature allows you to receive webhook notifications whenever an agent step completes in the Letta agent loop.
+
+## Architecture
+
+The webhook service integrates with Letta's execution architecture in two ways:
+
+### 1. With Temporal (Recommended)
+
+When using Temporal for agent workflows, webhook calls are wrapped as Temporal activities, providing:
+- Built-in retry logic with configurable timeouts
+- Full observability in Temporal UI
+- Durability guarantees
+- Consistent error handling
+- Activity history and replay capability
+
+Webhooks are triggered after the `create_step` activity completes in the Temporal workflow.
+
+### 2. Without Temporal (Direct Execution)
+
+For direct agent execution (non-Temporal), webhooks are called directly from the `StepManager` service methods:
+- `update_step_success_async()` - When step completes successfully
+- `update_step_error_async()` - When step fails with an error
+- `update_step_cancelled_async()` - When step is cancelled
+
+Webhooks are sent after the step status is committed to the database.
+
+### Common Behavior
+
+In **both** cases:
+- ✅ Webhook failures do not prevent step completion
+- ✅ Step is always marked as complete in the database first
+- ✅ Webhook delivery is logged for debugging
+- ✅ Same authentication and payload format
+
+## Configuration
+
+Set the following environment variables to enable webhook notifications:
+
+### Required
+
+- **`STEP_COMPLETE_WEBHOOK`**: The URL endpoint that will receive POST requests when steps complete.
+  - Example: `https://your-app.com/api/webhooks/step-complete`
+
+### Optional
+
+- **`STEP_COMPLETE_KEY`**: A secret key used for authentication.
+  - When set, the webhook service will include this in an `Authorization` header as `Bearer {key}`
+  - Example: `your-secret-webhook-key-12345`
+
+## Webhook Payload
+
+When a step completes, the webhook service will send a POST request with the following JSON payload:
+
+```json
+{
+  "step_id": "step-01234567-89ab-cdef-0123-456789abcdef"
+}
+```
+
+## Authentication
+
+If `STEP_COMPLETE_KEY` is configured, requests will include an Authorization header:
+
+```
+Authorization: Bearer your-secret-webhook-key-12345
+```
+
+Your webhook endpoint should validate this key to ensure requests are coming from your Letta instance.
+
+## Example Webhook Endpoint
+
+Here's a simple example of a webhook endpoint (using FastAPI):
+
+```python
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+import os
+
+app = FastAPI()
+
+class StepCompletePayload(BaseModel):
+    step_id: str
+
+WEBHOOK_SECRET = os.getenv("STEP_COMPLETE_KEY")
+
+@app.post("/api/webhooks/step-complete")
+async def handle_step_complete(
+    payload: StepCompletePayload,
+    authorization: str = Header(None)
+):
+    # Validate the webhook key
+    if WEBHOOK_SECRET:
+        if not authorization or not authorization.startswith("Bearer "):
+            raise HTTPException(status_code=401, detail="Missing authorization")
+
+        token = authorization.replace("Bearer ", "")
+        if token != WEBHOOK_SECRET:
+            raise HTTPException(status_code=401, detail="Invalid authorization")
+
+    # Process the step completion
+    print(f"Step completed: {payload.step_id}")
+
+    # You can now:
+    # - Log the step completion
+    # - Trigger downstream processes
+    # - Update your application state
+    # - Send notifications
+
+    return {"status": "success"}
+```
+
+## Usage Example
+
+```bash
+# Set environment variables
+export STEP_COMPLETE_WEBHOOK="https://your-app.com/api/webhooks/step-complete"
+export STEP_COMPLETE_KEY="your-secret-webhook-key-12345"
+
+# Start your Letta server
+python -m letta.server
+```
+
+## When Webhooks Are Sent
+
+Webhooks are triggered when a step reaches a terminal state:
+
+1. **Success** - Step completed successfully (`StepStatus.SUCCESS`)
+2. **Error** - Step failed with an error (`StepStatus.FAILED`)
+3. **Cancelled** - Step was cancelled (`StepStatus.CANCELLED`)
+
+All three states trigger the webhook with the same payload containing just the `step_id`.
+
+## Behavior
+
+- **No webhook URL configured**: The service will skip sending notifications (logged at debug level)
+- **Webhook call succeeds**: Returns status 200-299, logged at info level
+- **Webhook timeout**: Returns error, logged at warning level (does not fail the step)
+- **HTTP error**: Returns non-2xx status, logged at warning level (does not fail the step)
+- **Other errors**: Logged at error level (does not fail the step)
+
+**Important**: Webhook failures do not prevent step completion. The step will be marked as complete in the database regardless of webhook delivery status. This ensures system reliability - your webhook endpoint being down will not block agent execution.
+
+## Testing
+
+To test the webhook functionality:
+
+1. Set up a webhook endpoint (you can use [webhook.site](https://webhook.site) for testing)
+2. Configure the environment variables
+3. Run an agent and observe webhook calls when steps complete
+
+```bash
+# Example using webhook.site
+export STEP_COMPLETE_WEBHOOK="https://webhook.site/your-unique-url"
+export STEP_COMPLETE_KEY="test-key-123"
+
+# Run tests
+python -m pytest apps/core/letta/services/webhook_service_test.py -v
+```
+
+## Implementation Details
+
+The webhook notification is sent after:
+1. The step is persisted to the database
+2. Step metrics are recorded
+
+This ensures that the step data is fully committed before external systems are notified.
+
+### Temporal Integration
+
+When using Temporal, the webhook call is executed as a separate activity (`send_step_complete_webhook`) with the following configuration:
+
+- **Start-to-close timeout**: 15 seconds
+- **Schedule-to-close timeout**: 30 seconds
+- **Retry behavior**: Wrapped in try-catch to prevent workflow failure on webhook errors
+
+This allows you to monitor webhook delivery in the Temporal UI and get detailed visibility into any failures.
+
+### File Locations
+
+**Core Service:**
+- `apps/core/letta/services/webhook_service.py` - HTTP client for webhook delivery
+
+**Temporal Integration:**
+- `apps/core/letta/agents/temporal/activities/send_webhook.py` - Temporal activity wrapper
+- `apps/core/letta/agents/temporal/temporal_agent_workflow.py` - Workflow integration
+- `apps/core/letta/agents/temporal/constants.py` - Timeout constants
+
+**Non-Temporal Integration:**
+- `apps/core/letta/services/step_manager.py` - Direct calls in update_step_* methods
+
+**Tests:**
+- `apps/core/letta/services/webhook_service_test.py` - Unit tests