`agentc` Command Documentation¶

The agentc command line tool acts as an interface for your Agent Catalog instance.

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

  The Couchbase Agent Catalog command line tool.

Options:
  -v, --verbose  Flag to enable verbose output.  [default: 0; 0<=x<=2]
  -i, --interactive / -ni, --no-interactive
                 Flag to enable interactive mode.  [default: i]
  -h, --help     Show this message and exit.

Commands:
  add      Interactively create a new tool or prompt and save it to the...
  clean    Delete all or specific (catalog and/or activity) Agent Catalog...
  env      Return all Agent Catalog related environment and configuration...
  execute  Search for and subsequently execute a specific tool.
  find     Find items from the catalog based on a natural language string...
  index    Walk the source directory trees (sources) to index source files...
  init     Initialize the necessary files/collections for your working Agent...
  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 (aggregate) status of your Agent Catalog environment.
  version  Show the current version of Agent Catalog.

See https://couchbaselabs.github.io/agent-catalog/index.html for more
information.

All sub-commands have a verbosity option (-v, --verbose, by default verbosity is 0) and an interactive option (-i, --interactive / -ni, --no-interactive, by default interactivity is enabled).

`add` Command¶

The primary purpose of the add command is to import templates for declarative Agent Catalog tools (and prompts).

$ agentc add --help
Usage: agentc add [OPTIONS]

  Interactively create a new tool or prompt and save it to the filesystem
  (output). You MUST edit the generated file as per your requirements!

Options:
  -o, --output DIRECTORY  Location to save the generated tool / prompt to.
                          Defaults to your current working directory.
  --kind [python_function|sqlpp_query|semantic_search|http_request|prompt]
  -h, --help              Show this message and exit.

See here for more information on the types of catalog entries Agent Catalog currently recognizes.

Note

The add command does not index the generated tool / prompt for you. You are responsible for populating the remaining fields from the generated output and running the subsequent agentc index command.

Tip

For tools authored in Python, we recommend adding the agentc.catalog.tool decorator to your function and specifying the containing directory on agentc index instead of using the add command. For example, if you have an existing tool named positive_sentiment_analysis_tool that is properly documented (i.e., has a docstring and descriptive names in the function signature), simply add @agentc.catalog.tool to the top of your function.

import agentc

@agentc.catalog.tool
def positive_sentiment_analysis_tool(text_to_analyze: str) -> float:
    """ Using the given text, return a number between 0 and 1.
        A value of 0 means the text is not positive.
        A value of 1 means the text is positive.
        A vale of 0.5 means the text is slightly positive. """
    ...

`clean` Command¶

The purpose of the clean command is to "clean" / prune data from your local and / or remote catalog.

$ agentc clean --help
Usage: agentc clean [OPTIONS]
                    [[catalog|activity]]...

  Delete all or specific (catalog and/or activity) Agent Catalog related files /
  collections.

Options:
  --db / --no-db            Flag to perform / not-perform a DB clean.  [default:
                            db]
  --local / --no-local      Flag to perform / not-perform a local FS clean.
                            [default: local]
  --tools / --no-tools      Flag to clean / avoid-cleaning the tool-catalog.
                            [default: tools]
  --prompts / --no-prompts  Flag to clean / avoid-cleaning the prompt-catalog.
                            [default: prompts]
  --bucket TEXT             Name of the Couchbase bucket to remove Agent Catalog
                            from.
  -cid, --catalog-id TEXT   Catalog ID used to remove a specific catalog version
                            from the DB catalog.
  -y, --yes                 Flag to delete local-FS and DB catalog data without
                            confirmation.
  -d, --date TEXT           Datetime of the oldest log entry to keep (older log
                            entries will be deleted).
  -h, --help                Show this message and exit.

For remote catalogs possessing multiple catalog versions, you can specify a set of catalog IDs (i.e., Git SHAs) via the --catalog-id flag to delete their associated entries from the remote catalog. For example, running the command below will delete all tool + prompt + metadata entries associated with catalog versions GS53S and 14dFDD:

$ agentc clean -cid GS53S -cid 14dFDD

`env` Command¶

The env command displays the current configuration of Agent Catalog as a JSON object (see here for all configuration fields).

$ agentc env --help
Usage: agentc env [OPTIONS]

  Return all Agent Catalog related environment and configuration parameters as a
  JSON object.

Options:
  -h, --help  Show this message and exit.

`execute` Command¶

The execute command is a helper command that allows users to directly invoke tools indexed by Agent Catalog.

$ agentc execute --help
Usage: agentc execute [OPTIONS]

  Search for and subsequently execute a specific tool.

