--- title: "Search Deployed Agents" method: POST path: "/v1/agents/search" tags: ["agents"] --- # Search Deployed Agents `POST /v1/agents/search` Search deployed agents ## Request body - object - `search` union[] - union - object - `field` 'version', required - `value` string, required - object - `field` 'name', required - `operator` 'eq' | 'contains', required - `value` string, required - object - `field` 'tags', required - `operator` 'contains', required - `value` string[], required - object - `field` 'identity', required - `operator` 'eq', required - `value` string, required - object - `field` 'templateName', required - `operator` 'eq', required - `value` string, required - `project_id` string - `combinator` 'AND' - `limit` number - `after` string, nullable - `sortBy` 'created_at' | 'last_run_completion' - `ascending` boolean ## Response `200` 200 - object - `agents` AgentState[], required - `created_by_id` string, nullable — The id of the user that made this object. - `last_updated_by_id` string, nullable — The id of the user that made this object. - `created_at` string, date-time, nullable — The timestamp when the object was created. - `updated_at` string, date-time, nullable — The timestamp when the object was last updated. - `id` string, required — The id of the agent. Assigned by the database. - `name` string, required — The name of the agent. - `tool_rules` union[], nullable — The list of tool rules. - union - ChildToolRule — A ToolRule represents a tool that can be invoked by the agent. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'constrain_child_tools' - `prompt_template` string, nullable — Optional template string (ignored). - `children` string[], required — The children tools that can be invoked. - `child_arg_nodes` ToolCallNode[], nullable — Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name` string, required — The name of the child tool to invoke next. - `args` object, nullable — Optional prefilled arguments for this child tool. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model. - InitToolRule — Represents the initial tool rule configuration. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'run_first' - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `args` object, nullable — Optional prefilled arguments for this tool. When present, these values will override any LLM-provided arguments with the same keys during invocation. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model. - TerminalToolRule — Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'exit_loop' - `prompt_template` string, nullable — Optional template string (ignored). - ConditionalToolRule — A ToolRule that conditionally maps to different child tools based on the output. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'conditional' - `prompt_template` string, nullable — Optional template string (ignored). - `default_child` string, nullable — The default child tool to be called. If None, any tool can be called. - `child_output_mapping` object, required — The output case to check for mapping - `require_output_mapping` boolean — Whether to throw an error when output doesn't match any case - ContinueToolRule — Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'continue_loop' - `prompt_template` string, nullable — Optional template string (ignored). - RequiredBeforeExitToolRule — Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'required_before_exit' - `prompt_template` string, nullable — Optional template string (ignored). - MaxCountPerStepToolRule — Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'max_count_per_step' - `prompt_template` string, nullable — Optional template string (ignored). - `max_count_limit` integer, required — The max limit for the total number of times this tool can be invoked in a single step. - ParentToolRule — A ToolRule that only allows a child tool to be called if the parent has been called. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'parent_last_tool' - `prompt_template` string, nullable — Optional template string (ignored). - `children` string[], required — The children tools that can be invoked. - RequiresApprovalToolRule — Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization. - `type` 'requires_approval' - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `message_ids` string[], nullable — The ids of the messages in the agent's in-context memory. - `system` string, required — The system prompt used by the agent. - `agent_type` 'memgpt_agent' | 'memgpt_v2_agent' | 'letta_v1_agent' | 'react_agent' | 'workflow_agent' | 'split_thread_agent' | 'sleeptime_agent' | 'voice_convo_agent' | 'voice_sleeptime_agent', required — Enum to represent the type of agent. - `llm_config` LLMConfig, required — Configuration for Language Model (LLM) connection and generation parameters. - `model` string, required — LLM model name. - `model_endpoint_type` 'openai' | 'anthropic' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'lmstudio-chatcompletions' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'bedrock' | 'deepseek' | 'xai', required — The endpoint type for the model. - `model_endpoint` string, nullable — The endpoint for the model. - `provider_name` string, nullable — The provider name for the model. - `provider_category` 'base' | 'byok' - `model_wrapper` string, nullable — The wrapper for the model. - `context_window` integer, required — The context window size for the model. - `put_inner_thoughts_in_kwargs` boolean, nullable — Puts 'inner_thoughts' as a kwarg in the function call if this is set to True. This helps with function calling performance and also the generation of inner thoughts. - `handle` string, nullable — The handle for this config, in the format provider/model-name. - `temperature` number — The temperature to use when generating text with the model. A higher temperature will result in more random text. - `max_tokens` integer, nullable — The maximum number of tokens to generate. If not set, the model will use its default value. - `enable_reasoner` boolean — Whether or not the model should use extended thinking if it is a 'reasoning' style model - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high', nullable — The reasoning effort to use when generating text reasoning models - `max_reasoning_tokens` integer — Configurable thinking budget for extended thinking. Used for enable_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable_reasoner. - `frequency_penalty` number, nullable — Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. From OpenAI: Number between -2.0 and 2.0. - `compatibility_type` 'gguf' | 'mlx', nullable — The framework compatibility type for the model. - `verbosity` 'low' | 'medium' | 'high', nullable — Soft control for how verbose model output should be, used for GPT-5 models. - `tier` string, nullable — The cost tier for the model (cloud only). - `embedding_config` EmbeddingConfig, required — Configuration for embedding model connection and processing parameters. - `embedding_endpoint_type` 'openai' | 'anthropic' | 'bedrock' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'pinecone', required — The endpoint type for the model. - `embedding_endpoint` string, nullable — The endpoint for the model (`None` if local). - `embedding_model` string, required — The model for the embedding. - `embedding_dim` integer, required — The dimension of the embedding. - `embedding_chunk_size` integer, nullable — The chunk size of the embedding. - `handle` string, nullable — The handle for this config, in the format provider/model-name. - `batch_size` integer — The maximum batch size for processing embeddings. - `azure_endpoint` string, nullable — The Azure endpoint for the model. - `azure_version` string, nullable — The Azure version for the model. - `azure_deployment` string, nullable — The Azure deployment for the model. - `response_format` union — The response format used by the agent when returning from `send_message`. - TextResponseFormat — Response format for plain text responses. - `type` 'text' — The type of the response format. - JsonSchemaResponseFormat — Response format for JSON schema-based responses. - `type` 'json_schema' — The type of the response format. - `json_schema` object, required — The JSON schema of the response. - JsonObjectResponseFormat — Response format for JSON object responses. - `type` 'json_object' — The type of the response format. - `description` string, nullable — The description of the agent. - `metadata` object, nullable — The metadata of the agent. - `memory` Memory, required — Represents the in-context memory (i.e. Core memory) of the agent. This includes both the `Block` objects (labelled by sections), as well as tools to edit the blocks. - `agent_type` union — Agent type controlling prompt rendering. - 'memgpt_agent' | 'memgpt_v2_agent' | 'letta_v1_agent' | 'react_agent' | 'workflow_agent' | 'split_thread_agent' | 'sleeptime_agent' | 'voice_convo_agent' | 'voice_sleeptime_agent' — Enum to represent the type of agent. - string - `blocks` Block[], required — Memory blocks contained in the agent's in-context memory - `value` string, required — Value of the block. - `limit` integer — Character limit of the block. - `project_id` string, nullable — The associated project id. - `name` string, nullable — The id of the template. - `is_template` boolean — Whether the block is a template (e.g. saved human/persona options). - `base_template_id` string, nullable — The base template id of the block. - `deployment_id` string, nullable — The id of the deployment. - `entity_id` string, nullable — The id of the entity within the template. - `preserve_on_migration` boolean, nullable — Preserve the block on template migration. - `label` string, nullable — Label of the block (e.g. 'human', 'persona') in the context window. - `read_only` boolean — Whether the agent has read-only access to the block. - `description` string, nullable — Description of the block. - `metadata` object, nullable — Metadata of the block. - `hidden` boolean, nullable — If set to True, the block will be hidden. - `id` string — The human-friendly ID of the Block - `created_by_id` string, nullable — The id of the user that made this Block. - `last_updated_by_id` string, nullable — The id of the user that last updated this Block. - `file_blocks` FileBlock[] — Special blocks representing the agent's in-context memory of an attached file - `value` string, required — Value of the block. - `limit` integer — Character limit of the block. - `project_id` string, nullable — The associated project id. - `name` string, nullable — The id of the template. - `is_template` boolean — Whether the block is a template (e.g. saved human/persona options). - `base_template_id` string, nullable — The base template id of the block. - `deployment_id` string, nullable — The id of the deployment. - `entity_id` string, nullable — The id of the entity within the template. - `preserve_on_migration` boolean, nullable — Preserve the block on template migration. - `label` string, nullable — Label of the block (e.g. 'human', 'persona') in the context window. - `read_only` boolean — Whether the agent has read-only access to the block. - `description` string, nullable — Description of the block. - `metadata` object, nullable — Metadata of the block. - `hidden` boolean, nullable — If set to True, the block will be hidden. - `id` string — The human-friendly ID of the Block - `created_by_id` string, nullable — The id of the user that made this Block. - `last_updated_by_id` string, nullable — The id of the user that last updated this Block. - `file_id` string, required — Unique identifier of the file. - `source_id` string, required — Unique identifier of the source. - `is_open` boolean, required — True if the agent currently has the file open. - `last_accessed_at` string, date-time, nullable — UTC timestamp of the agent’s most recent access to this file. Any operations from the open, close, or search tools will update this field. - `prompt_template` string — Deprecated. Ignored for performance. - `tools` Tool[], required — The tools used by the agent. - `id` string — The human-friendly ID of the Tool - `tool_type` 'custom' | 'letta_core' | 'letta_memory_core' | 'letta_multi_agent_core' | 'letta_sleeptime_core' | 'letta_voice_sleeptime_core' | 'letta_builtin' | 'letta_files_core' | 'external_langchain' | 'external_composio' | 'external_mcp' - `description` string, nullable — The description of the tool. - `source_type` string, nullable — The type of the source code. - `name` string, nullable — The name of the function. - `tags` string[] — Metadata tags. - `source_code` string, nullable — The source code of the function. - `json_schema` object, nullable — The JSON schema of the function. - `args_json_schema` object, nullable — The args JSON schema of the function. - `return_char_limit` integer — The maximum number of characters in the response. - `pip_requirements` PipRequirement[], nullable — Optional list of pip packages required by this tool. - `name` string, required — Name of the pip package. - `version` string, nullable — Optional version of the package, following semantic versioning. - `npm_requirements` NpmRequirement[], nullable — Optional list of npm packages required by this tool. - `name` string, required — Name of the npm package. - `version` string, nullable — Optional version of the package, following semantic versioning. - `default_requires_approval` boolean, nullable — Default value for whether or not executing this tool requires approval. - `created_by_id` string, nullable — The id of the user that made this Tool. - `last_updated_by_id` string, nullable — The id of the user that made this Tool. - `metadata_` object, nullable — A dictionary of additional metadata for the tool. - `sources` Source[], required — The sources used by the agent. - `name` string, required — The name of the source. - `description` string, nullable — The description of the source. - `instructions` string, nullable — Instructions for how to use the source. - `metadata` object, nullable — Metadata associated with the source. - `id` string — The human-friendly ID of the Source - `embedding_config` EmbeddingConfig, required — Configuration for embedding model connection and processing parameters. - `embedding_endpoint_type` 'openai' | 'anthropic' | 'bedrock' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'pinecone', required — The endpoint type for the model. - `embedding_endpoint` string, nullable — The endpoint for the model (`None` if local). - `embedding_model` string, required — The model for the embedding. - `embedding_dim` integer, required — The dimension of the embedding. - `embedding_chunk_size` integer, nullable — The chunk size of the embedding. - `handle` string, nullable — The handle for this config, in the format provider/model-name. - `batch_size` integer — The maximum batch size for processing embeddings. - `azure_endpoint` string, nullable — The Azure endpoint for the model. - `azure_version` string, nullable — The Azure version for the model. - `azure_deployment` string, nullable — The Azure deployment for the model. - `vector_db_provider` 'native' | 'tpuf' | 'pinecone' — Supported vector database providers for archival memory - `created_by_id` string, nullable — The id of the user that made this Tool. - `last_updated_by_id` string, nullable — The id of the user that made this Tool. - `created_at` string, date-time, nullable — The timestamp when the source was created. - `updated_at` string, date-time, nullable — The timestamp when the source was last updated. - `tags` string[], required — The tags associated with the agent. - `tool_exec_environment_variables` AgentEnvironmentVariable[] — Deprecated: use `secrets` field instead. - `created_by_id` string, nullable — The id of the user that made this object. - `last_updated_by_id` string, nullable — The id of the user that made this object. - `created_at` string, date-time, nullable — The timestamp when the object was created. - `updated_at` string, date-time, nullable — The timestamp when the object was last updated. - `id` string — The human-friendly ID of the Agent-env - `key` string, required — The name of the environment variable. - `value` string, required — The value of the environment variable. - `description` string, nullable — An optional description of the environment variable. - `value_enc` string, nullable — Encrypted secret value (stored as encrypted string) - `agent_id` string, required — The ID of the agent this environment variable belongs to. - `secrets` AgentEnvironmentVariable[] — The environment variables for tool execution specific to this agent. - `created_by_id` string, nullable — The id of the user that made this object. - `last_updated_by_id` string, nullable — The id of the user that made this object. - `created_at` string, date-time, nullable — The timestamp when the object was created. - `updated_at` string, date-time, nullable — The timestamp when the object was last updated. - `id` string — The human-friendly ID of the Agent-env - `key` string, required — The name of the environment variable. - `value` string, required — The value of the environment variable. - `description` string, nullable — An optional description of the environment variable. - `value_enc` string, nullable — Encrypted secret value (stored as encrypted string) - `agent_id` string, required — The ID of the agent this environment variable belongs to. - `project_id` string, nullable — The id of the project the agent belongs to. - `template_id` string, nullable — The id of the template the agent belongs to. - `base_template_id` string, nullable — The base template id of the agent. - `deployment_id` string, nullable — The id of the deployment. - `entity_id` string, nullable — The id of the entity within the template. - `identity_ids` string[] — The ids of the identities associated with this agent. - `message_buffer_autoclear` boolean — If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case. - `enable_sleeptime` boolean, nullable — If set to True, memory management will move to a background agent thread. - `multi_agent_group` Group - `id` string, required — The id of the group. Assigned by the database. - `manager_type` 'round_robin' | 'supervisor' | 'dynamic' | 'sleeptime' | 'voice_sleeptime' | 'swarm', required - `agent_ids` string[], required - `description` string, required - `project_id` string, nullable — The associated project id. - `template_id` string, nullable — The id of the template. - `base_template_id` string, nullable — The base template id. - `deployment_id` string, nullable — The id of the deployment. - `shared_block_ids` string[] - `manager_agent_id` string, nullable - `termination_token` string, nullable - `max_turns` integer, nullable - `sleeptime_agent_frequency` integer, nullable - `turns_counter` integer, nullable - `last_processed_message_id` string, nullable - `max_message_buffer_length` integer, nullable — The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving. - `min_message_buffer_length` integer, nullable — The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving. - `hidden` boolean, nullable — If set to True, the group will be hidden. - `last_run_completion` string, date-time, nullable — The timestamp when the agent last completed a run. - `last_run_duration_ms` integer, nullable — The duration in milliseconds of the agent's last run. - `timezone` string, nullable — The timezone of the agent (IANA format). - `max_files_open` integer, nullable — Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent. - `per_file_view_window_char_limit` integer, nullable — The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. - `hidden` boolean, nullable — If set to True, the agent will be hidden. - `nextCursor` string, nullable --- [API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/versions/6cec99480c13/schema)