From 530e7d5df68e5010b8a86df495b4caf96886969f Mon Sep 17 00:00:00 2001 From: nrosa-valory Date: Mon, 13 Jan 2025 16:49:36 +0000 Subject: [PATCH] Documentation general improvements (#2291) * Addition of examples for analyse logs command on advance reference section * Addition of autonomy develop and push-all command documentation * Addition of introduction pages for sections: - Advanced Reference > Commands - Configure Service - Get Started * Fix typos and some generic text improvements --------- Co-authored-by: Naiane B --- .../commands/autonomy_analyse.md | 39 +++++++++++- .../commands/autonomy_deploy.md | 19 ++++-- .../commands/autonomy_develop.md | 26 ++++++++ .../commands/autonomy_fetch.md | 22 ++++++- .../commands/autonomy_push_all.md | 21 +++++++ .../commands/autonomy_replay.md | 2 +- docs/advanced_reference/commands/index.md | 62 +++++++++++++++++++ docs/advanced_reference/index.md | 3 +- docs/configure_service/index.md | 11 ++++ docs/get_started/index.md | 37 +++++++++++ docs/guides/index.md | 2 + mkdocs.yml | 9 ++- 12 files changed, 242 insertions(+), 11 deletions(-) create mode 100644 docs/advanced_reference/commands/autonomy_develop.md create mode 100644 docs/advanced_reference/commands/autonomy_push_all.md create mode 100644 docs/advanced_reference/commands/index.md create mode 100644 docs/configure_service/index.md create mode 100644 docs/get_started/index.md diff --git a/docs/advanced_reference/commands/autonomy_analyse.md b/docs/advanced_reference/commands/autonomy_analyse.md index 029afb10eb..a16e74a03d 100644 --- a/docs/advanced_reference/commands/autonomy_analyse.md +++ b/docs/advanced_reference/commands/autonomy_analyse.md @@ -260,9 +260,44 @@ autonomy analyse logs [OPTIONS] : Show the help message and exit. ### Examples -!!! info - This section will be added soon. +Analyze logs from the build directory `./abci_build_hAsH/persistent_data/logs` for 2 agents: + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' -a 'aea_1' +``` + +View logs for 2 agents between specific times: + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --start-time "2024-01-20 10:00:00,000" --end-time "2024-01-20 11:00:00,000" +``` + +View logs for period `2` and round `RegistrationRound`: + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --period 2 --round RegistrationRound +``` + +View only the FSM state transitions: + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --fsm +``` + +Filter by log level `ERROR` and behaviour `RegistrationBehaviour`: + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --log-level ERROR --behaviour RegistrationBehaviour +``` + +Use regex patterns to filter logs, include lines with `consensus` and exclude lines with `debug` + +```bash +autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' -ir ".*consensus.*" -er ".*debug.*" +``` + +These examples demonstrate various ways to filter and analyze agent service logs. You can combine multiple options to narrow down the log output to exactly what you need for debugging or analysis. ## `autonomy analyse benchmarks` diff --git a/docs/advanced_reference/commands/autonomy_deploy.md b/docs/advanced_reference/commands/autonomy_deploy.md index 1b934a9f1a..03677b4bc3 100644 --- a/docs/advanced_reference/commands/autonomy_deploy.md +++ b/docs/advanced_reference/commands/autonomy_deploy.md @@ -102,11 +102,14 @@ autonomy deploy build [OPTIONS] [KEYS_FILE] `--agent-memory-limit INTEGER` : Set agent memory usage limit. -`--remote`` -: To use `a remote registry. +`--number-of-services INTEGER` + Number of services (i.e., separate deployment folders) to build. Default is 1. -`--local`` -: To use `a local registry. +`--remote` +: To use a remote registry. + +`--local` +: To use a local registry. `-p` : Ask for password interactively. @@ -123,6 +126,14 @@ autonomy deploy build keys.json -ltm Builds a service deployment using the keys stored in the file `keys.json` and applying environment variables to the service configuration file. The deployment will be generated by default for as many agents as keys are stored in `keys.json`. By default, the command searches for the file `keys.json`, if no file name is provided. +You can build multiple service deployments at once using the `--number-of-services` parameter. Each service will be created in its own `abci_build_*` folder: + +```bash +autonomy deploy build --number-of-services 2 keys.json +``` + +Note: Use `--n` to set the number of agents per service, and use `--number-of-services` to build multiple separate services at once. + If you are manually defining `keys.json` make sure to include `ledger` property for a key object. This will be used when writing key files to the deployment environment. If you don't specify the property `ethereum` will be used as default ledger identifier, so if you're running an agent against a different ledger (eg. `solana`) you'll have to specify this property manually like this ```json diff --git a/docs/advanced_reference/commands/autonomy_develop.md b/docs/advanced_reference/commands/autonomy_develop.md new file mode 100644 index 0000000000..f39c5c013f --- /dev/null +++ b/docs/advanced_reference/commands/autonomy_develop.md @@ -0,0 +1,26 @@ +Development tools for agent services. + +## Usage +```bash +autonomy develop [OPTIONS] COMMAND [ARGS]... +``` + +## Options +`--help` +: Show the help message and exit. + +## `autonomy develop service-registry-network` +Run service registry contracts locally. + +### Usage +```bash +autonomy develop service-registry-network [OPTIONS] +``` + +### Examples + +Run service registry contracts locally + +```bash +autonomy develop service-registry-network +``` \ No newline at end of file diff --git a/docs/advanced_reference/commands/autonomy_fetch.md b/docs/advanced_reference/commands/autonomy_fetch.md index ec89205071..13cb177ca3 100644 --- a/docs/advanced_reference/commands/autonomy_fetch.md +++ b/docs/advanced_reference/commands/autonomy_fetch.md @@ -1,4 +1,5 @@ Fetch an agent or agent service from a registry using its public ID, hash, or token ID. +The `autonomy fetch` command allows you to download service files from either a local or remote registry. ## Usage ```bash @@ -95,7 +96,7 @@ Fetch the agent service `hello_world` from a local registry with an explicit pat autonomy --registry-path=./packages fetch valory/hello_world:0.1.0 --service --local ``` -Fetch the agent service `hello_world` from a remote registry ([IPFS](https://ipfs.io)): +Fetch the agent service `hello_world` from a remote registry using [IPFS](https://ipfs.io) hash: ```bash autonomy fetch valory/hello_world:0.1.0:bafybeihl6j7ihkytk4t4ca2ffhctpzydwi6r4a354ubjasttuv2pw4oaci --service --remote ``` @@ -104,3 +105,22 @@ Fetch the agent service with the token ID `123` on Gnosis chain: ```bash autonomy fetch 123 --use-gnosis ``` + +### Viewing Remote Registry Files + +Before fetching a service, you can inspect its contents in on IPFS through `https://gateway.autonolas.tech/ipfs//` + +## Common Issues and Solutions + +### Service Not Found +- Verify the service ID is correct +- Check registry connection +- Ensure you're using the correct registry flag (--local or --remote) + +### Missing Dependencies +- Run `autonomy packages sync` to update local packages +- Check service requirements in `service.yaml` + +### Permission Issues +- Verify write permissions in packages directory +- Run with appropriate permissions \ No newline at end of file diff --git a/docs/advanced_reference/commands/autonomy_push_all.md b/docs/advanced_reference/commands/autonomy_push_all.md new file mode 100644 index 0000000000..9e6182a2ae --- /dev/null +++ b/docs/advanced_reference/commands/autonomy_push_all.md @@ -0,0 +1,21 @@ + +Push all available packages to a registry. + +## Usage +```bash +autonomy push-all [OPTIONS] +``` + +## Options +`--packages-dir PATH` +: Path to the packages directory. + +`--help` +: Show the help message and exit. + +## Examples +Push all packages + +```bash +autonomy push-all --packages-dir ./packages +``` \ No newline at end of file diff --git a/docs/advanced_reference/commands/autonomy_replay.md b/docs/advanced_reference/commands/autonomy_replay.md index e13dfa8cd9..b4520cb223 100644 --- a/docs/advanced_reference/commands/autonomy_replay.md +++ b/docs/advanced_reference/commands/autonomy_replay.md @@ -44,4 +44,4 @@ Tendermint runner. ## Examples -Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md). +Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md). \ No newline at end of file diff --git a/docs/advanced_reference/commands/index.md b/docs/advanced_reference/commands/index.md new file mode 100644 index 0000000000..7b0c79b02c --- /dev/null +++ b/docs/advanced_reference/commands/index.md @@ -0,0 +1,62 @@ +# Open Autonomy CLI Overview + +This page provides a quick reference to commonly used CLI commands in the Open Autonomy framework. Each command has a brief description and basic usage example, with links to more detailed documentation. + +## Core Commands + +### autonomy analyse +Analyse an agent service, including ABCI app specifications, docstrings, logs, and more. + +[Detailed analyse documentation](./advanced_reference/commands/autonomy_analyse.md) + +### autonomy deploy +Deploy an agent service using various deployment backends (Docker, Kubernetes, or localhost). + +[Detailed deploy documentation](./advanced_reference/commands/autonomy_deploy.md) + +### autonomy develop +Development tools for agent services. + +[Detailed develop documentation](./advanced_reference/commands/autonomy_develop.md) + +### autonomy fetch +Fetch an agent or service from a registry. + +[Detailed fetch documentation](./advanced_reference/commands/autonomy_fetch.md) + +### autonomy mint +Mint components and services on-chain. + +[Detailed mint documentation](./advanced_reference/commands/autonomy_mint.md) + +### autonomy push-all +Push all available packages to a registry. + +[Detailed push-all documentation](./advanced_reference/commands/autonomy_push_all.md) + +### autonomy replay +Replay tools for agent services. + +[Detailed replay documentation](./advanced_reference/commands/autonomy_replay.md) + +### autonomy service +Manage on-chain services. + +[Detailed service documentation](./advanced_reference/commands/autonomy_service.md) + +## Additional Information + +- Most commands support the `--help` flag for detailed usage information +- Commands that interact with blockchains typically require a key file +- Many commands have additional options for customization and configuration +- See the [detailed command reference](./advanced_reference/commands/autonomy_analyse.md) for complete documentation of each command + +## Common Options + +Many commands share common options: + +- `--registry`: Specify the registry to use (default: remote) +- `--chain`: Select blockchain network (e.g., ethereum, polygon) +- `--key`: Path to key file for blockchain transactions +- `--password`: Password for encrypted key files +- `--help`: Show help message and exit \ No newline at end of file diff --git a/docs/advanced_reference/index.md b/docs/advanced_reference/index.md index 4759685044..723e49a9fb 100644 --- a/docs/advanced_reference/index.md +++ b/docs/advanced_reference/index.md @@ -1,4 +1,5 @@ -#Advanced reference - index +# Advanced reference + In this section you will find advanced developer topics such as the API and CLI documentation, debugging tools and other topics relevant for the development of agent services with the {{open_autonomy}} framework. \ No newline at end of file diff --git a/docs/configure_service/index.md b/docs/configure_service/index.md new file mode 100644 index 0000000000..5942247105 --- /dev/null +++ b/docs/configure_service/index.md @@ -0,0 +1,11 @@ +# Configure Service + +This section provides detailed information and guides for configuring an agent service. +Here you will find: + +- [The service configuration file](./service_configuration_file.md): Learn how to set up and customize your service's configuration +- [Configure access to external chains](./configure_access_external_chains.md): Guide for configuring your service to work with different blockchain networks +- [On-chain deployment checklist](./on-chain_deployment_checklist.md): Requirements and steps for deploying your service on-chain +- [Analyze and test](./analyze_test.md): Tools and practices for testing and analyzing your service + +These guides will help you properly configure and validate your agent service for both development and production environments. \ No newline at end of file diff --git a/docs/get_started/index.md b/docs/get_started/index.md new file mode 100644 index 0000000000..1c983269fd --- /dev/null +++ b/docs/get_started/index.md @@ -0,0 +1,37 @@ +# Getting Started + +Welcome to the Open Autonomy Framework documentation! This section will help you understand and get started with building your own agent services. + +## What are Agent Services? + +Agent services are decentralized off-chain services that run as multi-agent systems and are secured on public blockchains. They enable complex processing and autonomous actions while maintaining decentralization, trust-minimization, transparency, and robustness. + +## Key Topics + +1. [What is an Agent Service?](./what_is_an_agent_service.md) + Learn about the architecture and components of agent services, including how they work and interact with blockchain networks. + +2. [Why do we need Agent Services?](./why_do_we_need_agent_services.md) + Understand the challenges in blockchain technology that agent services address and their role in the crypto ecosystem. + +3. [Use cases](./use_cases.md) + Explore practical applications of agent services, from DAO operations to customizable infrastructure solutions. + +4. [Agent Services compared](./agent_services_compared_to.md) + See how agent services compare to other software solutions and understand when to use them. + +## Next Steps + +After understanding the basics of agent services, you can: + +- Follow our [Quick Start Guide](../guides/quick_start.md) to build your first agent service +- Learn about the [Development Process](../guides/overview_of_the_development_process.md) +- Explore [Key Concepts](../key_concepts/index.md) in depth + +## Need Help? + +If you have questions or need assistance: + +- Check our [Questions and Answers](../questions-and-answers.md) section +- Join our community on [Discord](https://discord.com/invite/z2PT65jKqQ) +- Visit the [Autonolas website](https://www.autonolas.network/) for more resources \ No newline at end of file diff --git a/docs/guides/index.md b/docs/guides/index.md index dfa52a4fc3..6e58c24247 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,3 +1,5 @@ +# Guides + In this section you will find a number of useful guides which will help you to understand [the overall development process](./overview_of_the_development_process.md) of an agent service with the {{open_autonomy}} framework, including: diff --git a/mkdocs.yml b/mkdocs.yml index 174a4f9443..ce383e4894 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,10 +36,11 @@ extra_css: nav: - Home: 'index.md' - Get started: + - 'get_started/index.md' - What is an agent service: 'get_started/what_is_an_agent_service.md' - Why do we need agent services: 'get_started/why_do_we_need_agent_services.md' - - Agent services compared to...: 'get_started/agent_services_compared_to.md' - Use cases: 'get_started/use_cases.md' + - Agent services compared: 'get_started/agent_services_compared_to.md' - Guides: - 'guides/index.md' - Set up: 'guides/set_up.md' @@ -68,6 +69,7 @@ nav: - Sequence diagram: 'key_concepts/poc-diagram.md' - Threat model: 'key_concepts/threat_model.md' - Configure the service: + - 'configure_service/index.md' - The service configuration file: 'configure_service/service_configuration_file.md' - Configure access to external chains: 'configure_service/configure_access_external_chains.md' - On-chain deployment checklist: 'configure_service/on-chain_deployment_checklist.md' @@ -76,6 +78,7 @@ nav: - 'advanced_reference/index.md' # - publish fetch: 'guides/publish_fetch_packages.md' - Commands: + - 'advanced_reference/commands/index.md' - autonomy deploy: 'advanced_reference/commands/autonomy_deploy.md' - autonomy build-image: 'advanced_reference/commands/autonomy_build-image.md' - autonomy replay: 'advanced_reference/commands/autonomy_replay.md' @@ -83,7 +86,9 @@ nav: - autonomy fetch: 'advanced_reference/commands/autonomy_fetch.md' - autonomy scaffold: 'advanced_reference/commands/autonomy_scaffold.md' - autonomy mint: 'advanced_reference/commands/autonomy_mint.md' - - autonomy service: 'advanced_reference/commands/autonomy_service.md' + - autonomy service: 'advanced_reference/commands/autonomy_service.md' + - autonomy develop: 'advanced_reference/commands/autonomy_develop.md' + - autonomy push-all: 'advanced_reference/commands/autonomy_push_all.md' - Developer tooling: - Dev mode: 'advanced_reference/developer_tooling/dev_mode.md' - Execution replay: 'advanced_reference/developer_tooling/execution_replay.md'