Options:
  --query TEXT             User query describing the task for which tools /
                           prompts are needed. This field or --name must be
                           specified.
  --name TEXT              Name of catalog item to retrieve from the catalog
                           directly. This field or --query must be specified.
  --bucket TEXT            Name of the Couchbase bucket to search.
  --dirty / --no-dirty     Flag to process and search amongst dirty source
                           files.  [default: dirty]
  --refiner [ClosestCluster|None]
                           Class to post-process (rerank, prune, etc...) find
                           results.
  -an, --annotations TEXT  Tool-specific annotations to filter by, specified
                           using KEY="VALUE" (AND|OR KEY="VALUE")*.
  -cid, --catalog-id TEXT  Catalog ID that uniquely specifies a catalog version
                           / snapshot (git commit id).  [default: __LATEST__]
  --db / --no-db           Flag to include / exclude items from the DB-catalog
                           while searching.
  --local / --no-local     Flag to include / exclude items from the local-FS-
                           catalog while searching.  [default: local]
  -h, --help               Show this message and exit.

The arguments for agentc execute are identical to that of agentc find (with the exception of the {tools|prompts} argument). execute is useful for verifying declarative tools before running them in your application (e.g., validating the results of your SQL++ query, checking the results of your semantic search, etc...).

`find` Command¶

The primary purpose of the find command is to validate the query or name arguments used by a call to agentc.Catalog:find.

$ agentc find --help
Usage: agentc find [OPTIONS] {tools|prompts}

  Find items from the catalog based on a natural language string (query) or by
  name.

Options:
  --query TEXT             User query describing the task for which tools /
                           prompts are needed. This field or --name must be
                           specified.
  --name TEXT              Name of catalog item to retrieve from the catalog
                           directly. This field or --query must be specified.
  --bucket TEXT            Name of the Couchbase bucket to search.
  --limit INTEGER          Maximum number of results to show.  [default: 1]
  --dirty / --no-dirty     Flag to process and search amongst dirty source
                           files.  [default: dirty]
  --refiner [ClosestCluster|None]
                           Class to post-process (rerank, prune, etc...) find
                           results.
  -an, --annotations TEXT  Tool-specific annotations to filter by, specified
                           using KEY="VALUE" (AND|OR KEY="VALUE")*.
  -cid, --catalog-id TEXT  Catalog ID that uniquely specifies a catalog version
                           / snapshot (git commit id).  [default: __LATEST__]
  --db / --no-db           Flag to include / exclude items from the DB-catalog
                           while searching.
  --local / --no-local     Flag to include / exclude items from the local-FS-
                           catalog while searching.  [default: local]
  -h, --help               Show this message and exit.

Search By Name¶

To find a tool or prompt directly by name, use the --name option. For example, to search for the latest version of the tool "find_user_by_id", you would write / author the following:

Command Line

$ agentc find tool --name find_user_by_id

Python Program

import agentc

catalog = agentc.Catalog()
my_tool = catalog.find("tool", name="find_user_by_id")

Search By Query¶

On agentc index, descriptions of tools and prompts are forwarded through an embedding model to enable semantic search of tools and prompts at find time. This is useful for authoring prompts in a tool-agnostic manner (see here for more information). To find 3 tools semantically related to "finding users", you would write / author the following:

Command Line

$ agentc find tool --query "finding users" --limit 3

Python Program

import agentc

catalog = agentc.Catalog()
my_tools = catalog.find("tool", query="finding users", limit=3)

Filter By Annotations¶

Annotations can be added to tools and prompts, which can serve as optional filters for --query at find time. For example, to search for the most related prompt to "frontdesk agent" tailored towards healthcare (domain="healthcare"), you would write / author the following:

Command Line

$ # Use single quotes to interpret the annotations string as a literal here!
$ agentc find prompt --query "frontdesk agent" --annotations 'domain="healthcare"'

Python Program

import agentc

catalog = agentc.Catalog()
prompt = catalog.find("prompt", query="frontdesk agent", annotations='domain="healthcare"')

Tip

Annotations on the command line must (generally) follow the regex KEY="VALUE" (AND|OR KEY="VALUE")*. This string must be specified in between single quotes to properly interpret the double quote.

Local Only Search¶

By default, Agent Catalog will search the local catalog and attempt (in a best-effort fashion) to search your Couchbase-backed catalog. To search for local-only entries for a single find command, use the --no-db flag. There is no equivalent flag using a agentc.Catalog:find call, but you can force local-only searches for a agentc.Catalog instance by explicitly setting the conn_string attribute to None. For example, to find the tool named "get_most_popular_categories" from the local catalog, write / author the following:

Command Line

$ agentc find tool --name get_most_popular_categories --no-db

Python Program

import agentc

catalog = agentc.Catalog(conn_string=None)
tool = catalog.find("tool", name="get_most_popular_categories")

`index` Command¶

The purpose of the index command is to build a local index of all tools and prompts.

$ agentc index --help
Usage: agentc index [OPTIONS] [SOURCES]...

  Walk the source directory trees (sources) to index source files into the local
  catalog. Source files that will be scanned include *.py, *.sqlpp, *.yaml, etc.

Options:
  --prompts / --no-prompts  Flag to look for / ignore prompts when indexing
                            source files into the local catalog.  [default:
                            prompts]
  --tools / --no-tools      Flag to look for / ignore tools when indexing source
                            files into the local catalog.  [default: tools]
  --dry-run                 Flag to prevent catalog changes.
  -h, --help                Show this message and exit.

