---
title: "Retrieve Agent"
method: GET
path: "/v1/agents/{agent_id}"
tags: ["agents"]
---

# Retrieve Agent

`GET /v1/agents/{agent_id}`

Get the state of the agent.

## Path parameters

- `agent_id` string, required

## Query parameters

- `include_relationships` string[], nullable — Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. If not provided, all relationships are loaded by default. Using this can optimize performance by reducing unnecessary joins.

## Response `200`

Successful Response

- AgentState — Representation of an agent's state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent. Parameters: id (str): The unique identifier of the agent. name (str): The name of the agent (must be unique to the user). created_at (datetime): The datetime the agent was created. message_ids (List[str]): The ids of the messages in the agent's in-context memory. memory (Memory): The in-context memory of the agent. tools (List[str]): The tools used by the agent. This includes any memory editing functions specified in `memory`. system (str): The system prompt used by the agent. llm_config (LLMConfig): The LLM configuration used by the agent. embedding_config (EmbeddingConfig): The embedding configuration used by the 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, 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.

## Other responses

- `422` — Validation Error

---

[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)