From 411b63ae831a0c4327ba2722b19ecfb73de715bd Mon Sep 17 00:00:00 2001 From: notgitika Date: Thu, 19 Mar 2026 18:35:38 -0400 Subject: [PATCH] docs: update CLI command reference with missing commands, options, and aliases Add command aliases table, observability section (logs, traces), and missing flags across create, deploy, status, invoke, dev, and other commands. Fix AGENTS.md eval command names and add logs/traces entries. --- AGENTS.md | 12 +- docs/commands.md | 364 ++++++++++++++++++++++++++++++++++------------- 2 files changed, 270 insertions(+), 106 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 13400699..bc046f2e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,10 +30,14 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`. - `status` - Check deployment status - `dev` - Local development server (CodeZip: uvicorn with hot-reload; Container: Docker build + run with volume mount) - `invoke` - Invoke agents (local or deployed) -- `run eval` - Run on-demand evaluation against agent sessions -- `eval history` - View past eval run results +- `run evals` - Run on-demand evaluation against agent sessions +- `evals history` - View past eval run results - `pause online-eval` - Pause (disable) a deployed online eval config - `resume online-eval` - Resume (enable) a paused online eval config +- `logs` - Stream or search agent runtime logs +- `logs evals` - Stream or search online eval logs +- `traces list` - List recent traces for a deployed agent +- `traces get` - Download a trace to a JSON file - `package` - Package agent artifacts without deploying (zip for CodeZip, container image build for Container) - `validate` - Validate configuration files - `update` - Check for CLI updates @@ -53,8 +57,8 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`. ## Primitives Architecture -All resource types (agent, memory, identity, gateway, mcp-tool) are modeled as **primitives** -- self-contained classes -in `src/cli/primitives/` that own the full add/remove lifecycle for their resource type. +All resource types (agent, memory, identity, evaluator, online-eval, gateway, mcp-tool) are modeled as **primitives** -- +self-contained classes in `src/cli/primitives/` that own the full add/remove lifecycle for their resource type. Each primitive extends `BasePrimitive` and implements: `add()`, `remove()`, `previewRemove()`, `getRemovable()`, `registerCommands()`, and `addScreen()`. diff --git a/docs/commands.md b/docs/commands.md index 98f05e18..a2fb0ec8 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -2,6 +2,23 @@ All commands support non-interactive (scriptable) usage with flags. Use `--json` for machine-readable output. +Run `agentcore` without arguments to launch the interactive TUI. Flags marked `[non-interactive]` trigger CLI mode — run +`agentcore help modes` for details. + +## Command Aliases + +| Command | Alias | +| --------- | ----- | +| `deploy` | `p` | +| `dev` | `d` | +| `invoke` | `i` | +| `status` | `s` | +| `logs` | `l` | +| `traces` | `t` | +| `package` | `pkg` | + +--- + ## Project Lifecycle ### create @@ -23,6 +40,14 @@ agentcore create \ --memory shortTerm \ --output-dir ./projects +# With networking +agentcore create \ + --name MyProject \ + --defaults \ + --network-mode VPC \ + --subnets subnet-abc,subnet-def \ + --security-groups sg-123 + # Skip agent creation agentcore create --name MyProject --no-agent @@ -30,22 +55,26 @@ agentcore create --name MyProject --no-agent agentcore create --name MyProject --defaults --dry-run ``` -| Flag | Description | -| ---------------------- | -------------------------------------------------------------------------------- | -| `--name ` | Project name (alphanumeric, max 23 chars) | -| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) | -| `--no-agent` | Skip agent creation | -| `--language ` | `Python` or `TypeScript` | -| `--framework ` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` | -| `--model-provider

` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | -| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | -| `--api-key ` | API key for non-Bedrock providers | -| `--memory ` | `none`, `shortTerm`, `longAndShortTerm` | -| `--output-dir

