diff --git a/agentstack/cli/init.py b/agentstack/cli/init.py
index b215ea23..1bce9b14 100644
--- a/agentstack/cli/init.py
+++ b/agentstack/cli/init.py
@@ -135,12 +135,21 @@ def init_project(
packaging.create_venv()
log.info("Installing dependencies...")
packaging.install_project()
- repo.init() # initialize git repo
+
+ if repo.find_parent_repo(conf.PATH):
+ # if a repo already exists, we don't want to initialize a new one
+ log.info("Found existing git repository; disabling tracking.")
+ with conf.ConfigFile() as config:
+ config.use_git = False
+ else:
+ # create a new git repo in the project dir
+ repo.init()
# now we can interact with the project and add Agents, Tasks, and Tools
# we allow dependencies to be installed along with these, so the project must
# be fully initialized first.
with repo.Transaction() as commit:
+ commit.add_message("Initialized new project")
for task in template_data.tasks:
commit.add_message(f"Added task {task.name}")
generation.add_task(**task.model_dump())
diff --git a/agentstack/repo.py b/agentstack/repo.py
index ec1f32cb..f1e10465 100644
--- a/agentstack/repo.py
+++ b/agentstack/repo.py
@@ -1,3 +1,5 @@
+from typing import Optional
+from pathlib import Path
import shutil
import git
from agentstack import conf, log
@@ -108,6 +110,18 @@ def _require_git():
raise EnvironmentError(message)
+def find_parent_repo(path: Path) -> Optional[Path]:
+ """
+ Traverse the directory tree upwards from `path` until a .git directory is found.
+ """
+ current = path.absolute()
+ while current != current.parent:
+ if (current / '.git').exists():
+ return current
+ current = current.parent
+ return None
+
+
def _get_repo() -> git.Repo:
"""
Get the git repository for the current project.
@@ -118,6 +132,7 @@ def _get_repo() -> git.Repo:
"""
_require_git()
try:
+ # look for a repository in the project's directory
return git.Repo(conf.PATH.absolute())
except git.exc.InvalidGitRepositoryError:
message = "No git repository found in the current project."
@@ -125,15 +140,23 @@ def _get_repo() -> git.Repo:
raise EnvironmentError(message)
-def init() -> None:
+def init(force_creation: bool = False) -> None:
"""
Create a git repository for the current project and commit a .gitignore file
- to initialize the repo. Assumes that a repo does not already exist.
+ to initialize the repo.
+
+ `force_creation` will create a new repo even if one already exists in a parent
+ directory. default: False
"""
try:
_require_git()
except EnvironmentError as e:
return # git is not installed or tracking is disabled
+
+ if find_parent_repo(conf.PATH.absolute()):
+ log.warning("A git repository already exists in a parent directory.")
+ if not force_creation:
+ return
# creates a new repo at conf.PATH / '.git
repo = git.Repo.init(path=conf.PATH.absolute(), initial_branch=MAIN_BRANCH_NAME)
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
+
+
diff --git a/tests/test_repo.py b/tests/test_repo.py
index 63bc88fd..2499654d 100644
--- a/tests/test_repo.py
+++ b/tests/test_repo.py
@@ -28,7 +28,7 @@ def tearDown(self):
shutil.rmtree(self.test_dir)
def test_init(self):
- repo.init()
+ repo.init(force_creation=True)
# Check if a git repository was created
self.assertTrue((self.test_dir / '.git').is_dir())
@@ -40,19 +40,25 @@ def test_init(self):
self.assertEqual(len(commits), 1)
self.assertEqual(commits[0].message, f"{repo.INITIAL_COMMIT_MESSAGE}{repo.AUTOMATION_NOTE}")
+ def test_init_parent_repo_exists(self):
+ os.makedirs(self.test_dir.parent / '.git')
+
+ repo.init(force_creation=False)
+ self.assertFalse((self.test_dir / '.git').is_dir())
+
def test_get_repo_nonexistent(self):
with self.assertRaises(EnvironmentError):
repo._get_repo()
def test_get_repo_existent(self):
- repo.init()
+ repo.init(force_creation=True)
result = repo._get_repo()
self.assertIsInstance(result, git.Repo)
self.assertEqual(result.working_tree_dir, str(self.test_dir))
def test_get_uncommitted_files_new_file(self):
- repo.init()
+ repo.init(force_creation=True)
new_file = self.test_dir / "new_file.txt"
new_file.touch()
@@ -62,7 +68,7 @@ def test_get_uncommitted_files_new_file(self):
self.assertIn("new_file.txt", uncommitted)
def test_get_uncommitted_files_modified_file(self):
- repo.init()
+ repo.init(force_creation=True)
# Create and commit an initial file
initial_file = self.test_dir / "initial_file.txt"
@@ -154,7 +160,7 @@ def test_require_git_installed(self, mock_which, mock_should_track):
repo._require_git()
def test_transaction_context_manager(self):
- repo.init()
+ repo.init(force_creation=True)
mock_commit = MagicMock()
with patch('agentstack.repo.commit', mock_commit):
@@ -165,7 +171,7 @@ def test_transaction_context_manager(self):
mock_commit.assert_called_once_with(f"Test message", ["test_file.txt"], automated=True)
def test_transaction_multiple_messages(self):
- repo.init()
+ repo.init(force_creation=True)
mock_commit = MagicMock()
with patch('agentstack.repo.commit', mock_commit):
@@ -180,7 +186,7 @@ def test_transaction_multiple_messages(self):
)
def test_transaction_no_changes(self):
- repo.init()
+ repo.init(force_creation=True)
mock_commit = MagicMock()
with patch('agentstack.repo.commit', mock_commit):
@@ -192,7 +198,7 @@ def test_transaction_no_changes(self):
mock_commit.assert_not_called()
def test_transaction_with_exception(self):
- repo.init()
+ repo.init(force_creation=True)
mock_commit = MagicMock()
with patch('agentstack.repo.commit', mock_commit):
@@ -212,7 +218,7 @@ def test_transaction_with_exception(self):
def test_init_when_git_disabled(self):
repo.dont_track_changes()
- result = repo.init()
+ result = repo.init(force_creation=True)
self.assertIsNone(result)
repo._USE_GIT = None # Reset for other tests
@@ -235,7 +241,7 @@ def test_get_uncommitted_files_when_git_disabled(self):
repo._USE_GIT = None # Reset for other tests
def test_commit_user_changes(self):
- repo.init()
+ repo.init(force_creation=True)
# Create a new file
test_file = self.test_dir / "user_file.txt"