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. Make sure you have your SSH key setup!

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

3. You are now ready to install the Agent Catalog package! Using your project's Python environment, execute the following command to install a local package with pip:

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

   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. Make sure you have your SSH key setup!

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

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 agent catalog 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.
  publish  Upload the local catalog to a Couchbase instance.
  status   Show the status of the local catalog.
  version  Show the current version of agentc.

  See: https://docs.couchbase.com 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.

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