` | Output directory | -| `--skip-git` | Skip git initialization | -| `--skip-python-setup` | Skip venv setup | -| `--dry-run` | Preview without creating | -| `--json` | JSON output | +| Flag | Description | +| ------------------------- | -------------------------------------------------------------------------------- | +| `--name ` | Project name (alphanumeric, starts with letter, max 23 chars) | +| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) | +| `--no-agent` | Skip agent creation | +| `--language ` | `Python` (default) | +| `--framework ` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` | +| `--model-provider

` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | +| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | +| `--api-key ` | API key for non-Bedrock providers | +| `--memory ` | `none`, `shortTerm`, `longAndShortTerm` | +| `--protocol ` | `HTTP` (default), `MCP`, `A2A` | +| `--network-mode ` | `PUBLIC` (default) or `VPC` | +| `--subnets ` | Comma-separated subnet IDs (required for VPC mode) | +| `--security-groups ` | Comma-separated security group IDs (required for VPC mode) | +| `--output-dir

` | Output directory | +| `--skip-git` | Skip git initialization | +| `--skip-python-setup` | Skip venv setup | +| `--dry-run` | Preview without creating | +| `--json` | JSON output | ### deploy @@ -53,30 +82,44 @@ Deploy infrastructure to AWS. ```bash agentcore deploy -agentcore deploy -y --progress # Auto-confirm with progress -agentcore deploy -v --json # Verbose JSON output +agentcore deploy -y # Auto-confirm +agentcore deploy -y -v # Auto-confirm with verbose output +agentcore deploy --plan # Preview without deploying (dry-run) +agentcore deploy --diff # Show CDK diff without deploying +agentcore deploy --target staging -y # Deploy to a specific target +agentcore deploy -y --json # JSON output ``` -| Flag | Description | -| --------------- | --------------------- | -| `-y, --yes` | Auto-confirm prompts | -| `--progress` | Real-time progress | -| `-v, --verbose` | Resource-level events | -| `--json` | JSON output | +| Flag | Description | +| ----------------- | --------------------------------------------- | +| `--target ` | Deployment target name (default: `"default"`) | +| `-y, --yes` | Auto-confirm prompts | +| `-v, --verbose` | Resource-level deployment events | +| `--plan` | Preview deployment without deploying | +| `--diff` | Show CDK diff without deploying | +| `--json` | JSON output | ### status -Check deployment status. +Check deployment status and resource details. ```bash agentcore status agentcore status --agent MyAgent +agentcore status --type evaluator +agentcore status --state deployed +agentcore status --agent-runtime-id abc123 +agentcore status --json ``` -| Flag | Description | -| ------------------------- | ------------------- | -| `--agent ` | Specific agent | -| `--agent-runtime-id ` | Specific runtime ID | +| Flag | Description | +| ------------------------- | ----------------------------------------------------------------------------------------------- | +| `--agent-runtime-id ` | Look up a specific agent runtime by ID | +| `--target ` | Select deployment target | +| `--type ` | Filter by resource type: `agent`, `memory`, `credential`, `gateway`, `evaluator`, `online-eval` | +| `--state ` | Filter by deployment state: `deployed`, `local-only`, `pending-removal` | +| `--agent ` | Filter to a specific agent | +| `--json` | JSON output | ### validate @@ -113,28 +156,40 @@ agentcore add agent \ --type byo \ --code-location ./my-agent \ --entrypoint main.py \ - --language Python \ + --language Python + +# With MCP protocol and VPC networking +agentcore add agent \ + --name MyAgent \ --framework Strands \ - --model-provider Bedrock + --model-provider Bedrock \ + --protocol MCP \ + --network-mode VPC \ + --subnets subnet-abc,subnet-def \ + --security-groups sg-123 ``` -| Flag | Description | -| ------------------------ | -------------------------------------------------------------------------------- | -| `--name ` | Agent name | -| `--type ` | `create` (default) or `byo` | -| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | -| `--language ` | `Python`, `TypeScript`, `Other` (BYO) | -| `--framework ` | Agent framework | -| `--model-provider

