CLI Reference

Installation¶

The cloud-agent-cli entry point is installed automatically when you run uv sync.

uv run cloud-agent-cli --help

Global observability options¶

--tracing toggles shared tracing state (concierge-cloud-agent tracer name).
--mlflow enables MLflow tracing bootstrap for langgraph, microsoft-agent-framework, and github-copilot-sdk agents.
--verbose enables DEBUG logging.

Task Commands¶

Dispatch a task¶

All built-in agents (echo, langgraph, github-copilot-sdk, and microsoft-agent-framework) share the same payload contract: a non-empty message string is required.

uv run cloud-agent-cli task dispatch \
  --agent-type echo \
  --payload '{"message": "hello world"}'

Dispatch a LangGraph task¶

uv run cloud-agent-cli task dispatch \
  --agent-type langgraph \
  --payload '{"message": "Hello LangGraph"}'

The worker processes the task and stores the result. Poll with:

uv run cloud-agent-cli task get <uuid>

A successful result looks like:

{
  "message": "Hello LangGraph",
  "reply": "Hello LangGraph",
  "tool_calls": [
    {"name": "echo", "args": {"text": "Hello LangGraph"}}
  ]
}

Options:

Flag	Required	Description
`--agent-type`	Yes	Registered agent identifier
`--payload`	No	JSON string (default `{}`)
`--max-retries`	No	Override default max retries

Output (JSON):

{
  "id": "550e8400-...",
  "agent_type": "echo",
  "status": "QUEUED",
  ...
}

Get a task by ID¶

uv run cloud-agent-cli task get <uuid>

List tasks¶

# All tasks
uv run cloud-agent-cli task list

# Filter by status
uv run cloud-agent-cli task list --status QUEUED

# Filter by agent type
uv run cloud-agent-cli task list --agent-type echo

# Pagination
uv run cloud-agent-cli task list --limit 10 --offset 20

Cancel a task¶

uv run cloud-agent-cli task cancel <uuid>

Worker Command¶

The worker polls the task queue and executes tasks using registered agents.

# Run the worker indefinitely
uv run cloud-agent-cli worker

# Run for a fixed number of iterations (useful for testing)
uv run cloud-agent-cli worker --max-iterations 5

The worker handles SIGINT / SIGTERM gracefully — it finishes any task in progress before shutting down.

You can also run the worker directly as a Python module:

python -m concierge.cloud_agent.infrastructure.cli.worker

Agent List Command¶

uv run cloud-agent-cli agents

Output:

["echo", "langgraph", "github-copilot-sdk", "microsoft-agent-framework"]

Configuration¶

All settings are controlled by environment variables (or a .env file).

Variable	Default	Description
`CLOUD_AGENT_REPOSITORY_BACKEND`	`memory`	`memory` / `postgres` / `azure-postgres`
`CLOUD_AGENT_TABLE_NAME`	`cloud_agent_tasks`	SQL table name
`CLOUD_AGENT_QUEUE_BACKEND`	`memory`	`memory` / `azure-storage-queue`
`CLOUD_AGENT_QUEUE_NAME`	`cloud-agent-tasks`	Main queue name
`CLOUD_AGENT_DLQ_NAME`	`cloud-agent-dlq`	Dead letter queue name
`CLOUD_AGENT_AZURE_STORAGE_ACCOUNT_URL`	—	Azure Storage queue endpoint (Entra ID auth via `DefaultAzureCredential`)
`CLOUD_AGENT_VISIBILITY_TIMEOUT_SECONDS`	`60`	Queue visibility timeout
`CLOUD_AGENT_MAX_RETRIES`	`3`	Default max retries
`CLOUD_AGENT_WORKER_CONCURRENCY`	`1`	Worker concurrency (future)
`CLOUD_AGENT_POLL_INTERVAL_SECONDS`	`1.0`	Polling interval when queue empty
`AGENTS_LANGGRAPH_MODEL`	`azure_ai:gpt-5`	Model string for `init_chat_model` used by LangGraph agents
`AGENTS_LANGGRAPH_SYSTEM_PROMPT`	(built-in)	System prompt for LangGraph agents
`AGENTS_GITHUB_COPILOT_SDK_MODEL`	`gpt-5-mini`	Model name for `github-copilot-sdk`
`AGENTS_GITHUB_COPILOT_SDK_SYSTEM_PROMPT`	(built-in)	System prompt for `github-copilot-sdk`
`AGENTS_MICROSOFT_AGENT_FRAMEWORK_MODEL`	`gpt-5`	Model string for `microsoft-agent-framework`
`AGENTS_MICROSOFT_AGENT_FRAMEWORK_SYSTEM_PROMPT`	(built-in)	System prompt for `microsoft-agent-framework`

See the Configuration section in the Overview for backend selection tables and end-to-end .env examples.

Example: Azure Storage Queue backend¶

Authentication uses Microsoft Entra ID via DefaultAzureCredential. Grant the signed-in principal (or managed identity) the Storage Queue Data Contributor role on the storage account.

export CLOUD_AGENT_QUEUE_BACKEND=azure-storage-queue
export CLOUD_AGENT_AZURE_STORAGE_ACCOUNT_URL="https://<account>.queue.core.windows.net"
az login
uv run cloud-agent-cli worker