converteo-agent-deployer-cli 1.1.2
A custom CLI to operate CRUD ops on Agent Engine resources. List, Create, Update and Delete agents in Agent Engine.
Requires Python: >=3.10

# Converteo Agent Deployer CLI

Simple CLI for creating, listing, updating, and deleting Vertex AI Agent Engine apps.

## Prerequisites

- Python 3.10+
- Google Cloud SDK (`gcloud`) installed and authenticated
- Application Default Credentials (ADC) set up for Vertex AI
- uv as a Python package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)

### gcloud auth + ADC

This CLI uses ADC under the hood (via `google-cloud-aiplatform`). Make sure you have a
valid login and ADC available:

```bash
gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
```

Set `APPLICATION_DEFAULT_CREDENTIALS` to the ADC JSON file path (required for both user
credentials and service accounts). Ensure the credential has Vertex AI permissions in
the target project.

## Install

Install the Python package from Pypi:

```bash
uv venv
source .venv/bin/activate
uv pip install converteo-agent-deployer-cli 
```

## Configuration (.env)

The CLI reads defaults from a `.env` file in the working directory (or one you pass via
`--env-file`). Any variables prefixed with `SECRET_` are interpreted as Secret Manager
secrets. Required variables:

- `DEPLOYMENT_PROJECT_ID`: Google Cloud project ID
- `DEPLOYMENT_LOCATION`: Vertex AI region (e.g. `us-central1`)
- `DEPLOYMENT_STAGING_BUCKET`: GCS bucket for staging builds (e.g. `gs://my-bucket`)
- `DEPLOYMENT_MODULE`: Python module path that contains your agent definition
- `DEPLOYMENT_FILE`: Attribute name inside the module that exposes the agent module
- `DEPLOYMENT_ROOT_AGENT`: Attribute name for the root agent in the file

Example `.env` with required and optional variables:

```dotenv
DEPLOYMENT_PROJECT_ID=my-gcp-project
DEPLOYMENT_LOCATION=us-central1
DEPLOYMENT_STAGING_BUCKET=gs://my-staging-bucket
DEPLOYMENT_MODULE=my_agent_package
DEPLOYMENT_FILE=agent
DEPLOYMENT_ROOT_AGENT=root_agent

# Optional: any other env vars needed by your agent at runtime
API_BASE_URL=https://example.internal

# Optional: secrets (prefix with SECRET_ to store in Secret Manager)
SECRET_API_KEY=super-secret
```

Notes:
- The CLI will load dependencies from `pyproject.toml` if present, otherwise
  `requirements.txt`.
- Environment variables from `.env` are passed to Vertex AI during create/update.
- Keys prefixed with `SECRET_` are sent as secrets (stored with the `latest` version).
- The agent must be exposed as `root_agent` on the object referenced by
  `DEPLOYMENT_FILE`.

## Usage

General form:

```bash
adcli [GLOBAL OPTIONS] COMMAND [ARGS] [OPTIONS]
```

Global options (apply to all commands; set once via `.env` or pass flags):

- `--project` (required) Google Cloud project ID (defaults to `DEPLOYMENT_PROJECT_ID`)
- `--location` (required) Vertex AI region (defaults to `DEPLOYMENT_LOCATION`)
- `--module` (required) Python module path with the agent definition (defaults to `DEPLOYMENT_MODULE`)
- `--file` (required) Attribute name inside the module that exposes the agent module (defaults to `DEPLOYMENT_FILE`)
- `--root-agent` (required) Attribute name for the root agent (defaults to `DEPLOYMENT_ROOT_AGENT`)
- `--staging-bucket` (required for create/update) GCS bucket for staging builds (defaults to
  `DEPLOYMENT_STAGING_BUCKET`)

```bash
adcli --help
```

Create an agent (required: `--display-name`, `--description`):

```bash
adcli create \
  --display-name "My Agent" \
  --description "Customer support agent"
```

Optional flags for `create`:

- `--env-file PATH` (default: `.env`) load environment variables for the deployment
- `--requirements PATH` (default: `requirements.txt`) requirements file to use
- `--extra-package PATH` (repeatable) add extra packages/wheels to the build

List agents (optional: `--display-name` filter):

```bash
adcli list
adcli list --display-name "My Agent"
```

Update an agent (required arg: `RESOURCE_NAME`):

```bash
adcli update projects/PROJECT_ID/locations/LOCATION/agentEngines/AGENT_ID \
  --display-name "My Agent v2" \
  --description "Updated description"
```

Optional flags for `update`:

- `--display-name NAME` new display name
- `--description TEXT` new description
- `--env-file PATH` (default: `.env`) load environment variables for the deployment
- `--requirements PATH` (default: `requirements.txt`) requirements file to use
- `--extra-package PATH` (repeatable) add extra packages/wheels to the build

Delete an agent (required arg: `RESOURCE_NAME`):

```bash
adcli delete projects/PROJECT_ID/locations/LOCATION/agentEngines/AGENT_ID
```

Resource name format:

```text
projects/PROJECT_ID/locations/LOCATION/agentEngines/AGENT_ID
```