` | Model provider | -| `--api-key ` | API key for non-Bedrock | -| `--memory ` | Memory option (create only) | -| `--code-location ` | Code path (BYO only) | -| `--entrypoint ` | Entry file (BYO only) | -| `--json` | JSON output | +| Flag | Description | +| ------------------------- | -------------------------------------------------------------------------------- | +| `--name ` | Agent name (alphanumeric, starts with letter, max 64 chars) | +| `--type ` | `create` (default) or `byo` | +| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | +| `--language ` | `Python` (create); `Python`, `TypeScript`, `Other` (BYO) | +| `--framework ` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` | +| `--model-provider

` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | +| `--api-key ` | API key for non-Bedrock providers | +| `--memory ` | `none`, `shortTerm`, `longAndShortTerm` (create only) | +| `--protocol ` | `HTTP` (default), `MCP`, `A2A` | +| `--code-location ` | Path to existing code (BYO only) | +| `--entrypoint ` | Entry file relative to code-location (BYO, default: `main.py`) | +| `--network-mode ` | `PUBLIC` (default) or `VPC` | +| `--subnets ` | Comma-separated subnet IDs (required for VPC mode) | +| `--security-groups ` | Comma-separated security group IDs (required for VPC mode) | +| `--json` | JSON output | ### add memory -Add a memory resource. Memory is a top-level resource in the flat resource model. +Add a memory resource. ```bash agentcore add memory \ @@ -143,13 +198,12 @@ agentcore add memory \ --expiry 30 ``` -| Flag | Description | -| ---------------------- | ------------------------------------------------------------------------- | -| `--name ` | Memory name | -| `--description ` | Description | -| `--strategies ` | Comma-separated: `SEMANTIC`, `SUMMARIZATION`, `USER_PREFERENCE`, `CUSTOM` | -| `--expiry ` | Event expiry (default: 30) | -| `--json` | JSON output | +| Flag | Description | +| ---------------------- | --------------------------------------------------------------- | +| `--name ` | Memory name | +| `--strategies ` | Comma-separated: `SEMANTIC`, `SUMMARIZATION`, `USER_PREFERENCE` | +| `--expiry ` | Event expiry duration in days (default: 30, min: 7, max: 365) | +| `--json` | JSON output | ### add gateway @@ -184,6 +238,9 @@ agentcore add gateway \ | `--allowed-scopes ` | Comma-separated allowed scopes (optional for CUSTOM_JWT) | | `--agent-client-id ` | Agent OAuth client ID for Bearer token auth (CUSTOM_JWT) | | `--agent-client-secret ` | Agent OAuth client secret (CUSTOM_JWT) | +| `--agents ` | Comma-separated agent names | +| `--no-semantic-search` | Disable semantic search for tool discovery | +| `--exception-level ` | Exception verbosity level (default: `NONE`) | | `--json` | JSON output | ### add gateway-target @@ -248,30 +305,31 @@ agentcore add gateway-target \ --gateway MyGateway ``` -| Flag | Description | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `--name ` | Target name | -| `--description ` | Target description | -| `--type ` | Target type (required): `mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, `lambda-function-arn` | -| `--endpoint ` | MCP server endpoint URL (mcp-server) | -| `--language ` | Implementation language: Python, TypeScript, Other (mcp-server) | -| `--host ` | Compute host: Lambda or AgentCoreRuntime (mcp-server) | -| `--gateway ` | Gateway to attach target to | -| `--outbound-auth ` | `oauth`, `api-key`, or `none` (varies by target type) | -| `--credential-name ` | Existing credential name for outbound auth | -| `--oauth-client-id ` | OAuth client ID (creates credential inline) | -| `--oauth-client-secret ` | OAuth client secret (creates credential inline) | -| `--oauth-discovery-url ` | OAuth discovery URL (creates credential inline) | -| `--oauth-scopes ` | OAuth scopes, comma-separated | -| `--rest-api-id ` | API Gateway REST API ID (api-gateway) | -| `--stage ` | API Gateway stage name (api-gateway) | -| `--tool-filter-path ` | Filter API paths, supports wildcards (api-gateway) | -| `--tool-filter-methods ` | Comma-separated HTTP methods to expose (api-gateway) | -| `--schema ` | Path to schema file, relative to project root (open-api-schema, smithy-model) | -| `--schema-s3-account ` | AWS account for S3-hosted schema (open-api-schema, smithy-model) | -| `--lambda-arn ` | Lambda function ARN (lambda-function-arn) | -| `--tool-schema-file ` | Tool schema file, relative to project root or absolute path (lambda-function-arn) | -| `--json` | JSON output | +| Flag | Description | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `--name ` | Target name | +| `--description ` | Target description | +| `--type ` | Target type (required): `mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, `lambda-function-arn` | +| `--endpoint ` | MCP server endpoint URL (mcp-server) | +| `--language ` | Implementation language: Python, TypeScript, Other (mcp-server) | +| `--host ` | Compute host: Lambda or AgentCoreRuntime (mcp-server) | +| `--gateway ` | Gateway to attach target to | +| `--outbound-auth ` | `oauth`, `api-key`, or `none` (varies by target type) | +| `--credential-name ` | Existing credential name for outbound auth | +| `--oauth-client-id ` | OAuth client ID (creates credential inline) | +| `--oauth-client-secret ` | OAuth client secret (creates credential inline) | +| `--oauth-discovery-url ` | OAuth discovery URL (creates credential inline) | +| `--oauth-scopes ` | OAuth scopes, comma-separated | +| `--rest-api-id ` | API Gateway REST API ID (api-gateway) | +| `--stage ` | API Gateway stage name (api-gateway) | +| `--tool-filter-path ` | Filter API paths, supports wildcards (api-gateway) | +| `--tool-filter-methods ` | Comma-separated HTTP methods to expose (api-gateway) | +| `--tool-filter-description ` | Tool filter description pattern | +| `--schema ` | Path to schema file, relative to project root (open-api-schema, smithy-model) | +| `--schema-s3-account ` | AWS account for S3-hosted schema (open-api-schema, smithy-model) | +| `--lambda-arn ` | Lambda function ARN (lambda-function-arn) | +| `--tool-schema-file ` | Tool schema file, relative to project root or absolute path (lambda-function-arn) | +| `--json` | JSON output | > **Note**: `smithy-model` and `lambda-function-arn` use IAM role auth and do not support `--outbound-auth`. > `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`. @@ -384,44 +442,116 @@ agentcore remove all --dry-run # Preview ### dev -Start local development server. +Start local development server with hot-reload. ```bash agentcore dev agentcore dev --agent MyAgent --port 3000 agentcore dev --logs # Non-interactive agentcore dev --invoke "Hello" --stream # Direct invoke + +# MCP protocol dev commands +agentcore dev --invoke list-tools +agentcore dev --invoke call-tool --tool myTool --input '{"arg": "value"}' ``` -| Flag | Description | -| ----------------------- | ------------------------------- | -| `-p, --port ` | Port (default: 8080) | -| `-a, --agent ` | Agent to run | -| `-i, --invoke ` | Invoke running server | -| `-s, --stream` | Stream response (with --invoke) | -| `-l, --logs` | Non-interactive stdout logging | +| Flag | Description | +| ----------------------- | ------------------------------------------------------ | +| `-p, --port ` | Port (default: 8080; MCP uses 8000, A2A uses 9000) | +| `-a, --agent ` | Agent to run (required if multiple agents) | +| `-i, --invoke ` | Invoke running server | +| `-s, --stream` | Stream response (with --invoke) | +| `-l, --logs` | Non-interactive stdout logging | +| `--tool ` | MCP tool name (with `--invoke call-tool`) | +| `--input ` | MCP tool arguments as JSON (with `--invoke call-tool`) | ### invoke -Invoke local or deployed agents. +Invoke a deployed agent endpoint. ```bash agentcore invoke "What can you do?" agentcore invoke --prompt "Hello" --stream -agentcore invoke --agent MyAgent -agentcore invoke --session-id abc123 # Continue session -agentcore invoke --new-session # Fresh session -agentcore invoke --json # JSON output +agentcore invoke --agent MyAgent --target staging +agentcore invoke --session-id abc123 # Continue session +agentcore invoke --json # JSON output + +# MCP protocol invoke +agentcore invoke call-tool --tool myTool --input '{"key": "value"}' +``` + +| Flag | Description | +| ------------------- | -------------------------------------------------------- | +| `[prompt]` | Prompt text (positional argument) | +| `--prompt ` | Prompt text (flag, takes precedence over positional) | +| `--agent ` | Specific agent | +| `--target ` | Deployment target | +| `--session-id ` | Continue a specific session | +| `--user-id ` | User ID for runtime invocation (default: `default-user`) | +| `--stream` | Stream response in real-time | +| `--tool ` | MCP tool name (use with `call-tool` prompt) | +| `--input ` | MCP tool arguments as JSON (use with `--tool`) | +| `--json` | JSON output | + +--- + +## Observability + +### logs + +Stream or search agent runtime logs. + +```bash +agentcore logs # Stream logs (follow mode) +agentcore logs --agent MyAgent # Specific agent +agentcore logs --since 1h --level error # Search last hour for errors +agentcore logs --since 2d --until 1d --query "timeout" +agentcore logs --json # JSON Lines output +``` + +| Flag | Description | +| ----------------- | -------------------------------------------------------------------------------- | +| `--agent ` | Select specific agent | +| `--since