.af

Agent File Schema

The Agent File (.af) format is a JSON-based schema that encapsulates all components of a stateful agent. This document provides a comprehensive reference for the schema structure.

Schema Overview

An Agent File contains the following top-level components:

Root Object

Field Type Description
id string The unique identifier of the agent
name string The descriptive name of the agent
description string Optional description of the agent's purpose
agent_type string The type of agent (e.g., "memgpt_agent")
system string System instructions for the agent
message_buffer_autoclear boolean If true, the agent will not persist message history between requests
tags array of strings Tags associated with the agent
llm_config object LLM configuration settings
embedding_config object Embedding model configuration
tool_rules array of objects Rules governing tool usage
messages array of objects Message history
core_memory array of objects Core memory blocks
tools array of objects Available tools
tool_exec_environment_variables array of objects Environment variables for tool execution

LLM Configuration

The llm_config object defines the large language model settings:

Field Type Description
model string Model identifier
model_endpoint_type string Provider type (e.g., "openai", "anthropic")
model_endpoint string API endpoint URL
model_wrapper string | null Optional wrapper for model API calls
context_window integer Maximum context window size in tokens
temperature number Temperature for generation (0.0-1.0)
max_tokens integer Maximum tokens to generate per response
put_inner_thoughts_in_kwargs boolean Whether to include inner thoughts in function call kwargs
handle string Provider/model handle in format "provider/model-name"

Embedding Configuration

The embedding_config object defines settings for the embedding model:

Field Type Description
embedding_endpoint_type string Provider type for embeddings
embedding_endpoint string API endpoint URL for embeddings
embedding_model string Embedding model identifier
embedding_dim integer Dimension of the embedding vectors
embedding_chunk_size integer Chunk size for text splitting when creating embeddings
handle string Provider/model handle in format "provider/model-name"
azure_endpoint string | null Optional Azure-specific endpoint
azure_version string | null Optional Azure API version
azure_deployment string | null Optional Azure deployment name

Core Memory

The core_memory array contains memory block objects:

Field Type Description
label string Type of memory block (e.g., "persona", "human")
value string Content of the memory block
limit integer Character limit for the memory block
is_template boolean Whether the block is a template
description string | null Optional description of the memory block
metadata_ object Additional metadata
id string Unique identifier for the memory block

Tools

The tools array contains tool definitions:

Field Type Description
name string Name of the tool
tool_type string Type of tool (e.g., "letta_core", "custom")
return_char_limit integer Maximum character limit for tool return values
description string Description of the tool's functionality
tags array of strings Tags associated with the tool
source_type string The language or format of the source code
source_code string | null Source code implementation of the tool
json_schema object JSON Schema definition of the tool's parameters
args_json_schema object | null Optional alternative schema for arguments
id string Unique identifier for the tool

Tool JSON Schema

The json_schema object within a tool follows this structure:

Field Type Description
name string Name of the tool (must match the parent tool name)
description string Description of the tool's purpose
parameters object Definition of the tool's parameters

The parameters object includes:

Field Type Description
type string Must be "object"
properties object Map of parameter names to their definitions
required array of strings List of required parameter names

Tool Rules

The tool_rules array defines constraints on tool behavior:

Field Type Description
tool_name string Name of the tool the rule applies to
type string Rule type (e.g., "continue_loop", "exit_loop")

Messages

The messages array contains message history:

Field Type Description
id string Unique message identifier
role string Message role (e.g., "system", "user", "assistant", "tool")
text string Message content
date string ISO timestamp of the message
message_type string | null Optional message type classification
model string Model used to generate the message
name string | null Optional name of the message author
tool_call_id string | null ID of associated tool call if applicable
tool_calls array Tool calls made in this message
tool_returns array Results returned from tool calls
created_at string Creation timestamp
updated_at string Last update timestamp
is_deleted boolean Whether the message is