agent-catalog (Couchbase Agent Catalog)

The mono-repo for the Couchbase Agent Catalog project.

Table of Contents

• Getting Started
  • Installing from Package
  • Installing from Source (with Pip)
  • Installing from Source (with Poetry)
  • Verifying Your Installation
• Building From Source
• Docs and Templates
• For Contributors / Developers
  • On Packages (inside libs)
  • Working with Poetry
  • Setting up Pre-Commit
  • Enabling Debug Mode

Getting Started

Installing from Package

(in the works!)

Installing from Source (with Pip)

1. Make sure you have Python 3.12 and Poetry installed!

2. Clone this repository.

   git clone https://github.com/couchbaselabs/agent-catalog

3. You are now ready to install the Agent Catalog package!
   We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project.

   Click here for Anaconda installation steps.

   Once anaconda or any of its distribution is installed, execute the following commands to activate the environment.

   conda create -n agentcenv python=3.12
   
   conda activate agentcenv

   Alternatively, you can use any Python virtual environment manager.

   Once environment is set up, execute the following command to install a local package with pip:

   cd agent-catalog
   
   # Install the agentc package.
   pip install libs/agentc

   If you are interested in developing with langchain, also install agentc_langchain by running the following:

   pip install libs/agentc_langchain

   If you are interested in building a .whl file (for later use in .whl-based installs), use :command:poetry directly:

   cd libs/agentc
   poetry build

Installing from Source (with Poetry)

1. Make sure you have Python 3.12 and Poetry installed!

2. Clone this repository.

   git clone https://github.com/couchbaselabs/agent-catalog

3. Within your own pyproject.toml file, add the following dependency to your project: The path should point to the location of the agentc package (and is relative to the pyproject.toml file itself).

   [tool.poetry.dependencies]
   agentc = { path = "agent-catalog/libs/agentc", develop = true }

4. Run the command poetry update to install the Agent Catalog package.

   cd agent-catalog
   poetry update

Verifying Your Installation

If you've followed the steps above, you should now have the agentc command line tool. Run agentc --help to verify your installation (note that your first run will take a couple of seconds as some libraries like numpy need to be built, subsequent runs will be faster).

Usage: agentc [OPTIONS] COMMAND [ARGS]...

  The Couchbase Agent Catalog command line tool.

Options:
  -c, --catalog DIRECTORY         Directory of the local catalog files.  [default: .agent-catalog]
  -a, --activity DIRECTORY        Directory of the local activity files (runtime data).  [default: .agent-activity]
  -v, --verbose                   Flag to enable verbose output.  [default: 0; 0<=x<=2]
  -i, --interactive / -ni, --no-interactive
                                  Flag to enable interactive mode.  [default: i]
  --help                          Show this message and exit.

Commands:
  add      Interactively create a new tool or prompt and save it to the filesystem (output).
  clean    Delete all or specific (catalog and/or activity) agent related files / collections.
  env      Return all agentc related environment and configuration parameters as a JSON object.
  execute  Search and execute a specific tool.
  find     Find items from the catalog based on a natural language QUERY string or by name.
  index    Walk the source directory trees (SOURCE_DIRS) to index source files into the local catalog.
  ls       List all indexed tools and/or prompts in the catalog.
  publish  Upload the local catalog and/or logs to a Couchbase instance.
  status   Show the status of the local catalog.
  version  Show the current version of agentc.

  See: https://docs.couchbase.com or https://couchbaselabs.github.io/agent-catalog/index.html# for more information.

If you see the output above, you are all set! Head on over to our docs or our templates to start developing your agent with Agent Catalog.

Building From Source

For examples on what an agentic workflow with agentc looks like, see the agent-catalog-example repository.

Adding files to ignore while indexing

By default, the index command will ignore files/patterns present in .gitignore file. In addition to .gitignore, there might be situation where additional files have to be ignored by agentc and not git. To add such files/pattern .agentcignore file can be used similar to .gitignore.

For more guide on how to use .agentcignore file check the documentation

Docs and Templates

Refer to docs/ to explore templates and other references while writing your agent workflow with Couchbase Agent Catalog. We also provide some starter recipes if you are building an agent from scratch.

For Contributors / Developers

On Packages (inside libs)

Every project package is wrapped under libs. The following are sub-folders that you can explore:

1. agentc, which contains the front-facing package for the Couchbase Agent Catalog project.
2. agentc-cli, which contains the command line interface for the Couchbase Agent Catalog project.
3. agentc-core, which contains the core SDK package for the Couchbase Agent Catalog project.
4. agentc-langchain, which contains additional tooling around building LangChain-specific agents.

Working with Poetry

Below, we list out some notes that developers might find useful w.r.t. Poetry:

1. Before committing, always use poetry update; poetry lock! This will check if the dependencies laid out in the pyproject.toml file are satisfiable and will repopulate the lock file appropriately.
2. poetry install vs. poetry update: in the presence of a poetry.lock file (which we do have), the former will only consider installing packages specified in the lock file. The latter (poetry update) will read from the pyproject.toml file and try to resolve dependencies from there.
3. Because these are a collection of libraries, we do not commit individual lock files for each sub-package. Do not commit poetry.lock files.

Setting up Pre-Commit

To set up pre-commit and reap all the benefits of code formatting, linting, etc... execute the following command:

pip install pre-commit
pre-commit install

Enabling Debug Mode

To enable debug mode, execute the following command:

export AGENT_CATALOG_DEBUG=1