diff options
| -rw-r--r-- | agents/demo/README.md | 62 | ||||
| -rw-r--r-- | docs/agent.md | 106 | ||||
| -rw-r--r-- | docs/environment-variables.md | 26 |
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.*` | |