# llGiveAgentInventory

*LSL function*

```lsl
integer integer llGiveAgentInventory(key agent, string folder, list items, list options);
```

- `key agent`: UUID of the target agent in the same region.
- `string folder`: Name of the destination folder to be created
- `list items`: The names of the items in the prim's inventory to transfer.
- `list options`: A list of options to configure the inventory transfer.

- Returns: `integer`
- Delay: 3 s
- Energy: 10

Gives the specified inventory items to the agent as a new folder named folder, as permitted by the permissions system. Customizes the transfer using options.

Gives **inventory** items to **agent**, creating a new **folder** to put them in.

```lsl title="How to use" frame="terminal"
integer result = llGiveAgentInventory(NULL_KEY, "", [], []);
```

## Specification

Constant group [GiveAgentInventoryParam](/constants/groups/GiveAgentInventoryParam/):

```lsl
TRANSFER_DEST = 0
TRANSFER_FLAGS = 1
```

- The target must be an avatar in the same region as the sending object, or must have recently been in the region.
- Places the inventory items in a newly created **folder** in the avatar's inventory (even if there is a **folder** by the same name, a new one is created).
- If a path of root folders has been specified, the function will ensure that those folders exist but will not recreate them if they already exist.

#### Transfer Options

<table>
	<tr>
		<th>Flags</th>
		<th></th>
		<td>Parameters</td>
		<th>Description</th>
	</tr>
	<tr>
		<td>[TRANSFER_DEST](/constants/TRANSFER_DEST/)</td>
		<td>0</td>
		<td>`[ TRANSFER_DEST, string ]`</td>
		<td>Sets a root path that will be used as the parent for **folder**. If the root path does not exist it will be created. If it already exists in the target inventory it will be reused. Path folders are separated by a "|" character. The path may have have up to 4 folders in it. Note that transfers to certain system folders (such as 'Trash') are disallowed. Examples:<br /> "Objects|Vehicles|My Motorcycle Company"<br /> "Clothing|Shoes|Breedables"<br /> "My Store|Home & Garden|"</td>
	</tr>
	<tr>
		<td>[TRANSFER_FLAGS](/constants/TRANSFER_FLAGS/)</td>
		<td>1</td>
		<td>`[ TRANSFER_FLAGS, integer ]`</td>
		<td>There are no flags defined at this time.</td>
	</tr>
</table>

#### Transfer Errors

<table>
	<tr>
		<th>Constant</th>
		<th></th>
		<td>Description</td>
	</tr>
	<tr>
		<td>[TRANSFER_OK](/constants/TRANSFER_OK/)</td>
		<td>0</td>
		<td>No error detected, inventory transferred</td>
	</tr>
	<tr>
		<td>[TRANSFER_BAD_OPTS](/constants/TRANSFER_BAD_OPTS/)</td>
		<td>-1</td>
		<td>A bad option was passed in the options list.</td>
	</tr>
	<tr>
		<td>[TRANSFER_NO_TARGET](/constants/TRANSFER_NO_TARGET/)</td>
		<td>-2</td>
		<td>Could not find the receiving agent in the current region.</td>
	</tr>
	<tr>
		<td>[TRANSFER_THROTTLE](/constants/TRANSFER_THROTTLE/)</td>
		<td>-3</td>
		<td>Transfer rate exceeded the inventory transfer throttle.</td>
	</tr>
	<tr>
		<td>[TRANSFER_NO_ITEMS](/constants/TRANSFER_NO_ITEMS/)</td>
		<td>-4</td>
		<td>The list of items was empty or contained only non-transferable items.</td>
	</tr>
	<tr>
		<td>[TRANSFER_BAD_ROOT](/constants/TRANSFER_BAD_ROOT/)</td>
		<td>-5</td>
		<td>The root path specified in [TRANSFER_DEST](/constants/TRANSFER_DEST/) contained an invalid directory or was reduced to nothing.</td>
	</tr>
	<tr>
		<td>[TRANSFER_NO_PERMS](/constants/TRANSFER_NO_PERMS/)</td>
		<td>-6</td>
		<td>The object does not have transfer permissions.</td>
	</tr>
	<tr>
		<td>[TRANSFER_NO_ATTACHMENT](/constants/TRANSFER_NO_ATTACHMENT/)</td>
		<td>-7</td>
		<td>Can not transfer ownership of an attached object.</td>
	</tr>
</table>

## Caveats

- Any no-copy items in **inventory** will be excluded from transfer.
- Any no-transfer items in **inventory** will be excluded from transfer if **agent** is not the script owner.

## Examples

<details open>
<summary>In this example, the object inventory needs to contain two objects named *Item 1* and *Item 2*. The destination **folder** will be named *Destination Folder* and will be created under the main **folder** *Objects*, in the sub-folder *Subfolder*. If *Subfolder* does not exist, it will be created.</summary>

If the object gets touched for a second time, the sub-folder *Subfolder* will **not** be duplicated, however the destination **folder** *Destination Folder* **will** be duplicated.

If *Item 1* and/or *Item 2* do not exist, the transfer will silently fail partially or completely.

```lsl
default
{
    touch_start(integer total_number)
    {
        llGiveAgentInventory(llDetectedKey(0), "Destination Folder", ["Item 1","Item 2"], [TRANSFER_DEST, "Objects|Subfolder"] );
    }
}
```

</details>

## See also

### Functions

- [llGiveInventory](/functions/llGiveInventory/)
- [llGiveInventoryList](/functions/llGiveInventoryList/)

### Events

- [changed](/events/changed/)

---

*Source: [LlGiveAgentInventory](https://wiki.secondlife.com/wiki/LlGiveAgentInventory) on the Second Life Wiki. Content from the Second Life Wiki articles LlGiveAgentInventory (revision 1218049, 2025-03-12), Template:LSL Constants/Transfer Errors (revision 1217643, 2024-11-13) and Template:LSL Constants/Transfer Inventory (revision 1217998, 2025-02-28), CC BY-SA 3.0.*

---

From lsl.dev: https://lsl.dev/functions/llGiveAgentInventory/