agents

Retrieve Agent

Changed on

Get the state of the agent.

get/v1/agents/{agent_id}

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/agents/{agent_id}
  • Auth
    HTTP bearer

Path parameters

agent_idstring required

Query parameters

include_relationshipsstring[] 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

Successful Response

created_by_idstring nullable

The id of the user that made this object.

last_updated_by_idstring nullable

The id of the user that made this object.

created_atstring date-time nullable

The timestamp when the object was created.

updated_atstring date-time nullable

The timestamp when the object was last updated.

idstring required

The id of the agent. Assigned by the database.

namestring required

The name of the agent.

message_idsstring[] nullable

The ids of the messages in the agent's in-context memory.

systemstring 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.

descriptionstring nullable

The description of the agent.

metadataobject nullable

The metadata of the agent.

tagsstring[] required

The tags associated with the agent.

project_idstring nullable

The id of the project the agent belongs to.

template_idstring nullable

The id of the template the agent belongs to.

base_template_idstring nullable

The base template id of the agent.

deployment_idstring nullable

The id of the deployment.

entity_idstring nullable

The id of the entity within the template.

identity_idsstring[]

The ids of the identities associated with this agent.

message_buffer_autoclearboolean

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_sleeptimeboolean nullable

If set to True, memory management will move to a background agent thread.

last_run_completionstring date-time nullable

The timestamp when the agent last completed a run.

last_run_duration_msinteger nullable

The duration in milliseconds of the agent's last run.

timezonestring nullable

The timezone of the agent (IANA format).

max_files_openinteger 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_limitinteger 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.

hiddenboolean nullable

If set to True, the agent will be hidden.

Example response

{
  "memory": {
    "blocks": [
      {
        "id": "block-123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "file_blocks": [
      {
        "id": "block-123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  },
  "tools": [
    {
      "id": "tool-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "sources": [
    {
      "id": "source-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "tool_exec_environment_variables": [
    {
      "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "secrets": [
    {
      "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Changes

  • 6cec99480c13Revision changes
    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • 17b1c4a59276Revision changes
    • info

      added the optional property //// to the response with the status