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