By default, the index command will look for both tools and prompts in the given SOURCES. To avoid searching for tools or prompts specifically, use the --no-tools and --no-prompts flags respectively. In the example below, Agent Catalog will scan the directories my_tools_1, my_tools_2, and my_tools_3 for only tools.

$ agentc index --no-prompts my_tools_1 my_tools_2 my_tools_3

`init` Command¶

The purpose of the init command is to initialize your Agent Catalog environment (both locally and on Couchbase).

$ agentc init --help
Usage: agentc init [OPTIONS]
                   [[catalog|activity]]...

  Initialize the necessary files/collections for your working Agent Catalog
  environment.

Options:
  --db / --no-db        Flag to enable / disable DB initialization.  [default:
                        db]
  --local / --no-local  Flag to enable / disable local FS initialization.
                        [default: local]
  --bucket TEXT         Name of the Couchbase bucket to initialize in.
  -h, --help            Show this message and exit.

The init command must be run at least once for each Agent Catalog environment. By default, init will run both locally and on Couchbase, initializing your catalog environment and your activity environment on each. For instances where init has already been run on Couchbase (or vice-versa), use the --no-db and --no-local flags respectively. In the example below, the catalog environment and the activity environment is only locally initialized:

$ agentc init --no-db

`ls` Command¶

The purpose of the ls command is to list out all items in the latest version of your Agent Catalog instance.

$ agentc ls --help
Usage: agentc ls [OPTIONS] [[tools|prompts]]...

  List all indexed tools and/or prompts in the catalog.

Options:
  --db / --no-db        Flag to force a DB-only search.  [default: no-db]
  --local / --no-local  Flag to force a local-only search.  [default: local]
  --dirty / --no-dirty  Flag to process and search amongst dirty source files.
                        [default: dirty]
  --bucket TEXT         Name of Couchbase bucket that is being used for Agent
                        Catalog.
  -h, --help            Show this message and exit.

By default, the ls command will only list items in a local and potentially dirty catalog instance. To list out all items in your Couchbase instance requires the --db flag. A common use case for this command involves running this command after index to see whether or not a certain tool exists in your local catalog.

Warning

This command is the equivalent to a SELECT * FROM agent_catalog.[tools|prompts]; and should be used sparingly with the --db flag. To view aggregate information about your catalog, use the status command instead.

`publish` Command¶

The primary purpose of the publish command is to "snapshot" your local catalog instance and persist this snapshot to Couchbase.

$ agentc publish --help
Usage: agentc publish [OPTIONS]
                      [[tools|prompts|logs]]...

  Upload the local catalog and/or logs to a Couchbase instance. By default, only
  tools and prompts are published unless log is explicitly specified.

Options:
  --bucket TEXT  Name of the Couchbase bucket to publish to.
  -an, --annotations <TEXT TEXT>...
                 Snapshot level annotations to be added while publishing
                 catalogs.
  -h, --help     Show this message and exit.

The publish command, similar to all other Couchbase-interfacing commands (e.g., clean, find, etc...) reads Couchbase authentication details from your environment. To override the bucket being published to, users can specify the bucket name directly via the --bucket option. In the example below, both tools and prompts are published to a bucket named test_bucket:

$ agentc publish --bucket test_bucket

Users can also choose to selectively publish tools, prompts, or logs to Couchbase. By default, only tools and prompts are published -- logs are expected to be continuously pushed to Couchbase while your application is running (thus, the logs choice is primarily for recovery operations). In the example below, only tools are published:

$ agentc publish tools

`status` Command¶

The purpose of the status command is to view aggregate information about your Agent Catalog instance.

$ agentc status --help
Usage: agentc status [OPTIONS]
                     [[tools|prompts]]...

  Show the (aggregate) status of your Agent Catalog environment.

Options:
  --dirty / --no-dirty  Flag to process and compare against dirty source files.
                        [default: dirty]
  --db / --no-db        Flag to include / exclude items from the DB-catalog
                        while displaying status.
  --local / --no-local  Flag to include / exclude items from the local-FS-
                        catalog while displaying status.  [default: local]
  --bucket TEXT         Name of the Couchbase bucket hosting the Agent Catalog.
  -h, --help            Show this message and exit.

TODO

`version` Command¶

The purpose of the version command is to display the current version of the agentc package.

$ agentc version --help
Usage: agentc version [OPTIONS]

  Show the current version of Agent Catalog.

Options:
  -h, --help  Show this message and exit.

$ agentc version
0.0.0

agentc Command Documentation¶

add Command¶

clean Command¶

env Command¶

execute Command¶

find Command¶

Search By Name¶

Search By Query¶

Filter By Annotations¶

Local Only Search¶

index Command¶

init Command¶

ls Command¶

publish Command¶

status Command¶

version Command¶

`agentc` Command Documentation¶

`add` Command¶

`clean` Command¶

`env` Command¶

`execute` Command¶

`find` Command¶

`index` Command¶

`init` Command¶

`ls` Command¶

`publish` Command¶

`status` Command¶

`version` Command¶