refactor: add docs (#143)

3 files changed, 132 insertions, 62 deletions

diff --git a/agents/demo/README.md b/agents/demo/README.md
index 8793eb6..7117efe 100644
--- a/agents/demo/README.md
+++ b/agents/demo/README.md
@@ -1,65 +1,3 @@
 # Demo
 
 This agent serves as a demo to guide agent development and showcase various agent capabilities.
-
-## index.yaml
-
-This file defines the agent.
-
-### variables
-
-Variables are generally used to store information about a user's behavior or preferences.
-
-```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 in the `instructions` and tools script.
-
-```yaml
-instructions: |
-  The instructions can access variables {{foo}} and {{bar}}.
-```
-
-```sh
-echo "The tools script can access environment variables $LLM_AGENT_VAR_FOO and $LLM_AGENT_VAR_BAR"
-```
-
-### documents
-
-Documents are used for RAG, supporting local files/dirs and remote URLs.
-
-```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).
-
-## tools.{sh,js,py}
-
-The tool script implements agent-specific tools.
-
-## tools.txt
-
-The `tools.txt` file enables tool reuse from the `/tools` folder in this project.
diff --git a/docs/agent.md b/docs/agent.md
new file mode 100644
index 0000000..802108d
--- /dev/null
+++ b/docs/agent.md
@@ -0,0 +1,106 @@
+# 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.
diff --git a/docs/environment-variables.md b/docs/environment-variables.md
new file mode 100644
index 0000000..8c13b64
--- /dev/null
+++ b/docs/environment-variables.md
@@ -0,0 +1,26 @@
+# Environment Variables
+
+## Injected by `run-tool.*`/`run-agent.*`
+
+| Name                  | Description                                                                                                          |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `LLM_ROOT_DIR`        | Path to `<llm-functions-dir>`                                                                                        |
+| `LLM_TOOL_NAME`       | Tool name, such as `execute_command`                                                                                 |
+| `LLM_TOOL_CACHE_DIR`  | Path to `<llm-functions-dir>/cache/<tool-name>`,<br>The tool script can use this directory to store some cache data  |
+| `LLM_AGENT_NAME`      | Agent name, such as `todo`                                                                                           |
+| `LLM_AGENT_FUNC`      | Agent function, such as `list_todos`                                                                                 |
+| `LLM_AGENT_ROOT_DIR`  | Path to `<llm-functions-dir>/agents/<agent-name>`                                                                    |
+| `LLM_AGENT_CACHE_DIR` | Path to `<llm-functions-dir>/cache/<agent-name>`,<br>The tool script can use this directory to store some cache data |
+
+## Injected by runtime (AIChat)
+
+| Name                   | Description                                          |
+| ---------------------- | ---------------------------------------------------- |
+| `LLM_OUTPUT`           | File to store the the execution results of the tool. |
+| `LLM_AGENT_VAR_<NAME>` | Agent variables.                                     |
+
+## Provided by users
+
+| Name               | Description                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| `LLM_DUMP_RESULTS` | Controls whether to print the execution results of the tool, e.g. `get_current_weather\|fs.*` |