Merge branch 'main' into firecrawl-tool

# Conflicts:
#	agentstack/_tools/vision/__init__.py
#	agentstack/_tools/vision/config.json

Author: bboynton97

.github/workflows/codecov.yml

@@ -31,7 +31,7 @@ jobs:
         pip install tox
 
     - name: Run tests with tox
-      run: tox
+      run: tox -m quick  # quick runs all 3.12 tests and then combines coverage
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v5

.github/workflows/python-testing.yml

@@ -25,15 +25,17 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [3.10,3.11,3.12]
+        python-version: ["3.10","3.11","3.12"]  # versions need to be strings
 
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.11' # Use a default Python version for running tox
+          python-version: ${{ matrix.python-version }}
       - name: Install tox
         run: pip install tox
+      - name: Install tox-gh-actions
+        run: pip install tox-gh-actions  # allows tox to get the current python version
       - name: Run tests with tox
-        run: tox
+        run: tox  # we can't pass arguments to tox when using tox-gh-actions, so all frameworks happen in one run

.gitignore

@@ -175,9 +175,13 @@ ex/
 **/ex/
 cookiecutter.json
 
+tests/tmp
+
 examples/tests/
 examples/tests/**/*
 
 uv.lock
 .DS_Store
 
+.python-version
+

MANIFEST.in

@@ -1,3 +1,4 @@
 recursive-include agentstack/templates *
+recursive-include agentstack/frameworks/templates *
 recursive-include agentstack/_tools *
 include agentstack.json .env .env.example

README.md

@@ -27,9 +27,16 @@ agentstack init <project_name>
 AgentStack scaffolds your _agent stack_ - the tech stack that collectively is your agent
 
 <p align='center'>
-<img src='https://github.com/AgentOps-AI/AgentStack/blob/7b40e53bf7300f69e3291c62d5b45e46ff818245/docs/images/the_agent_stack.png?raw=true' width='600' alt='agentstack init'>
+<img src='https://github.com/AgentOps-AI/AgentStack/blob/main/docs/images/the_agent_stack.png?raw=true' width='600' alt='agentstack init'>
 </p>
 
