# Agent

## folder structure

The agent follows a specific organizational structure to ensure streamlined functionality and easy access to essential files:
```
└── agents
    └── myagent
        ├── functions.json                  # Auto-generated JSON declarations for functions
        ├── index.yaml                      # Main agent definition file
        ├── tools.txt                       # List of shared tools
        └── tools.{sh,js,py}                # Scripts implementing agent-specific tools
```

## index.yaml

This is the main definition file for your agent where you provide all essential information and configuration for the agent.

### metadata

Metadata provides basic information about the agent:

- `name`: A unique name for your agent, which helps in identifying and referencing the agent.
- `description`: A brief explanation of what the agent is or its primary purpose.
- `version`: The version number of the agent, which helps track changes or updates to the agent over time.

```yaml
name: TestAgent                             
description: This is test agent
version: 0.1.0
```

### instructions

Defines the initial context or behavior directives for the agent:

```yaml
instructions: You are a test ai agent to ... 
```

### variables

Variables store user-related data, such as behavior or preferences. Below is the syntax for defining variables:

```yaml
variables:
  - name: foo
    description: This is a foo
  - name: bar
    description: This is a bar with default value
    default: val
```

When use define variables, please avoid these built-in variables:

| name            | description                                   | example                  |
| :-------------- | :-------------------------------------------- | :----------------------- |
| `__os__`        | Operating system name                         | linux                    |
| `__os_family__` | Operating system family                       | unix                     |
| `__arch__`      | System architecture                           | x86_64                   |
| `__shell__`     | Current user's default shell                  | bash                     |
| `__locale__`    | User's preferred language and region settings | en-US                    |
| `__now__`       | Current timestamp in ISO 8601 format          | 2024-07-29T08:11:24.367Z |
| `__cwd__`       | Current working directory                     | /tmp                     |
| `__tools__`     | List of agent tools                                 |                          |

Variables can be used within `instructions` and within tool scripts:

```yaml
instructions: |
  The instructions can access user-defined variables: {{foo}} and {{bar}}, or built-in variables: {{__cwd__}}
```

```sh
echo "he tools script can access user-defined variables in environment variables: $LLM_AGENT_VAR_FOO and $LLM_AGENT_VAR_BAR"
```

### documents

A list of resources or references that the agent can access. Documents are used for building RAG.

```yaml
documents:
  - local-file.txt
  - local-dir/
  - https://example.com/remote-file.txt
```

> All local files and directories are relative to the agent directory (where index.yaml is located).

### conversation_starters

Predefined prompts or questions that the agent can use to initiate interactions or conversations.

 ```yaml
 conversation_starters:
   - What can you do?
 ```

## tools.{sh,js,py}

Scripts for implementing tools tailored to the agent's unique requirements.

## tools.txt

`tools.txt` facilitates the reuse of tools specified in the `/tools` directory within this project.