diff --git a/agentstack/cli/init.py b/agentstack/cli/init.py
index b215ea23..6e3299ae 100644
--- a/agentstack/cli/init.py
+++ b/agentstack/cli/init.py
@@ -36,6 +36,41 @@ def require_uv():
raise EnvironmentError(message)
+def prompt_slug_name() -> str:
+ """Prompt the user for a project name."""
+
+ def _validate(slug_name: Optional[str]) -> bool:
+ if not slug_name:
+ log.error("Project name cannot be empty")
+ return False
+
+ if not is_snake_case(slug_name):
+ log.error("Project name must be snake_case")
+ return False
+
+ if os.path.exists(conf.PATH / slug_name):
+ log.error(f"Project path already exists: {conf.PATH / slug_name}")
+ return False
+
+ return True
+
+ def _prompt() -> str:
+ return inquirer.text(
+ message="Project name (snake_case)",
+ )
+
+ log.info(
+ "Provide a project name. This will be used to create a new directory in the "
+ "current path and will be used as the project name. 🐍 Must be snake_case."
+ )
+ slug_name = None
+ while not _validate(slug_name):
+ slug_name = _prompt()
+
+ assert slug_name # appease type checker
+ return slug_name
+
+
def select_template(slug_name: str, framework: Optional[str] = None) -> TemplateConfig:
"""Let the user select a template from the ones available."""
templates: list[TemplateConfig] = get_all_templates()
@@ -85,22 +120,11 @@ def init_project(
welcome_message()
if not slug_name:
- log.info(
- "Provide a project name. This will be used to create a new directory in the "
- "current path and will be used as the project name. 🐍 Must be snake_case."
- )
- slug_name = inquirer.text(
- message="Project name (snake_case)",
- )
-
- if not slug_name:
- raise Exception("Project name cannot be empty")
- if not is_snake_case(slug_name):
- raise Exception("Project name must be snake_case")
+ slug_name = prompt_slug_name()
conf.set_path(conf.PATH / slug_name)
- if os.path.exists(conf.PATH): # cookiecutter requires the directory to not exist
- raise Exception(f"Directory already exists: {conf.PATH}")
+ # cookiecutter requires the directory to not exist
+ assert not os.path.exists(conf.PATH), f"Directory already exists: {conf.PATH}"
if use_wizard:
log.debug("Initializing new project with wizard.")
diff --git a/agentstack/cli/spinner.py b/agentstack/cli/spinner.py
new file mode 100644
index 00000000..dc70ba58
--- /dev/null
+++ b/agentstack/cli/spinner.py
@@ -0,0 +1,95 @@
+import itertools
+import shutil
+import sys
+import threading
+import time
+from typing import Optional, Literal
+
+from agentstack import log
+
+
+class Spinner:
+ def __init__(self, message="Working", delay=0.1):
+ self.spinner = itertools.cycle(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'])
+ self.delay = delay
+ self.message = message
+ self.running = False
+ self.spinner_thread = None
+ self.start_time = None
+ self._lock = threading.Lock()
+ self._last_printed_len = 0
+ self._last_message = ""
+
+ def _clear_line(self):
+ """Clear the current line in terminal."""
+ sys.stdout.write('\r' + ' ' * self._last_printed_len + '\r')
+ sys.stdout.flush()
+
+ def spin(self):
+ while self.running:
+ with self._lock:
+ elapsed = time.time() - self.start_time
+ terminal_width = shutil.get_terminal_size().columns
+ spinner_char = next(self.spinner)
+ time_str = f"{elapsed:.1f}s"
+
+ # Format: [spinner] Message... [time]
+ message = f"\r{spinner_char} {self.message}... [{time_str}]"
+
+ # Ensure we don't exceed terminal width
+ if len(message) > terminal_width:
+ message = message[:terminal_width - 3] + "..."
+
+ # Clear previous line and print new one
+ self._clear_line()
+ sys.stdout.write(message)
+ sys.stdout.flush()
+ self._last_printed_len = len(message)
+
+ time.sleep(self.delay)
+
+ def __enter__(self):
+ self.start()
+ return self
+
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ self.stop()
+
+ def start(self):
+ if not self.running:
+ self.running = True
+ self.start_time = time.time()
+ self.spinner_thread = threading.Thread(target=self.spin)
+ self.spinner_thread.start()
+
+ def stop(self):
+ if self.running:
+ self.running = False
+ if self.spinner_thread:
+ self.spinner_thread.join()
+ with self._lock:
+ self._clear_line()
+
+ def update_message(self, message):
+ """Update spinner message and ensure clean line."""
+ with self._lock:
+ self._clear_line()
+ self.message = message
+
+ def clear_and_log(self, message, color: Literal['success', 'info'] = 'success'):
+ """Temporarily clear spinner, print message, and resume spinner.
+ Skips printing if message is the same as the last message printed."""
+ with self._lock:
+ # Skip if message is same as last one
+ if hasattr(self, '_last_message') and self._last_message == message:
+ return
+
+ self._clear_line()
+ if color == 'success':
+ log.success(message)
+ else:
+ log.info(message)
+ sys.stdout.flush()
+
+ # Store current message
+ self._last_message = message
\ No newline at end of file
diff --git a/agentstack/packaging.py b/agentstack/packaging.py
index 8f4f4a4d..e226db96 100644
--- a/agentstack/packaging.py
+++ b/agentstack/packaging.py
@@ -24,44 +24,49 @@
def install(package: str):
"""Install a package with `uv` and add it to pyproject.toml."""
+ from agentstack.cli.spinner import Spinner
+
def on_progress(line: str):
if RE_UV_PROGRESS.match(line):
- log.info(line.strip())
+ spinner.clear_and_log(line.strip(), 'info')
def on_error(line: str):
log.error(f"uv: [error]\n {line.strip()}")
-
- log.info(f"Installing {package}")
- _wrap_command_with_callbacks(
- [get_uv_bin(), 'add', '--python', '.venv/bin/python', package],
- on_progress=on_progress,
- on_error=on_error,
- )
+
+ with Spinner(f"Installing {package}") as spinner:
+ _wrap_command_with_callbacks(
+ [get_uv_bin(), 'add', '--python', '.venv/bin/python', package],
+ on_progress=on_progress,
+ on_error=on_error,
+ )
def install_project():
"""Install all dependencies for the user's project."""
+ from agentstack.cli.spinner import Spinner
+
def on_progress(line: str):
if RE_UV_PROGRESS.match(line):
- log.info(line.strip())
+ spinner.clear_and_log(line.strip(), 'info')
def on_error(line: str):
log.error(f"uv: [error]\n {line.strip()}")
try:
- result = _wrap_command_with_callbacks(
- [get_uv_bin(), 'pip', 'install', '--python', '.venv/bin/python', '.'],
- on_progress=on_progress,
- on_error=on_error,
- )
- if result is False:
- log.info("Retrying uv installation with --no-cache flag...")
- _wrap_command_with_callbacks(
- [get_uv_bin(), 'pip', 'install', '--no-cache', '--python', '.venv/bin/python', '.'],
+ with Spinner(f"Installing project dependencies.") as spinner:
+ result = _wrap_command_with_callbacks(
+ [get_uv_bin(), 'pip', 'install', '--python', '.venv/bin/python', '.'],
on_progress=on_progress,
on_error=on_error,
)
+ if result is False:
+ spinner.clear_and_log("Retrying uv installation with --no-cache flag...", 'info')
+ _wrap_command_with_callbacks(
+ [get_uv_bin(), 'pip', 'install', '--no-cache', '--python', '.venv/bin/python', '.'],
+ on_progress=on_progress,
+ on_error=on_error,
+ )
except Exception as e:
log.error(f"Installation failed: {str(e)}")
raise
diff --git a/docs/llms.txt b/docs/llms.txt
index fa23ea5c..e904cfa5 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -1,73 +1,3 @@
-## introduction.mdx
-
----
-title: Introduction
-description: 'The easiest way to start your agent project'
-icon: 'hand-point-up'
----
-
-
-
-
-AgentStack is a valuable developer tool for quickly scaffolding agent projects.
-
-_Think `create-next-app` for Agents._
-
-### Features of AgentStack
-- Instant project setup with `agentstack init`
-- Useful CLI commands for generating new agents and tasks in the development cycle
-- A myriad of pre-built tools for Agents
-
-## What is _the agent stack_
-The agent stack is the list of tools that are collectively the _agent stack_.
-
-This is similar to the tech stack of a web app. An agent's tech stack is comprised of the following:
-
-
-
-Whether a project is built with AgentStack or not, the concept of the agent stack remains the same.
-
-## What is **AgentStack**
-Our project is called **AgentStack** because it's the easiest way to quickly scaffold your agent stack! With a couple CLI commands, you can create a near-production ready agent!
-
-## First Steps
-
-
-
- Install the AgentStack CLI
-
-
- A quickstart guide to using the CLI
-
-
- High level overview of AgentStack
- 
-
-
- Build a simple web scraper agent
- 
-
-
-
## installation.mdx
---
@@ -180,128 +110,263 @@ To generate a new task, run `agentstack generate task ` - [More Info]
-## contributing/adding-tools.mdx
+## introduction.mdx
---
-title: 'Adding Tools'
-description: 'Contribute your own Agent tool to the ecosystem'
+title: Introduction
+description: 'The easiest way to start your agent project'
+icon: 'hand-point-up'
---
-If you're reading this section, you probably have a product that AI agents can use as a tool. We're glad you're here!
-
-Adding tools is easy once you understand the project structure. A few things need to be done for a tool to be considered completely supported:
+
+
-
-
- - Create a new tool config at `agentstack/_tools//config.json`
- - As an example, look at our [tool config fixture](https://github.com/AgentOps-AI/AgentStack/blob/main/tests/fixtures/tool_config_max.json)
- - AgentStack uses this to know what code to insert where. Follow the structure to add your tool.
-
-
- - In `agentstack/_tools`, you'll see other implementations of tools.
- - Create a file `agentstack/_tools//__init__.py`,
- - Build your tool implementation simply as python functions in this file. The functions that are to be exposed to the agent as a *tool* should contain detailed docstrings and have typed parameters.
- - The tools that are exported from this file should be listed in the tool's config json.
-
-
- Manually test your tool integration by running `agentstack tools add ` and ensure it behaves as expected.
- This must be done within an AgentStack project. To create your test project, run `agentstack init test_proj`, then `cd` into the project and try adding your tool.
-
-
-
-
+AgentStack is a valuable developer tool for quickly scaffolding agent projects.
-# Tool Config
-- `name` (str) - Name of your tool
-- `category` (str) - Category your tool belongs in
-- `tools` (List[str]) - The exported functions within your tool file
-- `url` (str) - URL to where developers can learn more about your tool
-- `tools_bundled` (bool) - True if the tool file exports a list of tools
-- `cta` (str) - Call To Action printed in the terminal after install
-- `env` (dict) - Key: Environment variable name; Value: default value
-- `packages` (List[str]) - Python packages to be installed to support your tool
-- `post_install` (str) - A script to be run after install of your tool
-- `post_remove` (str) - A script to be run after removal of your tool
+_Think `create-next-app` for Agents._
-## contributing/how-to-contribute.mdx
+### Features of AgentStack
+- Instant project setup with `agentstack init`
+- Useful CLI commands for generating new agents and tasks in the development cycle
+- A myriad of pre-built tools for Agents
----
-title: 'How To Contribute'
-description: 'Contribute your own Agent tool to the ecosystem'
----
+## What is _the agent stack_
+The agent stack is the list of tools that are collectively the _agent stack_.
-First of all, __thank you__ for your interest in contributing to AgentStack! Even the smallest contributions help a _ton_.
+This is similar to the tech stack of a web app. An agent's tech stack is comprised of the following:
-Our vision is to build the de facto CLI for quickly spinning up an AI Agent project. We want to be the [create-react-app](https://create-react-app.dev/) of agents. Our inspiration also includes the oh-so-convenient [Angular CLI](https://v17.angular.io/cli).
+
-## How to Help
+Whether a project is built with AgentStack or not, the concept of the agent stack remains the same.
-Grab an issue from the [issues tab](https://github.com/AgentOps-AI/AgentStack/issues)! Plenty are labelled "Good First Issue". Fork the repo and create a PR when ready!
+## What is **AgentStack**
+Our project is called **AgentStack** because it's the easiest way to quickly scaffold your agent stack! With a couple CLI commands, you can create a near-production ready agent!
-The best place to engage in conversation about your contribution is in the Issue chat or on our [Discord](https://discord.gg/JdWkh9tgTQ).
+## First Steps
-## Setup
+
+
+ Install the AgentStack CLI
+
+
+ A quickstart guide to using the CLI
+
+
+ High level overview of AgentStack
+ 
+
+
+ Build a simple web scraper agent
+ 
+
+
-1. `git clone https://github.com/AgentOps-AI/AgentStack.git`
- `cd AgentStack`
-2. `uv pip install -e ".[dev,test]`
- - This will install the CLI locally and in editable mode so you can use `agentstack ` to test your latest changes
- - Note that after you initialize a project, it will install it's own version of `agentstack` in the project's
- virtual environment. To use your local version, run `uv pip install -e "../AgentStack/.[]"` to get
- your development version inside of the project, too.
+## cli-reference/cli.mdx
-## Project Structure
+---
+title: 'CLI Reference'
+description: 'Everything to do with the CLI'
+---
-A detailed overview of the project structure is available at [Project Structure](https://docs.agentstack.sh/contributing/project-structure).
+It all starts with calling
+```bash
+$ agentstack
+```
+### Shortcut Aliases
+Many top-level AgentStack commands can be invoked using a single-letter prefix to save keystrokes. These are indicated
+in the command's documentation here after a `|` character. Run `agentstack help` for the full list.
-## Before Making a Pull Request
+### Global Flags
+These flags work with all commands:
-Make sure tests pass, type checking is correct, and ensure your code is formatted correctly.
+`--debug` - Print a full traceback when an error is encountered. This also enables printing additional debug information
+from within AgentStack useful for development and debugging.
-1. `tox -m quick`
- - This will run tests for Python version 3.12 only. You can run tests on all supported versions with `tox`.
-2. `mypy agentstack`
- - Please resolve all type checking errors before marking your PR as ready for review.
-3. `ruff`
- - We use `ruff` to ensure consistency in our codebase.
+`--path=` - Set the working directory of the current AgentStack project. By default `agentstack` works inside of the
+current directory and looks for an `agentstack.json` file there. By passing a path to this flag you can work on a project
+from outside of it's directory.
-## Tests
+`--version` - Prints the current version and exits.
-We're actively working toward increasing our test coverage. Make sure to review the `codecov` output of your
-tests to ensure your contribution is well tested. We use `tox` to run our tests, which sets up individual
-environments for each framework and Python version we support. Tests are run when a PR is pushed to, and
-contributions without passing tests will not be merged.
-You can test a specific Python version and framework by running: `tox -e py312-`, but keep in mind
-that the coverage report will be incomplete.
+## `$ agentstack init`
+This initializes a new AgentStack project.
+```bash
+agentstack init
+```
-## contributing/project-structure.mdx
+`slug_name` is the name of your project, and will be created as a directory to initialize your project inside. When the
+default arguments are passed, a starter project template will be used, which adds a single agent, a single task and
+demonstrates the use of a tool.
----
-title: 'Project Structure'
-description: 'Concepts and Structure of AgentStack'
----
+### Init Creates a Virtual Environment
+AgentStack creates a new directory, initializes a new virtual environment, installs dependencies, and populates the project
+structure. After `init` completes, `cd` into the directory, activate the virtual environment with `source .venv/bin/activate`.
+Virtual environments and package management are handled by the `uv` package manager.
-> This document is a work-in-progress as we build to version 0.3 and helps
-define the structure of the project that we are aiming to create.
+### Initializing with the Wizard
+You can pass the `--wizard` flag to `agentstack init` to use an interactive project configuration wizard.
-AgentStack is a framework-agnostic toolkit for bootstrapping and managing
-AI agents. Out of the box it has support for a number of tools and generates
-code to get your project off the ground and deployed to a production environment.
-It also aims to provide robust tooling for running and managing agents including
-logging, debugging, deployment, and observability via [AgentOps](https://www.agentops.ai/).
+### Initializing from a Template
+You can also pass a `--template=` argument to `agentstack init` which will pre-populate your project with functionality
+from a built-in template, or one found on the internet. A `template_name` can be one of three identifiers:
-Developers with limited agent experience should be able to get an agentic
-workflow up and running in a matter of minutes. Developers with more experience
-should be able to leverage the tools provided by AgentStack to create more
-complex workflows and deploy them to production with ease.
+- A built-in AgentStack template (see the `templates` directory in the AgentStack repo for bundled templates).
+- A template file from the internet; pass the full https URL of the template.
+- A local template file; pass an absolute or relative path.
-# Concepts
-## Projects
-A project is a user's implementation of AgentStack that is used to implement
-and agentic workflow. This is a directory the `agentstack` shell command is
+## `$ agentstack run`
+This runs your AgentStack project.
+```bash
+agentstack run
+```
+
+Environment variables will be loaded from `~/.env` and from the `.env` file inside your project directory. Make sure you
+have enabled your project's `venv` before executing to include all dependencies required.
+
+### Overriding Inputs
+Your project defines Inputs which are used to customize the Agent and Task prompts for a specific task. In cases where
+using the `inputs.yaml` file to populate data is not flexible enough, `run` can accept value overrides for all defined
+inputs. Use `--input-=` to pass data which will only be used on this run.
+
+For example, if you have a key in your `inputs.yaml` file named `topic` and want to override it for this run, you would
+use the following command:
+
+```bash
+agentstack run --input-topic=Sports
+```
+
+### Running other project commands
+By default, `run` will call the `main()` function inside your project's `main.py` file. You can pass alternate function
+names to run with `--function=`.
+
+
+## Generate
+Code generation commands for automatically creating new agents or tasks.
+
+### `$ agentstack generate agent | agentstack g a`
+Generate a new agent
+- `agent_name` (required | str) - the name of the agent
+- `--role` (optional | str) - Prompt parameter: The role of the agent
+- `--goal` (optional | str) - Prompt parameter: The goal of the agent
+- `--backstory` (optional | str) - Prompt parameter: The backstory of the agent
+- `--llm` (optional | `/`) - Which model to use for this agent
+
+#### Default LLM
+All arguments to generate a new Agent are optional. A default LLM can be configured in `agentstack.json`under the
+`default_model` setting to populate a provider/model. If you are generating an agent in a project which does not have
+a default model set, you will be prompted to configure one.
+
+#### Example
+```bash Generate Agent
+agentstack generate agent script_writer
+```
+
+### `$ agentstack generate task | agentstack g t`
+Generate a new task
+- `task_name` (required | str) - the name of the task
+- `--description` (optional | str) - Prompt parameter: Explain the task in detail
+- `--expected_output` (optional | str) - What is the expected output from the agent (ex: data in json format)
+- `--agent` (optional | str) - The name of the agent of which to assign the task to (when using Crew in sequential mode)
+
+#### Example
+```bash Generate Task
+agentstack g t gen_script --description "Write a short film script about secret agents"
+```
+
+## Tools
+Tools are what make AgentStack powerful. Adding and removing Tools from Agents is easy with this command.
+
+### `$ agentstack tools list | agentstack t l`
+Lists all tools available in AgentStack.
+
+### `$ agentstack tools add | agentstack t a`
+Shows an interactive interface for selecting which Tool to add and which Agents to add it to.
+
+#### Add a Tool to all Agents
+When a tool_name is provided it will be made available to all Agents in the project.
+```bash
+$ agentstack tools add
+```
+
+#### Add a Tool to a single Agent
+When an agent_name is provided, the tool will be made available to only that agent.
+```bash
+$ agentstack tools add --agent=
+```
+
+#### Add a Tool to multiple Agents
+When a comma-separated list of Agents is passed, the tool will be made available to those agents.
+```bash
+$ agentstack tools add --agents=,,
+```
+
+### `$ agentstack tools remove `
+Removes a tool from all Agents in the project.
+
+
+## Templates
+Projects can be exported into a template to facilitate sharing configurations. Re-initialize a project from a template
+with `agentstack init --template=`.
+
+### `$ agentstack export `
+The current project will be written to a JSON template at the provided filename.
+
+## `$ agentstack update`
+Check for updates and allow the user to install the latest release of AgentStack.
+
+## `$ agentstack login`
+Authenticate with [agentstack.sh](https://agentstack.sh) for hosted integrations.
+
+
+
+## contributing/project-structure.mdx
+
+---
+title: 'Project Structure'
+description: 'Concepts and Structure of AgentStack'
+---
+
+> This document is a work-in-progress as we build to version 0.3 and helps
+define the structure of the project that we are aiming to create.
+
+AgentStack is a framework-agnostic toolkit for bootstrapping and managing
+AI agents. Out of the box it has support for a number of tools and generates
+code to get your project off the ground and deployed to a production environment.
+It also aims to provide robust tooling for running and managing agents including
+logging, debugging, deployment, and observability via [AgentOps](https://www.agentops.ai/).
+
+Developers with limited agent experience should be able to get an agentic
+workflow up and running in a matter of minutes. Developers with more experience
+should be able to leverage the tools provided by AgentStack to create more
+complex workflows and deploy them to production with ease.
+
+# Concepts
+
+## Projects
+A project is a user's implementation of AgentStack that is used to implement
+and agentic workflow. This is a directory the `agentstack` shell command is
executed from.
## Frameworks
@@ -705,143 +770,118 @@ to OpenAI Swarms is contained in this package.
as a framework.
-## templates/system_analyzer.mdx
+## contributing/how-to-contribute.mdx
---
-title: 'System Analyzer'
-description: 'Inspect a project directory and improve it'
+title: 'How To Contribute'
+description: 'Contribute your own Agent tool to the ecosystem'
---
-[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/system_analyzer.json)
+First of all, __thank you__ for your interest in contributing to AgentStack! Even the smallest contributions help a _ton_.
-```bash
-agentstack init --template=system_analyzer
-```
+Our vision is to build the de facto CLI for quickly spinning up an AI Agent project. We want to be the [create-react-app](https://create-react-app.dev/) of agents. Our inspiration also includes the oh-so-convenient [Angular CLI](https://v17.angular.io/cli).
-# Purpose
+## How to Help
-This agent will accept a query as a string, use Perplexity to research it. Another agent will take the data gathered and perform an analysis focused on answering the query.
+Grab an issue from the [issues tab](https://github.com/AgentOps-AI/AgentStack/issues)! Plenty are labelled "Good First Issue". Fork the repo and create a PR when ready!
-# Inputs
+The best place to engage in conversation about your contribution is in the Issue chat or on our [Discord](https://discord.gg/JdWkh9tgTQ).
-`system_path` (str): the absolute path to
+## Setup
-## templates/researcher.mdx
+1. `git clone https://github.com/AgentOps-AI/AgentStack.git`
+ `cd AgentStack`
+2. `uv pip install -e ".[dev,test]`
+ - This will install the CLI locally and in editable mode so you can use `agentstack ` to test your latest changes
+ - Note that after you initialize a project, it will install it's own version of `agentstack` in the project's
+ virtual environment. To use your local version, run `uv pip install -e "../AgentStack/.[]"` to get
+ your development version inside of the project, too.
----
-title: 'Researcher'
-description: 'Research and report result from a query'
----
+## Project Structure
-[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/research.json)
+A detailed overview of the project structure is available at [Project Structure](https://docs.agentstack.sh/contributing/project-structure).
-```bash
-agentstack init --template=research
-```
-# Purpose
+## Before Making a Pull Request
-This agent will accept a query as a string, use Perplexity to research it. Another agent will take the data gathered and perform an analysis focused on answering the query.
+Make sure tests pass, type checking is correct, and ensure your code is formatted correctly.
-# Inputs
+1. `tox -m quick`
+ - This will run tests for Python version 3.12 only. You can run tests on all supported versions with `tox`.
+2. `mypy agentstack`
+ - Please resolve all type checking errors before marking your PR as ready for review.
+3. `ruff`
+ - We use `ruff` to ensure consistency in our codebase.
-`query` (str): the query for the agent to research and report on
+## Tests
-## templates/templates.mdx
+We're actively working toward increasing our test coverage. Make sure to review the `codecov` output of your
+tests to ensure your contribution is well tested. We use `tox` to run our tests, which sets up individual
+environments for each framework and Python version we support. Tests are run when a PR is pushed to, and
+contributions without passing tests will not be merged.
+
+You can test a specific Python version and framework by running: `tox -e py312-`, but keep in mind
+that the coverage report will be incomplete.
+
+## contributing/adding-tools.mdx
---
-title: 'Templates'
-description: 'Default AgentStack templates'
+title: 'Adding Tools'
+description: 'Contribute your own Agent tool to the ecosystem'
---
-_Templates are a really powerful tool within AgentStack!_
+If you're reading this section, you probably have a product that AI agents can use as a tool. We're glad you're here!
-# Start a new project with a template
-Initializing a new project with AgentStack involves adding just one argument:
-```bash
-agentstack init --template=
-```
+Adding tools is easy once you understand the project structure. A few things need to be done for a tool to be considered completely supported:
-Templates can also be passed as a URL. The URL should serve a valid json AgentStack template.
+
+
+ - Create a new tool config at `agentstack/_tools//config.json`
+ - As an example, look at our [tool config fixture](https://github.com/AgentOps-AI/AgentStack/blob/main/tests/fixtures/tool_config_max.json)
+ - AgentStack uses this to know what code to insert where. Follow the structure to add your tool.
+
+
+ - In `agentstack/_tools`, you'll see other implementations of tools.
+ - Create a file `agentstack/_tools//__init__.py`,
+ - Build your tool implementation simply as python functions in this file. The functions that are to be exposed to the agent as a *tool* should contain detailed docstrings and have typed parameters.
+ - The tools that are exported from this file should be listed in the tool's config json.
+
+
+ Manually test your tool integration by running `agentstack tools add ` and ensure it behaves as expected.
+ This must be done within an AgentStack project. To create your test project, run `agentstack init test_proj`, then `cd` into the project and try adding your tool.
+
+
+
+
-## Start Easier
-If you're struggling to get started with a project in AgentStack, a great way to better understand what to do is to start with a template!
+# Tool Config
+- `name` (str) - Name of your tool
+- `category` (str) - Category your tool belongs in
+- `tools` (List[str]) - The exported functions within your tool file
+- `url` (str) - URL to where developers can learn more about your tool
+- `tools_bundled` (bool) - True if the tool file exports a list of tools
+- `cta` (str) - Call To Action printed in the terminal after install
+- `env` (dict) - Key: Environment variable name; Value: default value
+- `packages` (List[str]) - Python packages to be installed to support your tool
+- `post_install` (str) - A script to be run after install of your tool
+- `post_remove` (str) - A script to be run after removal of your tool
-## Churn Faster
-Many contractors that build agent systems have a tried and true prompting method that they want to replicate more quickly.
-By creating your own template, you can quickly start projects that adhere to your design.
+## frameworks/list.mdx
-## For Content Creators
-Have a tutorial you've created using AgentStack? Make your project available as a quickstart with templates.
+---
+title: Frameworks
+description: 'Supported frameworks in AgentStack'
+icon: 'ship'
+---
-# Built-In Templates
+These are documentation links to the frameworks supported directly by AgentStack.
-The following templates are built into the AgentStack project. Template contributions are welcome!
+To start a project with one of these frameworks, use
+```bash
+agentstack init --framework
+```
-
-
- Research and report result from a query
-
-
- Research a topic and create content on it
-
-
- Inspect a project directory and improve it
-
-
-
-## templates/community.mdx
-
----
-title: 'Community Templates'
-description: 'Extending templating outside what is in the repo'
----
-
-The easiest way to create your own templates right now is to host them online.
-
-```bash
-agentstack init --template=
-```
-
-Much more community template support coming soon!
-
-## templates/content_creator.mdx
-
----
-title: 'Content Creator'
-description: 'Research a topic and create content on it'
----
-
-[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/content_creator.json)
-
-## frameworks/list.mdx
-
----
-title: Frameworks
-description: 'Supported frameworks in AgentStack'
-icon: 'ship'
----
-
-These are documentation links to the frameworks supported directly by AgentStack.
-
-To start a project with one of these frameworks, use
-```bash
-agentstack init --framework
-```
-
-## Framework Docs
+## Framework Docs
--framework
-## tools/package-structure.mdx
-
-
-## Tool Configuration
-Each tool gets a directory inside `agentstack/_tools/` where the tool's
-source code and configuration will be stored.
-
-The directory should contain the following files:
-
-`config.json`
--------------
-This contains the configuration for the tool for use by AgentStack, including
-metadata, dependencies, configuration & functions exposed by the tool.
-
-`__init__.py`
----------
-Python package which contains the framework-agnostic tool implementation. Tools
-are simple packages which exponse functions; when a tool is loaded into a user's
-project, it will be wrapped in the framework-specific tool format by AgentStack.
-
-
-`config.json` Format
---------------------
-
-### `name` (string) [required]
-The name of the tool in snake_case. This is used to identify the tool in the system.
-
-### `url` (string) [optional]
-The URL of the tool's repository. This is provided to the user to allow them to
-learn more about the tool.
-
-### `category` (string) [required]
-The category of the tool. This is used to group tools together in the CLI.
-
-### `cta` (string) [optional]
-String to print in the terminal when the tool is installed that provides a call to action.
-
-### `env` (list[dict(str, Any)]) [optional]
-Definitions for environment variables that will be appended to the local `.env` file.
-This is a list of key-value pairs ie. `[{"ENV_VAR": "value"}, ...]`.
-In cases where the user is expected to provide their own information, the value is
-set to `null` which adds it to the project's `.env` file as a comment.
-
-### `dependencies` (list[str]) [optional]
-List of dependencies that will be installed in the user's project. It is
-encouraged that versions are specified, which use the `package>=version` format.
-
-### `tools` (list[str]) [required]
-List of public functions that are accessible in the tool implementation.
-
-
-
-## tools/core.mdx
+## templates/content_creator.mdx
---
-title: 'Core Tools'
-description: 'AgentStack tools that are not third-party integrations'
+title: 'Content Creator'
+description: 'Research a topic and create content on it'
---
-## File System
-
-- [Directory Search](/tools/tool/dir_search)
-- [File Read](/tools/tool/file_read)
-- [FTP](/tools/tool/ftp)
-
-## Code Execution
-
-- [Code Interpreter](/tools/tool/code-interpreter)
-
-## Data Input
-- [Vision](/tools/tool/vision)
-
-
-
- Third party tools from the Agent Community
-
-
+[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/content_creator.json)
-## tools/community.mdx
+## templates/templates.mdx
---
-title: 'Community Tools'
-description: 'AgentStack tools from community contributors'
+title: 'Templates'
+description: 'Default AgentStack templates'
---
-## Web Retrieval
-- [AgentQL](/tools/tool/agentql)
-
-## Browsing
-
-[//]: # (- [Browserbase](/tools/tool/browserbase))
-- [Firecrawl](/tools/tool/firecrawl)
-
-## Search
-- [Perplexity](/tools/tool/perplexity)
-
-## Memory / State
+_Templates are a really powerful tool within AgentStack!_
-- [Mem0](/tools/tool/mem0)
+# Start a new project with a template
+Initializing a new project with AgentStack involves adding just one argument:
+```bash
+agentstack init --template=
+```
-## Database Tools
-- [Neon](/tools/tool/neon)
+Templates can also be passed as a URL. The URL should serve a valid json AgentStack template.
-## Code Execution
+## Start Easier
+If you're struggling to get started with a project in AgentStack, a great way to better understand what to do is to start with a template!
-- [Open Interpreter](/tools/tool/open-interpreter)
+## Churn Faster
+Many contractors that build agent systems have a tried and true prompting method that they want to replicate more quickly.
+By creating your own template, you can quickly start projects that adhere to your design.
-## Unified API
+## For Content Creators
+Have a tutorial you've created using AgentStack? Make your project available as a quickstart with templates.
-- [Composio](/tools/tool/composio)
+# Built-In Templates
-## Network Protocols
-- [Agent Connect](/tools/tool/agent-connect)
+The following templates are built into the AgentStack project. Template contributions are welcome!
-## Application Specific
-- [Stripe](/tools/tool/stripe)
-- [Payman](/tools/tool/payman)
-
+
- Default tools in AgentStack
+ Research and report result from a query
+
+
+ Research a topic and create content on it
+
+
+ Inspect a project directory and improve it
-## tools/tools.mdx
-
----
-title: 'Tools'
-description: 'Giving your agents tools should be easy'
----
-
-## Installation
-
-Once you find the right tool for your use-case, install it with simply
-```bash
-agentstack tools add
-```
-
-You can also specify a tool, and one or more agents to install it to:
-```bash
-agentstack tools add --agents=,
-```
-
-
- Add your own tool to the AgentStack repo [here](/contributing/adding-tools)!
-
-
-## snippets/snippet-intro.mdx
-
-One of the core principles of software development is DRY (Don't Repeat
-Yourself). This is a principle that apply to documentation as
-well. If you find yourself repeating the same content in multiple places, you
-should consider creating a custom snippet to keep your content in sync.
-
-
-## cli-reference/cli.mdx
+## templates/system_analyzer.mdx
---
-title: 'CLI Reference'
-description: 'Everything to do with the CLI'
+title: 'System Analyzer'
+description: 'Inspect a project directory and improve it'
---
-It all starts with calling
-```bash
-$ agentstack
-```
-
-### Shortcut Aliases
-Many top-level AgentStack commands can be invoked using a single-letter prefix to save keystrokes. These are indicated
-in the command's documentation here after a `|` character. Run `agentstack help` for the full list.
-
-### Global Flags
-These flags work with all commands:
-
-`--debug` - Print a full traceback when an error is encountered. This also enables printing additional debug information
-from within AgentStack useful for development and debugging.
-
-`--path=` - Set the working directory of the current AgentStack project. By default `agentstack` works inside of the
-current directory and looks for an `agentstack.json` file there. By passing a path to this flag you can work on a project
-from outside of it's directory.
-
-`--version` - Prints the current version and exits.
-
-
-## `$ agentstack init`
-This initializes a new AgentStack project.
-```bash
-agentstack init
-```
-
-`slug_name` is the name of your project, and will be created as a directory to initialize your project inside. When the
-default arguments are passed, a starter project template will be used, which adds a single agent, a single task and
-demonstrates the use of a tool.
-
-### Init Creates a Virtual Environment
-AgentStack creates a new directory, initializes a new virtual environment, installs dependencies, and populates the project
-structure. After `init` completes, `cd` into the directory, activate the virtual environment with `source .venv/bin/activate`.
-Virtual environments and package management are handled by the `uv` package manager.
-
-### Initializing with the Wizard
-You can pass the `--wizard` flag to `agentstack init` to use an interactive project configuration wizard.
-
-### Initializing from a Template
-You can also pass a `--template=` argument to `agentstack init` which will pre-populate your project with functionality
-from a built-in template, or one found on the internet. A `template_name` can be one of three identifiers:
-
-- A built-in AgentStack template (see the `templates` directory in the AgentStack repo for bundled templates).
-- A template file from the internet; pass the full https URL of the template.
-- A local template file; pass an absolute or relative path.
-
-
-## `$ agentstack run`
-This runs your AgentStack project.
-```bash
-agentstack run
-```
-
-Environment variables will be loaded from `~/.env` and from the `.env` file inside your project directory. Make sure you
-have enabled your project's `venv` before executing to include all dependencies required.
-
-### Overriding Inputs
-Your project defines Inputs which are used to customize the Agent and Task prompts for a specific task. In cases where
-using the `inputs.yaml` file to populate data is not flexible enough, `run` can accept value overrides for all defined
-inputs. Use `--input-=` to pass data which will only be used on this run.
-
-For example, if you have a key in your `inputs.yaml` file named `topic` and want to override it for this run, you would
-use the following command:
-
-```bash
-agentstack run --input-topic=Sports
-```
-
-### Running other project commands
-By default, `run` will call the `main()` function inside your project's `main.py` file. You can pass alternate function
-names to run with `--function=`.
-
-
-## Generate
-Code generation commands for automatically creating new agents or tasks.
-
-### `$ agentstack generate agent | agentstack g a`
-Generate a new agent
-- `agent_name` (required | str) - the name of the agent
-- `--role` (optional | str) - Prompt parameter: The role of the agent
-- `--goal` (optional | str) - Prompt parameter: The goal of the agent
-- `--backstory` (optional | str) - Prompt parameter: The backstory of the agent
-- `--llm` (optional | `/`) - Which model to use for this agent
-
-#### Default LLM
-All arguments to generate a new Agent are optional. A default LLM can be configured in `agentstack.json`under the
-`default_model` setting to populate a provider/model. If you are generating an agent in a project which does not have
-a default model set, you will be prompted to configure one.
-
-#### Example
-```bash Generate Agent
-agentstack generate agent script_writer
-```
-
-### `$ agentstack generate task | agentstack g t`
-Generate a new task
-- `task_name` (required | str) - the name of the task
-- `--description` (optional | str) - Prompt parameter: Explain the task in detail
-- `--expected_output` (optional | str) - What is the expected output from the agent (ex: data in json format)
-- `--agent` (optional | str) - The name of the agent of which to assign the task to (when using Crew in sequential mode)
+[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/system_analyzer.json)
-#### Example
-```bash Generate Task
-agentstack g t gen_script --description "Write a short film script about secret agents"
+```bash
+agentstack init --template=system_analyzer
```
-## Tools
-Tools are what make AgentStack powerful. Adding and removing Tools from Agents is easy with this command.
+# Purpose
-### `$ agentstack tools list | agentstack t l`
-Lists all tools available in AgentStack.
+This agent will accept a query as a string, use Perplexity to research it. Another agent will take the data gathered and perform an analysis focused on answering the query.
-### `$ agentstack tools add | agentstack t a`
-Shows an interactive interface for selecting which Tool to add and which Agents to add it to.
+# Inputs
-#### Add a Tool to all Agents
-When a tool_name is provided it will be made available to all Agents in the project.
-```bash
-$ agentstack tools add
-```
+`system_path` (str): the absolute path to
-#### Add a Tool to a single Agent
-When an agent_name is provided, the tool will be made available to only that agent.
-```bash
-$ agentstack tools add --agent=
-```
+## templates/researcher.mdx
+
+---
+title: 'Researcher'
+description: 'Research and report result from a query'
+---
+
+[View Template](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/templates/research.json)
-#### Add a Tool to multiple Agents
-When a comma-separated list of Agents is passed, the tool will be made available to those agents.
```bash
-$ agentstack tools add --agents=,,
+agentstack init --template=research
```
-### `$ agentstack tools remove `
-Removes a tool from all Agents in the project.
+# Purpose
+This agent will accept a query as a string, use Perplexity to research it. Another agent will take the data gathered and perform an analysis focused on answering the query.
-## Templates
-Projects can be exported into a template to facilitate sharing configurations. Re-initialize a project from a template
-with `agentstack init --template=`.
+# Inputs
-### `$ agentstack export `
-The current project will be written to a JSON template at the provided filename.
+`query` (str): the query for the agent to research and report on
-## `$ agentstack update`
-Check for updates and allow the user to install the latest release of AgentStack.
+## templates/community.mdx
-## `$ agentstack login`
-Authenticate with [agentstack.sh](https://agentstack.sh) for hosted integrations.
+---
+title: 'Community Templates'
+description: 'Extending templating outside what is in the repo'
+---
+
+The easiest way to create your own templates right now is to host them online.
+
+```bash
+agentstack init --template=
+```
+
+Much more community template support coming soon!
+
+## snippets/snippet-intro.mdx
+One of the core principles of software development is DRY (Don't Repeat
+Yourself). This is a principle that apply to documentation as
+well. If you find yourself repeating the same content in multiple places, you
+should consider creating a custom snippet to keep your content in sync.
## essentials/agentops.mdx
@@ -1248,6 +1094,38 @@ To get started, create an [AgentOps account](https://agentops.ai/?=agentstack).
For feature requests or bug reports, please reach out to the AgentOps team on the [AgentOps Repo](https://github.com/AgentOps-AI/agentops).
+## essentials/generating-tasks.mdx
+
+---
+title: 'Generating Tasks'
+description: 'CLI command to add a task to your project'
+---
+
+To generate a new task for your project, run:
+
+```bash
+agentstack generate task
+```
+
+This command will modify two files, your agent file (`crew.py`/`graph.py`) and `agents.yaml`.
+
+## your agent file
+
+This is the file that declares each of your agents and tasks. It's the core of your AgentStack project and how AgentStack configures your framework.
+- Crew projects have `crew.py`
+- LangGraph projects have `graph.py`
+
+## agents.yaml
+
+This is your prompt file. Any prompt engineering is abstracted to here for non-technical ease.
+
+Each task has two prompt params:
+- Description
+- Expected Output
+
+And one configuration param:
+- Agent - If operating in Sequential mode, this tells the Crew which agent should accomplish the task
+
## essentials/generating-agents.mdx
---
@@ -1284,35 +1162,160 @@ And one configuration param:
Ex: `openai/gpt-4o`
-## essentials/generating-tasks.mdx
+## tools/core.mdx
---
-title: 'Generating Tasks'
-description: 'CLI command to add a task to your project'
+title: 'Core Tools'
+description: 'AgentStack tools that are not third-party integrations'
---
-To generate a new task for your project, run:
+## File System
+
+- [Directory Search](/tools/tool/dir_search)
+- [File Read](/tools/tool/file_read)
+- [FTP](/tools/tool/ftp)
+
+## Code Execution
+
+- [Code Interpreter](/tools/tool/code-interpreter)
+
+## Input
+- [Vision](/tools/tool/vision)
+
+## Data
+- [SQL](/tools/tool/sql)
+
+
+
+ Third party tools from the Agent Community
+
+
+
+## tools/tools.mdx
+
+---
+title: 'Tools'
+description: 'Giving your agents tools should be easy'
+---
+## Installation
+
+Once you find the right tool for your use-case, install it with simply
```bash
-agentstack generate task
+agentstack tools add
```
-This command will modify two files, your agent file (`crew.py`/`graph.py`) and `agents.yaml`.
+You can also specify a tool, and one or more agents to install it to:
+```bash
+agentstack tools add --agents=,
+```
-## your agent file
+
+ Add your own tool to the AgentStack repo [here](/contributing/adding-tools)!
+
-This is the file that declares each of your agents and tasks. It's the core of your AgentStack project and how AgentStack configures your framework.
-- Crew projects have `crew.py`
-- LangGraph projects have `graph.py`
+## tools/package-structure.mdx
-## agents.yaml
-This is your prompt file. Any prompt engineering is abstracted to here for non-technical ease.
+## Tool Configuration
+Each tool gets a directory inside `agentstack/_tools/` where the tool's
+source code and configuration will be stored.
-Each task has two prompt params:
-- Description
-- Expected Output
+The directory should contain the following files:
-And one configuration param:
-- Agent - If operating in Sequential mode, this tells the Crew which agent should accomplish the task
+`config.json`
+-------------
+This contains the configuration for the tool for use by AgentStack, including
+metadata, dependencies, configuration & functions exposed by the tool.
+
+`__init__.py`
+---------
+Python package which contains the framework-agnostic tool implementation. Tools
+are simple packages which exponse functions; when a tool is loaded into a user's
+project, it will be wrapped in the framework-specific tool format by AgentStack.
+
+
+`config.json` Format
+--------------------
+
+### `name` (string) [required]
+The name of the tool in snake_case. This is used to identify the tool in the system.
+
+### `url` (string) [optional]
+The URL of the tool's repository. This is provided to the user to allow them to
+learn more about the tool.
+
+### `category` (string) [required]
+The category of the tool. This is used to group tools together in the CLI.
+
+### `cta` (string) [optional]
+String to print in the terminal when the tool is installed that provides a call to action.
+
+### `env` (list[dict(str, Any)]) [optional]
+Definitions for environment variables that will be appended to the local `.env` file.
+This is a list of key-value pairs ie. `[{"ENV_VAR": "value"}, ...]`.
+In cases where the user is expected to provide their own information, the value is
+set to `null` which adds it to the project's `.env` file as a comment.
+
+### `dependencies` (list[str]) [optional]
+List of dependencies that will be installed in the user's project. It is
+encouraged that versions are specified, which use the `package>=version` format.
+
+### `tools` (list[str]) [required]
+List of public functions that are accessible in the tool implementation.
+
+
+
+## tools/community.mdx
+
+---
+title: 'Community Tools'
+description: 'AgentStack tools from community contributors'
+---
+
+## Web Retrieval
+- [AgentQL](/tools/tool/agentql)
+
+## Browsing
+
+[//]: # (- [Browserbase](/tools/tool/browserbase))
+- [Firecrawl](/tools/tool/firecrawl)
+
+## Search
+- [Perplexity](/tools/tool/perplexity)
+
+## Memory / State
+
+- [Mem0](/tools/tool/mem0)
+
+## Database Tools
+- [Neon](/tools/tool/neon)
+
+## Code Execution
+
+- [Open Interpreter](/tools/tool/open-interpreter)
+
+## Unified API
+
+- [Composio](/tools/tool/composio)
+
+## Network Protocols
+- [Agent Connect](/tools/tool/agent-connect)
+
+## Application Specific
+- [Stripe](/tools/tool/stripe)
+- [Payman](/tools/tool/payman)
+
+
+ Default tools in AgentStack
+
+