diff --git a/src/assets/AGENTS.md b/src/assets/AGENTS.md index 9c583f4d7..7ab8ab6d9 100644 --- a/src/assets/AGENTS.md +++ b/src/assets/AGENTS.md @@ -2,27 +2,47 @@ This directory stores: -- Template assets for agents written in different Languages, SDKs and having different configurations +- Template assets for agents written in different languages, SDKs, and configurations - Container templates (`container/python/`) with `Dockerfile` and `.dockerignore` for Container build agents +- Vended documentation (`README.md`, `agents/AGENTS.md`) copied into user projects at create time +- CDK project template (`cdk/`) using `@aws/agentcore-cdk` L3 constructs +- Evaluator templates (`evaluators/`) for code-based evaluators +- MCP tool templates (`mcp/`) for Lambda and AgentCoreRuntime compute ### Directory Layout ``` assets/ -├── python/ # Framework templates (one per SDK) -│ ├── strands/ -│ ├── langchain_langgraph/ -│ ├── googleadk/ -│ ├── openaiagents/ -│ └── autogen/ +├── README.md # Vended to project root as project README +├── AGENTS.md # This file — internal dev context +├── agents/ +│ └── AGENTS.md # Vended to project root for AI coding assistants +├── python/ # Framework templates (one per SDK per protocol) +│ ├── http/ # HTTP protocol agents +│ │ ├── strands/ +│ │ ├── langchain_langgraph/ +│ │ ├── googleadk/ +│ │ ├── openaiagents/ +│ │ └── autogen/ +│ ├── mcp/ # MCP protocol agents +│ │ └── standalone/ +│ └── a2a/ # A2A protocol agents +│ ├── strands/ +│ ├── langchain_langgraph/ +│ └── googleadk/ +├── typescript/ # TypeScript agent templates ├── container/ # Container build templates │ └── python/ │ ├── Dockerfile │ └── dockerignore.template -└── agents/ # AGENTS.md vended to user projects +├── cdk/ # CDK project template (@aws/agentcore-cdk) +├── evaluators/ # Code-based evaluator templates +└── mcp/ # MCP tool templates (Lambda + AgentCoreRuntime) + ├── python/ + └── python-lambda/ ``` -The rendering logic is rooted in the `AgentEnvSpec` and must ALWAYS respect the configuration in the Spec. +The rendering logic is rooted in the `AgentEnvSpec` and must ALWAYS respect the configuration in the spec. For Container builds, `BaseRenderer.render()` automatically copies the `container//` templates (Dockerfile, .dockerignore) into the agent directory when `buildType === 'Container'`. @@ -31,7 +51,10 @@ For Container builds, `BaseRenderer.render()` automatically copies the `containe - Always make sure the templates are as close to working code as possible - AVOID as much as possible using any conditionals within the templates +- Test template rendering with `agentcore add agent` for each framework/protocol combination ## How to use the assets in this directory -- These assets are rendered by the CLI's template renderer in `src/cli/templates/`. +- These assets are rendered by the CLI's template renderer in `src/cli/templates/` +- The `README.md` and `agents/AGENTS.md` are copied verbatim (no template rendering) during project creation +- The `.llm-context/` files are sourced from `src/schema/llm-compacted/` and written during init diff --git a/src/assets/README.md b/src/assets/README.md index f808b99f7..7064d6466 100644 --- a/src/assets/README.md +++ b/src/assets/README.md @@ -5,14 +5,19 @@ This project was created with the [AgentCore CLI](https://github.com/aws/agentco ## Project Structure ``` -. my-project/ +├── AGENTS.md # AI coding assistant context ├── agentcore/ -│ ├── .env.local # API keys (gitignored) -│ ├── agentcore.json # Resource specifications -│ ├── aws-targets.json # Deployment targets -│ └── cdk/ # CDK infrastructure -├── app/ # Application code +│ ├── agentcore.json # Project config (agents, memories, credentials, gateways, evaluators) +│ ├── aws-targets.json # Deployment targets (account + region) +│ ├── .env.local # Secrets — API keys (gitignored) +│ ├── .llm-context/ # TypeScript type definitions for AI assistants +│ │ ├── agentcore.ts # AgentCoreProjectSpec types +│ │ ├── aws-targets.ts # Deployment target types +│ │ └── mcp.ts # Gateway and MCP tool types +│ └── cdk/ # CDK infrastructure (@aws/agentcore-cdk) +├── app/ # Agent application code +└── evaluators/ # Custom evaluator code (if any) ``` ## Getting Started @@ -20,7 +25,9 @@ my-project/ ### Prerequisites - **Node.js** 20.x or later -- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/)) +- **Python 3.10+** and **uv** for Python agents ([install uv](https://docs.astral.sh/uv/getting-started/installation/)) +- **AWS credentials** configured (`aws configure` or environment variables) +- **Docker** (only for Container build agents) ### Development @@ -38,42 +45,60 @@ Deploy to AWS: agentcore deploy ``` -Or use CDK directly: +## Commands -```bash -cd agentcore/cdk -npx cdk deploy -``` +| Command | Description | +| --- | --- | +| `agentcore create` | Create a new AgentCore project | +| `agentcore add` | Add resources (agent, memory, credential, gateway, evaluator, policy) | +| `agentcore remove` | Remove resources | +| `agentcore dev` | Run agent locally with hot-reload | +| `agentcore deploy` | Deploy to AWS via CDK | +| `agentcore status` | Show deployment status | +| `agentcore invoke` | Invoke agent (local or deployed) | +| `agentcore logs` | View agent logs | +| `agentcore traces` | View agent traces | +| `agentcore eval` | Run evaluations | +| `agentcore package` | Package agent artifacts | +| `agentcore validate` | Validate configuration | +| `agentcore pause` | Pause a deployed agent | +| `agentcore resume` | Resume a paused agent | +| `agentcore fetch` | Fetch remote resource definitions | +| `agentcore import` | Import existing resources | +| `agentcore update` | Check for CLI updates | ## Configuration -Edit the JSON files in `agentcore/` to configure your agents, memory, and credentials. See `agentcore/.llm-context/` for -type definitions and validation constraints. +Edit the JSON files in `agentcore/` to configure your project. See `agentcore/.llm-context/` for type definitions and validation constraints. -The project uses a **flat resource model** where agents, memories, and credentials are top-level arrays in -`agentcore.json`. +The project uses a **flat resource model** — agents, memories, credentials, gateways, evaluators, and policies are top-level arrays in `agentcore.json`. Resources are independent; agents discover memories and credentials at runtime via environment variables or SDK calls. -## Commands +## Resources -| Command | Description | -| -------------------- | ----------------------------------------------- | -| `agentcore create` | Create a new AgentCore project | -| `agentcore add` | Add resources (agent, memory, credential, target) | -| `agentcore remove` | Remove resources | -| `agentcore dev` | Run agent locally | -| `agentcore deploy` | Deploy to AWS | -| `agentcore status` | Show deployment status | -| `agentcore invoke` | Invoke agent (local or deployed) | -| `agentcore package` | Package agent artifacts | -| `agentcore validate` | Validate configuration | -| `agentcore update` | Check for CLI updates | +| Resource | Purpose | +| --- | --- | +| Agent (runtime) | HTTP, MCP, or A2A agent deployed to AgentCore Runtime | +| Memory | Persistent context storage with configurable strategies | +| Credential | API key or OAuth credential providers | +| Gateway | MCP gateway that routes tool calls to targets | +| Gateway Target | Tool implementation (Lambda, MCP server, OpenAPI, Smithy, API Gateway) | +| Evaluator | Custom LLM-as-a-Judge or code-based evaluation | +| Online Eval Config | Continuous evaluation pipeline for deployed agents | +| Policy | Cedar authorization policies for gateway tools | ### Agent Types -- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents) +- **Template agents**: Created from framework templates (Strands, LangChain/LangGraph, GoogleADK, OpenAI Agents, Autogen) - **BYO agents**: Bring your own code with `agentcore add agent --type byo` +- **Import agents**: Import existing Bedrock agents with `agentcore import` + +### Build Types + +- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime +- **Container**: Docker image built via CodeBuild (ARM64), pushed to ECR, and deployed to AgentCore Runtime ## Documentation -- [AgentCore CLI Documentation](https://github.com/aws/agentcore-cli) +- [AgentCore CLI](https://github.com/aws/agentcore-cli) +- [AgentCore CDK Constructs](https://github.com/aws/agentcore-l3-cdk-constructs) - [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) diff --git a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap index 1a51b6b29..67baffe38 100644 --- a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap +++ b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap @@ -4316,27 +4316,47 @@ exports[`Assets Directory Snapshots > Root-level assets > AGENTS.md should match This directory stores: -- Template assets for agents written in different Languages, SDKs and having different configurations +- Template assets for agents written in different languages, SDKs, and configurations - Container templates (\`container/python/\`) with \`Dockerfile\` and \`.dockerignore\` for Container build agents +- Vended documentation (\`README.md\`, \`agents/AGENTS.md\`) copied into user projects at create time +- CDK project template (\`cdk/\`) using \`@aws/agentcore-cdk\` L3 constructs +- Evaluator templates (\`evaluators/\`) for code-based evaluators +- MCP tool templates (\`mcp/\`) for Lambda and AgentCoreRuntime compute ### Directory Layout \`\`\` assets/ -├── python/ # Framework templates (one per SDK) -│ ├── strands/ -│ ├── langchain_langgraph/ -│ ├── googleadk/ -│ ├── openaiagents/ -│ └── autogen/ +├── README.md # Vended to project root as project README +├── AGENTS.md # This file — internal dev context +├── agents/ +│ └── AGENTS.md # Vended to project root for AI coding assistants +├── python/ # Framework templates (one per SDK per protocol) +│ ├── http/ # HTTP protocol agents +│ │ ├── strands/ +│ │ ├── langchain_langgraph/ +│ │ ├── googleadk/ +│ │ ├── openaiagents/ +│ │ └── autogen/ +│ ├── mcp/ # MCP protocol agents +│ │ └── standalone/ +│ └── a2a/ # A2A protocol agents +│ ├── strands/ +│ ├── langchain_langgraph/ +│ └── googleadk/ +├── typescript/ # TypeScript agent templates ├── container/ # Container build templates │ └── python/ │ ├── Dockerfile │ └── dockerignore.template -└── agents/ # AGENTS.md vended to user projects +├── cdk/ # CDK project template (@aws/agentcore-cdk) +├── evaluators/ # Code-based evaluator templates +└── mcp/ # MCP tool templates (Lambda + AgentCoreRuntime) + ├── python/ + └── python-lambda/ \`\`\` -The rendering logic is rooted in the \`AgentEnvSpec\` and must ALWAYS respect the configuration in the Spec. +The rendering logic is rooted in the \`AgentEnvSpec\` and must ALWAYS respect the configuration in the spec. For Container builds, \`BaseRenderer.render()\` automatically copies the \`container//\` templates (Dockerfile, .dockerignore) into the agent directory when \`buildType === 'Container'\`. @@ -4345,10 +4365,13 @@ For Container builds, \`BaseRenderer.render()\` automatically copies the \`conta - Always make sure the templates are as close to working code as possible - AVOID as much as possible using any conditionals within the templates +- Test template rendering with \`agentcore add agent\` for each framework/protocol combination ## How to use the assets in this directory -- These assets are rendered by the CLI's template renderer in \`src/cli/templates/\`. +- These assets are rendered by the CLI's template renderer in \`src/cli/templates/\` +- The \`README.md\` and \`agents/AGENTS.md\` are copied verbatim (no template rendering) during project creation +- The \`.llm-context/\` files are sourced from \`src/schema/llm-compacted/\` and written during init " `; @@ -4360,14 +4383,19 @@ This project was created with the [AgentCore CLI](https://github.com/aws/agentco ## Project Structure \`\`\` -. my-project/ +├── AGENTS.md # AI coding assistant context ├── agentcore/ -│ ├── .env.local # API keys (gitignored) -│ ├── agentcore.json # Resource specifications -│ ├── aws-targets.json # Deployment targets -│ └── cdk/ # CDK infrastructure -├── app/ # Application code +│ ├── agentcore.json # Project config (agents, memories, credentials, gateways, evaluators) +│ ├── aws-targets.json # Deployment targets (account + region) +│ ├── .env.local # Secrets — API keys (gitignored) +│ ├── .llm-context/ # TypeScript type definitions for AI assistants +│ │ ├── agentcore.ts # AgentCoreProjectSpec types +│ │ ├── aws-targets.ts # Deployment target types +│ │ └── mcp.ts # Gateway and MCP tool types +│ └── cdk/ # CDK infrastructure (@aws/agentcore-cdk) +├── app/ # Agent application code +└── evaluators/ # Custom evaluator code (if any) \`\`\` ## Getting Started @@ -4375,7 +4403,9 @@ my-project/ ### Prerequisites - **Node.js** 20.x or later -- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/)) +- **Python 3.10+** and **uv** for Python agents ([install uv](https://docs.astral.sh/uv/getting-started/installation/)) +- **AWS credentials** configured (\`aws configure\` or environment variables) +- **Docker** (only for Container build agents) ### Development @@ -4393,44 +4423,62 @@ Deploy to AWS: agentcore deploy \`\`\` -Or use CDK directly: +## Commands -\`\`\`bash -cd agentcore/cdk -npx cdk deploy -\`\`\` +| Command | Description | +| --- | --- | +| \`agentcore create\` | Create a new AgentCore project | +| \`agentcore add\` | Add resources (agent, memory, credential, gateway, evaluator, policy) | +| \`agentcore remove\` | Remove resources | +| \`agentcore dev\` | Run agent locally with hot-reload | +| \`agentcore deploy\` | Deploy to AWS via CDK | +| \`agentcore status\` | Show deployment status | +| \`agentcore invoke\` | Invoke agent (local or deployed) | +| \`agentcore logs\` | View agent logs | +| \`agentcore traces\` | View agent traces | +| \`agentcore eval\` | Run evaluations | +| \`agentcore package\` | Package agent artifacts | +| \`agentcore validate\` | Validate configuration | +| \`agentcore pause\` | Pause a deployed agent | +| \`agentcore resume\` | Resume a paused agent | +| \`agentcore fetch\` | Fetch remote resource definitions | +| \`agentcore import\` | Import existing resources | +| \`agentcore update\` | Check for CLI updates | ## Configuration -Edit the JSON files in \`agentcore/\` to configure your agents, memory, and credentials. See \`agentcore/.llm-context/\` for -type definitions and validation constraints. +Edit the JSON files in \`agentcore/\` to configure your project. See \`agentcore/.llm-context/\` for type definitions and validation constraints. -The project uses a **flat resource model** where agents, memories, and credentials are top-level arrays in -\`agentcore.json\`. +The project uses a **flat resource model** — agents, memories, credentials, gateways, evaluators, and policies are top-level arrays in \`agentcore.json\`. Resources are independent; agents discover memories and credentials at runtime via environment variables or SDK calls. -## Commands +## Resources -| Command | Description | -| -------------------- | ----------------------------------------------- | -| \`agentcore create\` | Create a new AgentCore project | -| \`agentcore add\` | Add resources (agent, memory, credential, target) | -| \`agentcore remove\` | Remove resources | -| \`agentcore dev\` | Run agent locally | -| \`agentcore deploy\` | Deploy to AWS | -| \`agentcore status\` | Show deployment status | -| \`agentcore invoke\` | Invoke agent (local or deployed) | -| \`agentcore package\` | Package agent artifacts | -| \`agentcore validate\` | Validate configuration | -| \`agentcore update\` | Check for CLI updates | +| Resource | Purpose | +| --- | --- | +| Agent (runtime) | HTTP, MCP, or A2A agent deployed to AgentCore Runtime | +| Memory | Persistent context storage with configurable strategies | +| Credential | API key or OAuth credential providers | +| Gateway | MCP gateway that routes tool calls to targets | +| Gateway Target | Tool implementation (Lambda, MCP server, OpenAPI, Smithy, API Gateway) | +| Evaluator | Custom LLM-as-a-Judge or code-based evaluation | +| Online Eval Config | Continuous evaluation pipeline for deployed agents | +| Policy | Cedar authorization policies for gateway tools | ### Agent Types -- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents) +- **Template agents**: Created from framework templates (Strands, LangChain/LangGraph, GoogleADK, OpenAI Agents, Autogen) - **BYO agents**: Bring your own code with \`agentcore add agent --type byo\` +- **Import agents**: Import existing Bedrock agents with \`agentcore import\` + +### Build Types + +- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime +- **Container**: Docker image built via CodeBuild (ARM64), pushed to ECR, and deployed to AgentCore Runtime ## Documentation -- [AgentCore CLI Documentation](https://github.com/aws/agentcore-cli) +- [AgentCore CLI](https://github.com/aws/agentcore-cli) +- [AgentCore CDK Constructs](https://github.com/aws/agentcore-l3-cdk-constructs) - [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) " `; @@ -4440,103 +4488,114 @@ exports[`Assets Directory Snapshots > Root-level assets > agents/AGENTS.md shoul This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application. -The \`agentcore/\` directory serves as a declarative model of an AgentCore project along with a concrete implementation -through the \`agentcore/cdk/\` project which is modeled to take the configs as input. The project uses a **flat resource -model** where agents, memories, and credentials are top-level arrays. +The \`agentcore/\` directory is a declarative model of the project. The \`agentcore/cdk/\` subdirectory uses the +\`@aws/agentcore-cdk\` L3 constructs to deploy the configuration to AWS. ## Mental Model -The project uses a **flat resource model**. Agents, memories, and credentials are independent top-level arrays in -\`agentcore.json\`. There is no binding or attachment between resources in the schema — each resource is provisioned -independently. To use a memory or credential from an agent, the application code discovers the resource at runtime -(e.g., via environment variables or SDK calls). Tags defined in \`agentcore.json\` flow through to deployed CloudFormation resources. +The project uses a **flat resource model**. Agents, memories, credentials, gateways, evaluators, and policies are +independent top-level arrays in \`agentcore.json\`. There is no binding between resources in the schema — each resource is +provisioned independently. Agents discover memories and credentials at runtime via environment variables or SDK calls. +Tags defined in \`agentcore.json\` flow through to deployed CloudFormation resources. ## Critical Invariants -1. **Schema-First Authority:** The \`.json\` files are the absolute source of truth. Do not attempt to modify agent - behavior by editing the generated CDK code in \`cdk/\`. -2. **Resource Identity:** The \`name\` field in the schema determines the CloudFormation Logical ID. - - **Renaming** an agent or target will **destroy and recreate** that resource. - - **Modifying** other fields (descriptions, config) will update the resource **in-place**. -3. **1:1 Validation:** The schema maps directly to valid CloudFormation. If your JSON conforms to the types in - \`.llm-context/\`, it will deploy successfully. -4. **Resource Removal:** To remove all resources, use \`agentcore remove all\`. To tear down deployed infrastructure, run - \`agentcore deploy\` after removal — it will detect the empty state and offer a teardown flow. +1. **Schema-First Authority:** The \`.json\` files are the source of truth. Do not modify agent behavior by editing + generated CDK code in \`cdk/\`. +2. **Resource Identity:** The \`name\` field determines the CloudFormation Logical ID. + - **Renaming** a resource will **destroy and recreate** it. + - **Modifying** other fields will update the resource **in-place**. +3. **Schema Validation:** If your JSON conforms to the types in \`.llm-context/\`, it will deploy successfully. Run + \`agentcore validate\` to check. +4. **Resource Removal:** Use \`agentcore remove\` to remove resources. Run \`agentcore deploy\` after removal to tear down + deployed infrastructure. ## Directory Structure \`\`\` -myNewProject/ -├── AGENTS.md # This file - AI coding assistant context -├── agentcore/ # AgentCore configuration directory +myProject/ +├── AGENTS.md # This file — AI coding assistant context +├── agentcore/ │ ├── agentcore.json # Main project config (AgentCoreProjectSpec) -│ ├── aws-targets.json # Deployment targets -│ ├── .llm-context/ # TypeScript type definitions for AI coding assistants -│ │ ├── README.md # Guide to using the schema files +│ ├── aws-targets.json # Deployment targets (account + region) +│ ├── .env.local # Secrets — API keys (gitignored) +│ ├── .llm-context/ # TypeScript type definitions for AI assistants +│ │ ├── README.md # Guide to using schema files │ │ ├── agentcore.ts # AgentCoreProjectSpec types -│ │ └── aws-targets.ts # AWS deployment target types -│ └── cdk/ # AWS CDK project for deployment -└── app/ # Application code (if agents were created) +│ │ ├── aws-targets.ts # AWS deployment target types +│ │ └── mcp.ts # Gateway and MCP tool types +│ └── cdk/ # AWS CDK project (@aws/agentcore-cdk L3 constructs) +├── app/ # Agent application code +└── evaluators/ # Custom evaluator code (if any) \`\`\` ## Schema Reference The \`agentcore/.llm-context/\` directory contains TypeScript type definitions optimized for AI coding assistants. Each -file maps to a JSON config file and includes validation constraints as comments. +file maps to a JSON config file and includes validation constraints as comments (\`@regex\`, \`@min\`, \`@max\`). -| JSON Config | Schema File | Root Type | -| ---------------------------- | --------------------------------------- | ----------------------- | -| \`agentcore/agentcore.json\` | \`agentcore/.llm-context/agentcore.ts\` | \`AgentCoreProjectSpec\` | -| \`agentcore/aws-targets.json\` | \`agentcore/.llm-context/aws-targets.ts\` | \`AWSDeploymentTarget[]\` | +| JSON Config | Schema File | Root Type | +| --- | --- | --- | +| \`agentcore/agentcore.json\` | \`agentcore/.llm-context/agentcore.ts\` | \`AgentCoreProjectSpec\` | +| \`agentcore/agentcore.json\` (gateways) | \`agentcore/.llm-context/mcp.ts\` | \`AgentCoreMcpSpec\` | +| \`agentcore/aws-targets.json\` | \`agentcore/.llm-context/aws-targets.ts\` | \`AwsDeploymentTarget[]\` | ### Key Types -- **AgentCoreProjectSpec**: Root project configuration with \`agents\`, \`memories\`, \`credentials\` arrays -- **AgentEnvSpec**: Agent configuration (runtime, entrypoint, code location) -- **Memory**: Memory resource with strategies and expiry -- **Credential**: API key credential provider +- **AgentCoreProjectSpec**: Root config with \`runtimes\`, \`memories\`, \`credentials\`, \`agentCoreGateways\`, \`evaluators\`, \`onlineEvalConfigs\`, \`policyEngines\` arrays +- **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode) +- **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry +- **Credential**: API key or OAuth credential provider +- **AgentCoreGateway**: MCP gateway with targets (Lambda, MCP server, OpenAPI, Smithy, API Gateway) +- **Evaluator**: LLM-as-a-Judge or code-based evaluator +- **OnlineEvalConfig**: Continuous evaluation pipeline bound to an agent ### Common Enum Values - **BuildType**: \`'CodeZip'\` | \`'Container'\` -- **NetworkMode**: \`'PUBLIC'\` -- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` | \`'PYTHON_3_14'\` +- **NetworkMode**: \`'PUBLIC'\` | \`'VPC'\` +- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` | \`'PYTHON_3_14'\` | \`'NODE_18'\` | \`'NODE_20'\` | \`'NODE_22'\` - **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` | \`'EPISODIC'\` +- **GatewayTargetType**: \`'lambda'\` | \`'mcpServer'\` | \`'openApiSchema'\` | \`'smithyModel'\` | \`'apiGateway'\` | \`'lambdaFunctionArn'\` +- **ModelProvider**: \`'Bedrock'\` | \`'Gemini'\` | \`'OpenAI'\` | \`'Anthropic'\` ### Build Types -- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime. -- **Container**: Agent code is built as a Docker container image. Requires a \`Dockerfile\` in the agent's \`codeLocation\` - directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR - repository, and the container URI is provided to the AgentCore Runtime. For local development (\`agentcore dev\`), the - container is built and run locally with volume-mounted hot-reload. +- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime. +- **Container**: Docker image built in CodeBuild (ARM64), pushed to a per-agent ECR repository. Requires a \`Dockerfile\` + in the agent's \`codeLocation\` directory. For local development (\`agentcore dev\`), the container is built and run + locally with volume-mounted hot-reload. ### Supported Frameworks (for template agents) -- **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini -- **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini -- **GoogleADK** - Gemini only -- **OpenAIAgents** - OpenAI only +- **Strands** — Bedrock, Anthropic, OpenAI, Gemini +- **LangChain/LangGraph** — Bedrock, Anthropic, OpenAI, Gemini +- **GoogleADK** — Gemini +- **OpenAI Agents** — OpenAI +- **Autogen** — Bedrock, Anthropic, OpenAI, Gemini +### Protocols -### Specific Context - -Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image) -deployment options are available. +- **HTTP** — Standard HTTP agent endpoint +- **MCP** — Model Context Protocol server +- **A2A** — Agent-to-Agent protocol (Google A2A) ## Deployment -The \`agentcore/cdk/\` subdirectory contains an AWS CDK node project. +Deployments are orchestrated through the CLI: -Deployments of this project are primarily intended to be orchestrated through the \`agentcore deploy\` command in the CLI. +\`\`\`bash +agentcore deploy # Synthesizes CDK and deploys to AWS +agentcore status # Shows deployment status +\`\`\` -Alternatively, the project can be deployed directly as a traditional CDK project: +Alternatively, deploy directly via CDK: \`\`\`bash cd agentcore/cdk npm install -npx cdk synth # Preview CloudFormation template -npx cdk deploy # Deploy to AWS +npx cdk synth +npx cdk deploy \`\`\` ## Editing Schemas @@ -4547,7 +4606,25 @@ When modifying JSON config files: 2. Check validation constraint comments (\`@regex\`, \`@min\`, \`@max\`) 3. Use exact enum values as string literals 4. Use CloudFormation-safe names (alphanumeric, start with letter) -5. Run \`agentcore validate\` command to verify changes. +5. Run \`agentcore validate\` to verify changes + +## CLI Commands + +| Command | Description | +| --- | --- | +| \`agentcore create\` | Create a new project | +| \`agentcore add \` | Add agent, memory, credential, gateway, evaluator, policy | +| \`agentcore remove \` | Remove a resource | +| \`agentcore dev\` | Run agent locally with hot-reload | +| \`agentcore deploy\` | Deploy to AWS | +| \`agentcore status\` | Show deployment status | +| \`agentcore invoke\` | Invoke agent (local or deployed) | +| \`agentcore logs\` | View agent logs | +| \`agentcore traces\` | View agent traces | +| \`agentcore eval\` | Run evaluations against an agent | +| \`agentcore package\` | Package agent artifacts | +| \`agentcore validate\` | Validate configuration | +| \`agentcore pause\` / \`resume\` | Pause or resume a deployed agent | " `; diff --git a/src/assets/agents/AGENTS.md b/src/assets/agents/AGENTS.md index dc50d5349..2153de014 100644 --- a/src/assets/agents/AGENTS.md +++ b/src/assets/agents/AGENTS.md @@ -2,103 +2,114 @@ This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application. -The `agentcore/` directory serves as a declarative model of an AgentCore project along with a concrete implementation -through the `agentcore/cdk/` project which is modeled to take the configs as input. The project uses a **flat resource -model** where agents, memories, and credentials are top-level arrays. +The `agentcore/` directory is a declarative model of the project. The `agentcore/cdk/` subdirectory uses the +`@aws/agentcore-cdk` L3 constructs to deploy the configuration to AWS. ## Mental Model -The project uses a **flat resource model**. Agents, memories, and credentials are independent top-level arrays in -`agentcore.json`. There is no binding or attachment between resources in the schema — each resource is provisioned -independently. To use a memory or credential from an agent, the application code discovers the resource at runtime -(e.g., via environment variables or SDK calls). Tags defined in `agentcore.json` flow through to deployed CloudFormation resources. +The project uses a **flat resource model**. Agents, memories, credentials, gateways, evaluators, and policies are +independent top-level arrays in `agentcore.json`. There is no binding between resources in the schema — each resource is +provisioned independently. Agents discover memories and credentials at runtime via environment variables or SDK calls. +Tags defined in `agentcore.json` flow through to deployed CloudFormation resources. ## Critical Invariants -1. **Schema-First Authority:** The `.json` files are the absolute source of truth. Do not attempt to modify agent - behavior by editing the generated CDK code in `cdk/`. -2. **Resource Identity:** The `name` field in the schema determines the CloudFormation Logical ID. - - **Renaming** an agent or target will **destroy and recreate** that resource. - - **Modifying** other fields (descriptions, config) will update the resource **in-place**. -3. **1:1 Validation:** The schema maps directly to valid CloudFormation. If your JSON conforms to the types in - `.llm-context/`, it will deploy successfully. -4. **Resource Removal:** To remove all resources, use `agentcore remove all`. To tear down deployed infrastructure, run - `agentcore deploy` after removal — it will detect the empty state and offer a teardown flow. +1. **Schema-First Authority:** The `.json` files are the source of truth. Do not modify agent behavior by editing + generated CDK code in `cdk/`. +2. **Resource Identity:** The `name` field determines the CloudFormation Logical ID. + - **Renaming** a resource will **destroy and recreate** it. + - **Modifying** other fields will update the resource **in-place**. +3. **Schema Validation:** If your JSON conforms to the types in `.llm-context/`, it will deploy successfully. Run + `agentcore validate` to check. +4. **Resource Removal:** Use `agentcore remove` to remove resources. Run `agentcore deploy` after removal to tear down + deployed infrastructure. ## Directory Structure ``` -myNewProject/ -├── AGENTS.md # This file - AI coding assistant context -├── agentcore/ # AgentCore configuration directory +myProject/ +├── AGENTS.md # This file — AI coding assistant context +├── agentcore/ │ ├── agentcore.json # Main project config (AgentCoreProjectSpec) -│ ├── aws-targets.json # Deployment targets -│ ├── .llm-context/ # TypeScript type definitions for AI coding assistants -│ │ ├── README.md # Guide to using the schema files +│ ├── aws-targets.json # Deployment targets (account + region) +│ ├── .env.local # Secrets — API keys (gitignored) +│ ├── .llm-context/ # TypeScript type definitions for AI assistants +│ │ ├── README.md # Guide to using schema files │ │ ├── agentcore.ts # AgentCoreProjectSpec types -│ │ └── aws-targets.ts # AWS deployment target types -│ └── cdk/ # AWS CDK project for deployment -└── app/ # Application code (if agents were created) +│ │ ├── aws-targets.ts # AWS deployment target types +│ │ └── mcp.ts # Gateway and MCP tool types +│ └── cdk/ # AWS CDK project (@aws/agentcore-cdk L3 constructs) +├── app/ # Agent application code +└── evaluators/ # Custom evaluator code (if any) ``` ## Schema Reference The `agentcore/.llm-context/` directory contains TypeScript type definitions optimized for AI coding assistants. Each -file maps to a JSON config file and includes validation constraints as comments. +file maps to a JSON config file and includes validation constraints as comments (`@regex`, `@min`, `@max`). -| JSON Config | Schema File | Root Type | -| ---------------------------- | --------------------------------------- | ----------------------- | -| `agentcore/agentcore.json` | `agentcore/.llm-context/agentcore.ts` | `AgentCoreProjectSpec` | -| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AWSDeploymentTarget[]` | +| JSON Config | Schema File | Root Type | +| --- | --- | --- | +| `agentcore/agentcore.json` | `agentcore/.llm-context/agentcore.ts` | `AgentCoreProjectSpec` | +| `agentcore/agentcore.json` (gateways) | `agentcore/.llm-context/mcp.ts` | `AgentCoreMcpSpec` | +| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AwsDeploymentTarget[]` | ### Key Types -- **AgentCoreProjectSpec**: Root project configuration with `agents`, `memories`, `credentials` arrays -- **AgentEnvSpec**: Agent configuration (runtime, entrypoint, code location) -- **Memory**: Memory resource with strategies and expiry -- **Credential**: API key credential provider +- **AgentCoreProjectSpec**: Root config with `runtimes`, `memories`, `credentials`, `agentCoreGateways`, `evaluators`, `onlineEvalConfigs`, `policyEngines` arrays +- **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode) +- **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry +- **Credential**: API key or OAuth credential provider +- **AgentCoreGateway**: MCP gateway with targets (Lambda, MCP server, OpenAPI, Smithy, API Gateway) +- **Evaluator**: LLM-as-a-Judge or code-based evaluator +- **OnlineEvalConfig**: Continuous evaluation pipeline bound to an agent ### Common Enum Values - **BuildType**: `'CodeZip'` | `'Container'` -- **NetworkMode**: `'PUBLIC'` -- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` +- **NetworkMode**: `'PUBLIC'` | `'VPC'` +- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'` - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'` +- **GatewayTargetType**: `'lambda'` | `'mcpServer'` | `'openApiSchema'` | `'smithyModel'` | `'apiGateway'` | `'lambdaFunctionArn'` +- **ModelProvider**: `'Bedrock'` | `'Gemini'` | `'OpenAI'` | `'Anthropic'` ### Build Types -- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime. -- **Container**: Agent code is built as a Docker container image. Requires a `Dockerfile` in the agent's `codeLocation` - directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR - repository, and the container URI is provided to the AgentCore Runtime. For local development (`agentcore dev`), the - container is built and run locally with volume-mounted hot-reload. +- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime. +- **Container**: Docker image built in CodeBuild (ARM64), pushed to a per-agent ECR repository. Requires a `Dockerfile` + in the agent's `codeLocation` directory. For local development (`agentcore dev`), the container is built and run + locally with volume-mounted hot-reload. ### Supported Frameworks (for template agents) -- **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini -- **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini -- **GoogleADK** - Gemini only -- **OpenAIAgents** - OpenAI only +- **Strands** — Bedrock, Anthropic, OpenAI, Gemini +- **LangChain/LangGraph** — Bedrock, Anthropic, OpenAI, Gemini +- **GoogleADK** — Gemini +- **OpenAI Agents** — OpenAI +- **Autogen** — Bedrock, Anthropic, OpenAI, Gemini +### Protocols -### Specific Context - -Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image) -deployment options are available. +- **HTTP** — Standard HTTP agent endpoint +- **MCP** — Model Context Protocol server +- **A2A** — Agent-to-Agent protocol (Google A2A) ## Deployment -The `agentcore/cdk/` subdirectory contains an AWS CDK node project. +Deployments are orchestrated through the CLI: -Deployments of this project are primarily intended to be orchestrated through the `agentcore deploy` command in the CLI. +```bash +agentcore deploy # Synthesizes CDK and deploys to AWS +agentcore status # Shows deployment status +``` -Alternatively, the project can be deployed directly as a traditional CDK project: +Alternatively, deploy directly via CDK: ```bash cd agentcore/cdk npm install -npx cdk synth # Preview CloudFormation template -npx cdk deploy # Deploy to AWS +npx cdk synth +npx cdk deploy ``` ## Editing Schemas @@ -109,4 +120,22 @@ When modifying JSON config files: 2. Check validation constraint comments (`@regex`, `@min`, `@max`) 3. Use exact enum values as string literals 4. Use CloudFormation-safe names (alphanumeric, start with letter) -5. Run `agentcore validate` command to verify changes. +5. Run `agentcore validate` to verify changes + +## CLI Commands + +| Command | Description | +| --- | --- | +| `agentcore create` | Create a new project | +| `agentcore add ` | Add agent, memory, credential, gateway, evaluator, policy | +| `agentcore remove ` | Remove a resource | +| `agentcore dev` | Run agent locally with hot-reload | +| `agentcore deploy` | Deploy to AWS | +| `agentcore status` | Show deployment status | +| `agentcore invoke` | Invoke agent (local or deployed) | +| `agentcore logs` | View agent logs | +| `agentcore traces` | View agent traces | +| `agentcore eval` | Run evaluations against an agent | +| `agentcore package` | Package agent artifacts | +| `agentcore validate` | Validate configuration | +| `agentcore pause` / `resume` | Pause or resume a deployed agent | diff --git a/src/schema/llm-compacted/README.md b/src/schema/llm-compacted/README.md index 400eb343e..b13c5a8dd 100644 --- a/src/schema/llm-compacted/README.md +++ b/src/schema/llm-compacted/README.md @@ -4,10 +4,11 @@ ## Files -| File | JSON Config | Purpose | -| ---------------- | ------------------ | ------------------------------------ | -| `agentcore.ts` | `agentcore.json` | Project and agent environment config | -| `aws-targets.ts` | `aws-targets.json` | Deployment targets | +| File | JSON Config | Purpose | +| ---------------- | ------------------ | ----------------------------------------- | +| `agentcore.ts` | `agentcore.json` | Project, agent, memory, credential config | +| `mcp.ts` | `agentcore.json` | Gateways, targets, MCP runtime tools | +| `aws-targets.ts` | `aws-targets.json` | Deployment targets (account + region) | ## Usage