+### Currently Supported Providers
+- **LLMs**: Most all notable LLMs and providers are supported via LiteLLM or LangChain
+- **Framework**: Currently supported frameworks include CrewAI, LangGraph, OpenAI Swarms and LlamaStack
+  - Roadmap: Pydantic AI, Eliza, AG2 and Autogen
+- **Tools**: Maintaining the largest repository of framework-agnostic tools! All tools listed [here](https://docs.agentstack.sh/tools/community)
+- **Observability**: AgentOps baked in by default with first-tier support
+
 ### Get Started Immediately
 
 You **don't** need to install or configure tools like LangChain or LlamaIndex.<br>
@@ -44,7 +51,7 @@ Create a project, and you're good to go.
 To create a new agent project, run:
 
 ```sh
-pip install agentstack
+uv pip install agentstack
 agentstack init <project_name>
 ```
 
@@ -56,10 +63,17 @@ Once the initialization is done, you can open your project folder:
 
 ```sh
 cd <your_agent_project>
+uv pip install
+```
+
+then run the default agent!
+
+```sh
+agentstack run
 ```
 
 ### Templates
-Additionally, pre-built templates are available as a shortcut to building your project. [View the available templates]().
+Additionally, pre-built templates are available as a shortcut to building your project. [View the available templates](https://docs.agentstack.sh/templates).
 
 ## Building Agent Functionality
 
@@ -101,33 +115,36 @@ Runs the agent project in development mode.<br>
 
 - **No Lock-In:** You can customize your setup at any time. AgentStack is designed to make it easy to get the components you need running right off the bat; it's up to you what to do next.
 
+- **Provider Agnosticism:** AgentStack is designed to be provider agnostic in all ways. This means especially that the framework layer of your agent stack should be interoperable with every other layer. Frameworks must still be supported by AgentStack. See supported frameworks above.
+
 AgentStack is not designed to be a low-code solution to building agents. Instead it is a great head-start for starting an agent project from scratch.
 
 ## Roadmap
 
-### Framework Agnosticism
-
-Development of AgentStack is being done primarily on [CrewAI](https://crewai.com). We will soon be working to make AgentStack fully framework-agnostic, meaning that any supported multi-agent framework can be used for your project. 
-
 ### Tools
-- Core Tools built by AgentStack
+- More [core tools](https://docs.agentstack.sh/tools/core) built by AgentStack
 - Preferred partners in the package directly
 - Community partner tools added through external repositories
 
+### New Stack Layers
+- Prompting layer (DSPy)
+- Eval Layer
+- UI layer
+
 ### Other Features
 - Generated testing
 - Integrated benchmarking
 - Easy integration of tools for browsing, RAG, and more.
 - A fast interactive test runner with built-in support for coverage reporting.
-- A live development server that warns about common mistakes.
-- A build script to bundle your project for production.
+- A live development server that warns about common mistakes (in progress).
+- A build script to bundle your project for production (in progress).
 
 ## License
 
 AgentStack is open source software [licensed as MIT](LICENSE).
 
 ## How to Contribute
 
-AgentStack is a new project built by passionate AI agent developers! We'd love help making this tool better. Easy first issues are available, create new issues with feature ideas, or chat with us on our [Discord](https://discord.gg/JdWkh9tgTQ).
+AgentStack is a new project built by passionate AI agent developers! We'd love help making this tool better. Easy first issues are available, create new issues with feature ideas, or chat with us on our [Discord](https://discord.gg/JdWkh9tgTQ). Make sure you read our contributor documentation to familiarize yourself with the project at [How to Contribute](https://docs.agentstack.sh/contributing/how-to-contribute).
 
 If you are an Agent Tool developer, feel free to create an issue or even a PR to add your tool to AgentStack. 

agentstack/__init__.py

@@ -9,17 +9,46 @@
 from pathlib import Path
 from agentstack import conf
 from agentstack.utils import get_framework
+from agentstack.agents import get_agent, get_all_agents, get_all_agent_names
+from agentstack.tasks import get_task, get_all_tasks, get_all_task_names
 from agentstack.inputs import get_inputs
 from agentstack import frameworks
 
 ___all___ = [
-    "conf",
-    "tools",
-    "get_tags",
-    "get_framework",
-    "get_inputs",
+    "conf", 
+    "agent", 
+    "task", 
+    "tools", 
+    "get_tags", 
+    "get_framework", 
+    "get_agent", 
+    "get_all_agents",
+    "get_all_agent_names",
+    "get_task", 
+    "get_all_tasks",
+    "get_all_task_names",
+    "get_inputs", 
 ]
 
+def agent(func):
+    """
+    The `agent` decorator is used to mark a method that implements an Agent. 
+    """
+    def wrap(*args, **kwargs):
+        """Does not alter the function's behavior; this is just a marker."""
+        return func(*args, **kwargs)
+    return wrap
+
+
+def task(func):
+    """
+    The `task` decorator is used to mark a method that implements a Task.
+    """
+    def wrap(*args, **kwargs):
+        """Does not alter the function's behavior; this is just a marker."""
+        return func(*args, **kwargs)
+    return wrap
+
 
 def get_tags() -> list[str]:
     """

agentstack/_tools/__init__.py

@@ -7,12 +7,23 @@
 import pydantic
 from agentstack.exceptions import ValidationError
 from agentstack.utils import get_package_path, open_json_file, term_color, snake_to_camel
+from agentstack import conf, log
 
 
 TOOLS_DIR: Path = get_package_path() / '_tools'  # NOTE: if you change this dir, also update MANIFEST.in
 TOOLS_CONFIG_FILENAME: str = 'config.json'
 
 
+def _get_custom_tool_path(name: str) -> Path:
+    """Get the path to a custom tool."""
+    return conf.PATH / 'src/tools' / name / TOOLS_CONFIG_FILENAME
+
+
+def _get_builtin_tool_path(name: str) -> Path:
+    """Get the path to a builtin tool."""
+    return TOOLS_DIR / name / TOOLS_CONFIG_FILENAME
+
+
 class ToolConfig(pydantic.BaseModel):
     """
     This represents the configuration data for a tool.
@@ -32,10 +43,15 @@ class ToolConfig(pydantic.BaseModel):
 
     @classmethod
     def from_tool_name(cls, name: str) -> 'ToolConfig':
-        path = TOOLS_DIR / name / TOOLS_CONFIG_FILENAME
-        if not os.path.exists(path):  # TODO raise exceptions and handle message/exit in cli
-            print(term_color(f'No known agentstack tool: {name}', 'red'))
-            sys.exit(1)
+        # First check in the user's project directory for custom tools
+        custom_path = _get_custom_tool_path(name)
+        if custom_path.exists():
+            return cls.from_json(custom_path)
+
+        # Then check in the package's tools directory
+        path = _get_builtin_tool_path(name)
+        if not path.exists():
+            raise ValidationError(f'No known agentstack tool: {name}')
         return cls.from_json(path)
 
     @classmethod
@@ -44,11 +60,18 @@ def from_json(cls, path: Path) -> 'ToolConfig':
         try:
             return cls(**data)
         except pydantic.ValidationError as e:
-            # TODO raise exceptions and handle message/exit in cli
-            print(term_color(f"Error validating tool config JSON: \n{path}", 'red'))
+            error_str = "Error validating tool config:\n"
             for error in e.errors():
-                print(f"{' '.join([str(loc) for loc in error['loc']])}: {error['msg']}")
-            sys.exit(1)
+                error_str += f"{' '.join([str(loc) for loc in error['loc']])}: {error['msg']}\n"
+            raise ValidationError(f"Error loading tool from {path}.\n{error_str}")
+
+    def write_to_file(self, filename: Path):
+        """Write the tool config to a json file."""
+        if not filename.suffix == '.json':
+            raise ValidationError(f"Filename must end with .json: {filename}")
+
+        with open(filename, 'w') as f:
+            f.write(self.model_dump_json())
 
     @property
     def type(self) -> type:
@@ -76,6 +99,12 @@ def not_implemented(*args, **kwargs):
     @property
     def module_name(self) -> str:
         """Module name for the tool module."""
+        # Check if this is a custom tool in the user's project
+        custom_path = _get_custom_tool_path(self.name)
+        if custom_path.exists():
+            return f"src.tools.{self.name}"
+
+        # Otherwise, it's a package tool
         return f"agentstack._tools.{self.name}"
 
     @property
@@ -107,19 +136,36 @@ def get_all_tool_paths() -> list[Path]:
     Get all the paths to the tool configuration files.
     ie. agentstack/_tools/<tool_name>/
     Tools are identified by having a `config.json` file inside the _tools/<tool_name> directory.
+    Also checks the user's project directory for custom tools.
     """
     paths = []
+
+    # Get package tools
     for tool_dir in TOOLS_DIR.iterdir():
         if tool_dir.is_dir():
             config_path = tool_dir / TOOLS_CONFIG_FILENAME
             if config_path.exists():
                 paths.append(tool_dir)
+
+    # Get custom tools from user's project if in a project directory
+    if conf.PATH:
+        custom_tools_dir = conf.PATH / 'src/tools'
+        if custom_tools_dir.exists():
+            for tool_dir in custom_tools_dir.iterdir():
+                if tool_dir.is_dir():
+                    config_path = tool_dir / TOOLS_CONFIG_FILENAME
+                    if config_path.exists():
+                        paths.append(tool_dir)
+
     return paths
 
 
 def get_all_tool_names() -> list[str]:
-    return [path.stem for path in get_all_tool_paths()]
+    """Get names of all available tools, including custom tools."""
+    return [path.name for path in get_all_tool_paths()]
 
 
 def get_all_tools() -> list[ToolConfig]:
-    return [ToolConfig.from_tool_name(path) for path in get_all_tool_names()]
+    """Get all tool configs, including custom tools."""
+    tool_names = get_all_tool_names()
+    return [ToolConfig.from_tool_name(name) for name in tool_names]

agentstack/_tools/composio/config.json

@@ -12,7 +12,7 @@
     "find_actions_by_tags"
   ],
   "dependencies": [
-    "composio>=1.0.0"
+    "composio-core>=0.6.0"
   ],
   "cta": "!!! Composio provides 150+ tools. Additional setup is required in agentstack/tools/composio/__init__.py"
 }

agentstack/_tools/file_read/config.json

@@ -3,6 +3,6 @@
   "category": "computer-control",
   "tools": ["read_file"],
   "description": "Read contents of files",
-  "url": "https://github.com/AgentOps-AI/AgentStack/tree/main/agentstack/tools/file_read",
+  "url": "https://docs.agentstack.sh/tools/tool/file_read",
   "dependencies": []
 }

agentstack/_tools/neon/config.json

@@ -7,7 +7,7 @@
     },
     "dependencies": [
         "neon-api>=0.1.5",
-        "psycopg2-binary"
+        "psycopg2-binary==2.9.10"
     ],
     "tools": ["create_database", "execute_sql_ddl", "run_sql_query"],
     "cta": "Create an API key at https://www.neon.tech"