### Run Method Sandbox Configuration Example Source: https://docs.letta.com/api/resources/agents/subresources/tools/methods/run Example of a sandbox configuration fingerprint returned by the run method. ```json "sandbox_config_fingerprint" ``` -------------------------------- ### Compaction Response Example Source: https://docs.letta.com/api/python/resources/agents/subresources/messages/methods/compact This is an example of a successful response when compacting messages. ```json { "num_messages_after": 0, "num_messages_before": 0, "summary": "summary" } ``` -------------------------------- ### List Steps Source: https://docs.letta.com/api/typescript/resources/steps/methods/list This example demonstrates how to list all steps. The client automatically handles pagination, fetching more pages as needed. ```APIDOC ## List Steps ### Description Retrieves a list of steps. The client handles pagination automatically. ### Method GET (implicitly via SDK) ### Endpoint `/steps` (implicitly via SDK) ### Parameters This method does not take any explicit parameters. It iterates over all available steps. ### Request Example ```typescript import Letta from '@letta-ai/letta-client'; const client = new Letta({ apiKey: process.env['LETTA_API_KEY'], }); // Automatically fetches more pages as needed. for await (const step of client.steps.list()) { console.log(step.id); } ``` ### Response #### Success Response (200) Returns an array of step objects. Each object contains details about a single step. - **id** (string) - The unique identifier for the step. - **agent_id** (string) - The ID of the agent associated with the step. - **cache_write_tokens** (number) - Tokens used for writing to cache. - **cached_input_tokens** (number) - Input tokens from cache. - **completion_tokens** (number) - Tokens used for completion. - **completion_tokens_details** (object) - Detailed breakdown of completion tokens. - **context_window_limit** (number) - The context window limit for the step. - **error_data** (object) - Data related to any errors encountered. - **error_type** (string) - The type of error, if any. - **feedback** (string) - User feedback on the step (e.g., 'positive'). - **messages** (array) - An array of message objects within the step. - **model** (string) - The model used for the step. - **model_endpoint** (string) - The endpoint of the model. - **model_handle** (string) - The handle for the model. - **origin** (string) - The origin of the step. - **project_id** (string) - The ID of the project the step belongs to. - **prompt_tokens** (number) - Tokens used for the prompt. - **prompt_tokens_details** (object) - Detailed breakdown of prompt tokens. - **provider_category** (string) - The category of the model provider. - **provider_id** (string) - The ID of the model provider. - **provider_name** (string) - The name of the model provider. - **reasoning_tokens** (number) - Tokens used for reasoning. - **request_id** (string) - The ID of the request. - **run_id** (string) - The ID of the run. - **status** (string) - The status of the step (e.g., 'pending'). - **stop_reason** (string) - The reason the step stopped (e.g., 'end_turn'). - **tags** (array) - Tags associated with the step. - **tid** (string) - The trace ID for the step. - **total_tokens** (number) - Total tokens used in the step. - **trace_id** (string) - The trace ID for the step. #### Response Example ```json [ { "id": "id", "agent_id": "agent_id", "cache_write_tokens": 0, "cached_input_tokens": 0, "completion_tokens": 0, "completion_tokens_details": { "foo": "bar" }, "context_window_limit": 0, "error_data": { "foo": "bar" }, "error_type": "error_type", "feedback": "positive", "messages": [ { "id": "message-123e4567-e89b-12d3-a456-426614174000", "role": "assistant", "agent_id": "agent_id", "approval_request_id": "approval_request_id", "approvals": [ { "approve": true, "tool_call_id": "tool_call_id", "reason": "reason", "type": "approval" } ], "approve": true, "batch_item_id": "batch_item_id", "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "denial_reason": "denial_reason", "group_id": "group_id", "is_err": true, "last_updated_by_id": "last_updated_by_id", "model": "model", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "step_id": "step_id", "tool_call_id": "tool_call_id", "tool_calls": [ { "id": "id", "function": { "arguments": "arguments", "name": "name" }, "type": "function" } ], "tool_returns": [ { "status": "success", "func_response": "string", "stderr": [ "string" ], "stdout": [ "string" ], "tool_call_id": {} } ], "updated_at": "2019-12-27T18:11:19.117Z" } ], "model": "model", "model_endpoint": "model_endpoint", "model_handle": "model_handle", "origin": "origin", "project_id": "project_id", "prompt_tokens": 0, "prompt_tokens_details": { "foo": "bar" }, "provider_category": "provider_category", "provider_id": "provider_id", "provider_name": "provider_name", "reasoning_tokens": 0, "request_id": "request_id", "run_id": "run_id", "status": "pending", "stop_reason": "end_turn", "tags": [ "string" ], "tid": "tid", "total_tokens": 0, "trace_id": "trace_id" } ] ``` ``` -------------------------------- ### Create Folder Response Example Source: https://docs.letta.com/api/resources/folders/methods/create Example of a successful response when creating a folder. ```APIDOC ## POST /folders ### Description Creates a new folder within the Letta platform. ### Method POST ### Endpoint /folders ### Response #### Success Response (200) - **id** (string) - The unique identifier for the created folder. - **embedding_config** (object) - Configuration details for embeddings. - **embedding_dim** (integer) - The dimension of the embeddings. - **embedding_endpoint_type** (string) - The type of embedding endpoint (e.g., 'openai'). - **embedding_model** (string) - The name of the embedding model. - **azure_deployment** (string) - Azure deployment name if applicable. - **azure_endpoint** (string) - Azure endpoint URL if applicable. - **azure_version** (string) - Azure API version if applicable. - **batch_size** (integer) - The batch size for embedding generation. - **embedding_chunk_size** (integer) - The chunk size for embedding generation. - **embedding_endpoint** (string) - The URL of the embedding endpoint. - **handle** (string) - A handle or identifier for the embedding configuration. - **name** (string) - The name of the folder. - **created_at** (string) - The timestamp when the folder was created. - **created_by_id** (string) - The ID of the user who created the folder. - **description** (string) - A description of the folder. - **instructions** (string) - Instructions associated with the folder. - **last_updated_by_id** (string) - The ID of the user who last updated the folder. - **metadata** (object) - Additional metadata associated with the folder. - **foo** (string) - Example metadata field. - **updated_at** (string) - The timestamp when the folder was last updated. #### Response Example { "id": "source-123e4567-e89b-12d3-a456-426614174000", "embedding_config": { "embedding_dim": 0, "embedding_endpoint_type": "openai", "embedding_model": "embedding_model", "azure_deployment": "azure_deployment", "azure_endpoint": "azure_endpoint", "azure_version": "azure_version", "batch_size": 0, "embedding_chunk_size": 0, "embedding_endpoint": "embedding_endpoint", "handle": "handle" }, "name": "name", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "description": "description", "instructions": "instructions", "last_updated_by_id": "last_updated_by_id", "metadata": { "foo": "bar" }, "updated_at": "2019-12-27T18:11:19.117Z" } ``` -------------------------------- ### Simple Hello World Agent Example Source: https://docs.letta.com/api/typescript Create a stateful agent, send it a message, and observe its memory updates. Requires a Letta API key or a running Docker server. ```typescript import { Letta } from "@letta-ai/letta-client"; const client = new Letta({ apiKey: process.env.LETTA_API_KEY }); const agentState = await client.agents.create({ model: "openai/gpt-4.1", embedding: "openai/text-embedding-3-small", memory_blocks: [ { label: "human", value: "The human's name is Chad. They like vibe coding." }, { label: "persona", value: "My name is Sam, a helpful assistant." } ], tools: ["web_search", "run_code"] }); console.log("Agent created with ID:", agentState.id); const response = await client.agents.messages.create(agentState.id, { input: "Hey, nice to meet you, my name is Brad." }); // the agent will think, then edit its memory using a tool for (const message of response.messages) { console.log(message); } // The content of this memory block will be something like // "The human's name is Brad. They like vibe coding." // Fetch this block's content with: const human_block = await client.agents.blocks.retrieve("human", { agent_id: agentState.id }); console.log(human_block.value); ``` -------------------------------- ### Search Tools with Python SDK Source: https://docs.letta.com/api/python/resources/tools/methods/search Demonstrates how to initialize the Letta client and perform a basic tool search. Ensure the LETTA_API_KEY environment variable is set. ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) tool_search_results = client.tools.search() print(tool_search_results) ``` -------------------------------- ### Template Create Response Example Source: https://docs.letta.com/api/python/resources/templates/methods/create This is an example of the response structure when a template is successfully created. ```json { "id": "id", "latest_version": "latest_version", "name": "name", "project_id": "project_id", "project_slug": "project_slug", "template_deployment_slug": "template_deployment_slug", "updated_at": "updated_at", "description": "description" } ``` -------------------------------- ### Initialize Letta Clients (Sync and Async) Source: https://docs.letta.com/api/python Demonstrates initializing both synchronous and asynchronous Letta clients using an API key. The async client requires `await` for certain operations. ```python from letta_client import Letta from letta_client.types import CreateAgentRequest # Sync client client = Letta(api_key="LETTA_API_KEY") # Async client from letta_client import AsyncLetta async_client = AsyncLetta(api_key="LETTA_API_KEY") agent = await async_client.agents.create( model="openai/gpt-4o-mini", memory_blocks=[...] ) ``` -------------------------------- ### Example Trace Response Source: https://docs.letta.com/api/python/resources/runs/subresources/trace/methods/retrieve This is an example of the JSON structure returned when retrieving trace data. ```json [ { "foo": "bar" } ] ``` -------------------------------- ### List Steps for Run Source: https://docs.letta.com/api/resources/runs/subresources/steps/methods/list This example shows how to list all steps for a given run using a curl command. Replace `$RUN_ID` with the actual run ID and `$LETTA_API_KEY` with your API key. ```APIDOC ## List Steps For Run ### Description Retrieves a list of all steps associated with a specific run. ### Method GET ### Endpoint /runs/$RUN_ID/steps ### Parameters #### Path Parameters - **RUN_ID** (string) - Required - The ID of the run to list steps for. ### Request Example ```bash curl https://api.letta.com/v1/runs/$RUN_ID/steps \ -H "Authorization: Bearer $LETTA_API_KEY" ``` ### Response #### Success Response (200) Returns a JSON array of step objects. - **id** (string) - The unique identifier for the step. - **agent_id** (string) - The ID of the agent that executed the step. - **cache_write_tokens** (integer) - Tokens used for writing to the cache. - **cached_input_tokens** (integer) - Tokens consumed from the cache. - **completion_tokens** (integer) - Tokens used for step completion. - **completion_tokens_details** (object) - Detailed breakdown of completion tokens. - **context_window_limit** (integer) - The context window limit for the model. - **error_data** (object) - Data associated with any errors encountered. - **error_type** (string) - The type of error, if any. - **feedback** (string) - User feedback on the step (e.g., 'positive'). - **messages** (array) - An array of message objects exchanged during the step. - **model** (string) - The name of the model used. - **model_endpoint** (string) - The endpoint of the model. - **model_handle** (string) - The handle for the model. - **origin** (string) - The origin of the step execution. - **project_id** (string) - The ID of the project the run belongs to. - **prompt_tokens** (integer) - Tokens used for the prompt. - **prompt_tokens_details** (object) - Detailed breakdown of prompt tokens. - **provider_category** (string) - The category of the model provider. - **provider_id** (string) - The ID of the model provider. - **provider_name** (string) - The name of the model provider. - **reasoning_tokens** (integer) - Tokens used for reasoning. - **request_id** (string) - The ID of the request that initiated the step. - **run_id** (string) - The ID of the run this step belongs to. - **status** (string) - The current status of the step (e.g., 'pending'). - **stop_reason** (string) - The reason the step stopped (e.g., 'end_turn'). - **tags** (array) - Tags associated with the step. - **tid** (string) - The trace ID for the step. - **total_tokens** (integer) - Total tokens used in the step. - **trace_id** (string) - The trace ID for the step. ### Response Example ```json [ { "id": "id", "agent_id": "agent_id", "cache_write_tokens": 0, "cached_input_tokens": 0, "completion_tokens": 0, "completion_tokens_details": { "foo": "bar" }, "context_window_limit": 0, "error_data": { "foo": "bar" }, "error_type": "error_type", "feedback": "positive", "messages": [ { "id": "message-123e4567-e89b-12d3-a456-426614174000", "role": "assistant", "agent_id": "agent_id", "approval_request_id": "approval_request_id", "approvals": [ { "approve": true, "tool_call_id": "tool_call_id", "reason": "reason", "type": "approval" } ], "approve": true, "batch_item_id": "batch_item_id", "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "denial_reason": "denial_reason", "group_id": "group_id", "is_err": true, "last_updated_by_id": "last_updated_by_id", "model": "model", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "step_id": "step_id", "tool_call_id": "tool_call_id", "tool_calls": [ { "id": "id", "function": { "arguments": "arguments", "name": "name" }, "type": "function" } ], "tool_returns": [ { "status": "success", "func_response": "string", "stderr": [ "string" ], "stdout": [ "string" ], "tool_call_id": {} } ], "updated_at": "2019-12-27T18:11:19.117Z" } ], "model": "model", "model_endpoint": "model_endpoint", "model_handle": "model_handle", "origin": "origin", "project_id": "project_id", "prompt_tokens": 0, "prompt_tokens_details": { "foo": "bar" }, "provider_category": "provider_category", "provider_id": "provider_id", "provider_name": "provider_name", "reasoning_tokens": 0, "request_id": "request_id", "run_id": "run_id", "status": "pending", "stop_reason": "end_turn", "tags": [ "string" ], "tid": "tid", "total_tokens": 0, "trace_id": "trace_id" } ] ``` ``` -------------------------------- ### McpServerListResponseItem Example Source: https://docs.letta.com/api/python/resources/mcp_servers/methods/list This is an example of the structure returned for a single MCP server in the list response. ```json [ { "args": [ "string" ], "command": "command", "server_name": "server_name", "id": "mcp_server-123e4567-e89b-12d3-a456-426614174000", "env": { "foo": "string" }, "mcp_server_type": "stdio" } ] ``` -------------------------------- ### Connect to MCP Servers and Use MCP Tools Source: https://docs.letta.com/api/python Example of creating an MCP server, listing its available tools, and then creating an agent that utilizes one of these MCP tools. ```python # First, create an MCP server (example: weather server) weather_server = client.mcp_servers.create( server_name="weather-server", config={ "mcp_server_type": "streamable_http", "server_url": "https://weather-mcp.example.com/mcp", } ) # List tools available from the MCP server tools = client.mcp_servers.tools.list(weather_server.id) # Create agent with MCP tool agent = client.agents.create( model="openai/gpt-4o-mini", tool_ids=[tool.id] ) ``` -------------------------------- ### Cancel Conversation API Response Example Source: https://docs.letta.com/api/python/resources/conversations/methods/cancel This is an example of a successful response when canceling a conversation. ```json { "foo": "bar" } ``` -------------------------------- ### Search Tools with Default Parameters Source: https://docs.letta.com/api/typescript/resources/tools/methods/search Demonstrates how to initialize the Letta client and perform a basic search for tools. Ensure your LETTA_API_KEY is set in your environment variables. ```typescript import Letta from '@letta-ai/letta-client'; const client = new Letta({ apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted }); const toolSearchResults = await client.tools.search(); console.log(toolSearchResults); ``` -------------------------------- ### 200 OK Response Example Source: https://docs.letta.com/api/python/resources/agents/subresources/schedule/methods/retrieve This is an example of a successful response when retrieving a scheduled agent message. ```json { "id": "id", "agent_id": "agent_id", "message": { "messages": [ { "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "role": "user", "name": "name", "otid": "otid", "sender_id": "sender_id", "type": "message" } ], "callback_url": "https://example.com", "include_return_message_types": [ "system_message" ], "max_steps": 0 }, "next_scheduled_time": "next_scheduled_time", "schedule": { "scheduled_at": 0, "type": "one-time" } } ``` -------------------------------- ### Create Agent Response Example Source: https://docs.letta.com/api/python/resources/templates/subresources/agents/methods/create Example of the JSON response structure when creating an agent from a template. ```json { "agent_ids": [ "string" ], "deployment_id": "deployment_id", "group_id": "group_id" } ``` -------------------------------- ### List All Tags Source: https://docs.letta.com/api/python/resources/tags/methods/list Demonstrates how to initialize the Letta client and retrieve a list of all tags. Ensure the LETTA_API_KEY environment variable is set. ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) tags = client.tags.list() print(tags) ``` -------------------------------- ### Rollback Template Response Example (JSON) Source: https://docs.letta.com/api/python/resources/templates/methods/rollback This is an example of a successful response when rolling back a template. ```json { "success": true, "message": "message" } ``` -------------------------------- ### Agent Run Method Output Example Source: https://docs.letta.com/api/typescript/resources/agents/subresources/tools/methods/run This example illustrates the output of the agent's 'run' method, including the sandbox configuration fingerprint, standard error, and standard output streams. ```json { "func_return": {}, "sandbox_config_fingerprint": "sandbox_config_fingerprint", "stderr": [ "string" ], "stdout": [ "string" ] } ``` -------------------------------- ### Metric Retrieve Response Example Source: https://docs.letta.com/api/python/resources/steps/subresources/metrics/methods/retrieve This is an example of the JSON response structure when retrieving step metrics. ```json { "id": "id", "agent_id": "agent_id", "base_template_id": "base_template_id", "llm_request_ns": 0, "llm_request_start_ns": 0, "project_id": "project_id", "provider_id": "provider_id", "run_id": "run_id", "step_ns": 0, "step_start_ns": 0, "template_id": "template_id", "tool_execution_ns": 0 } ``` -------------------------------- ### Example Agent Method Creation Source: https://docs.letta.com/api/python/resources/agents/methods/create This snippet demonstrates the structure of an agent method, including its name, description, and associated tool rules. It shows how to define constraints for child tools. ```json { "name": "tool_name", "description": "description", "tool_type": "function", "parameters": { "type": "object", "properties": { "foo": { "type": "string", "description": "bar" } } }, "tool_code": "def tool_code(foo: str): return foo" } ``` -------------------------------- ### Search Passages Response Example Source: https://docs.letta.com/api/python/resources/passages/methods/search Example JSON structure for a successful search passages response. ```json [ { "passage": { "embedding": [ 0 ], "embedding_config": { "embedding_dim": 0, "embedding_endpoint_type": "openai", "embedding_model": "embedding_model", "azure_deployment": "azure_deployment", "azure_endpoint": "azure_endpoint", "azure_version": "azure_version", "batch_size": 0, "embedding_chunk_size": 0, "embedding_endpoint": "embedding_endpoint", "handle": "handle" }, "text": "text", "id": "passage-123e4567-e89b-12d3-a456-426614174000", "archive_id": "archive_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "file_id": "file_id", "file_name": "file_name", "is_deleted": true, "last_updated_by_id": "last_updated_by_id", "metadata": { "foo": "bar" }, "source_id": "source_id", "tags": [ "string" ], "updated_at": "2019-12-27T18:11:19.117Z" }, "score": 0, "metadata": { "foo": "bar" } } ] ``` -------------------------------- ### System Message Search Response Example Source: https://docs.letta.com/api/python/resources/messages/methods/search This is an example of a successful response when searching for system messages. ```json [ { "content": "content", "created_at": "2019-12-27T18:11:19.117Z", "message_id": "message_id", "agent_id": "agent_id", "conversation_id": "conversation_id", "message_type": "system_message" } ] ``` -------------------------------- ### List Steps with Letta Client Source: https://docs.letta.com/api/python/resources/steps/methods/list Initializes the Letta client and retrieves a list of steps. Accesses the first item in the paginated list and prints its ID. Ensure the LETTA_API_KEY environment variable is set. ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.steps.list() page = page.items[0] print(page.id) ```