refactor: add docs (#143)

2024-12-12 10:31:37 +08:00
parent 7e88e70e17
commit 2fc9b47690
3 changed files with 132 additions and 62 deletions
@@ -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.