diff --git a/docs/commands.md b/docs/commands.md index 1777f8f31..e841186b8 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -52,18 +52,16 @@ Deploy infrastructure to AWS. ```bash agentcore deploy -agentcore deploy --target production agentcore deploy -y --progress # Auto-confirm with progress agentcore deploy -v --json # Verbose JSON output ``` -| Flag | Description | -| ----------------- | --------------------- | -| `--target ` | Deployment target | -| `-y, --yes` | Auto-confirm prompts | -| `--progress` | Real-time progress | -| `-v, --verbose` | Resource-level events | -| `--json` | JSON output | +| Flag | Description | +| --------------- | --------------------- | +| `-y, --yes` | Auto-confirm prompts | +| `--progress` | Real-time progress | +| `-v, --verbose` | Resource-level events | +| `--json` | JSON output | ### status @@ -72,14 +70,12 @@ Check deployment status. ```bash agentcore status agentcore status --agent MyAgent -agentcore status --target production ``` | Flag | Description | | ------------------------- | ------------------- | | `--agent ` | Specific agent | | `--agent-runtime-id ` | Specific runtime ID | -| `--target ` | Deployment target | ### validate @@ -169,26 +165,6 @@ agentcore add identity \ | `--api-key ` | API key value | | `--json` | JSON output | -### add target - -Add a deployment target. - -```bash -agentcore add target \ - --name production \ - --account 123456789012 \ - --region us-west-2 \ - --description "Production environment" -``` - -| Flag | Description | -| ---------------------- | -------------- | -| `--name ` | Target name | -| `--account ` | AWS account ID | -| `--region ` | AWS region | -| `--description ` | Description | -| `--json` | JSON output | - ### remove Remove resources from project. @@ -197,7 +173,6 @@ Remove resources from project. agentcore remove agent --name MyAgent --force agentcore remove memory --name SharedMemory agentcore remove identity --name OpenAI -agentcore remove target --name dev # Reset everything agentcore remove all --force @@ -241,7 +216,7 @@ Invoke local or deployed agents. ```bash agentcore invoke "What can you do?" agentcore invoke --prompt "Hello" --stream -agentcore invoke --agent MyAgent --target production +agentcore invoke --agent MyAgent agentcore invoke --session-id abc123 # Continue session agentcore invoke --new-session # Fresh session agentcore invoke --json # JSON output @@ -251,7 +226,6 @@ agentcore invoke --json # JSON output | ------------------- | ------------------------- | | `--prompt ` | Prompt text | | `--agent ` | Specific agent | -| `--target ` | Deployment target | | `--session-id ` | Continue specific session | | `--new-session` | Start fresh session | | `--stream` | Stream response | @@ -282,13 +256,8 @@ Check for CLI updates. ```bash agentcore update # Check and install -agentcore update --check # Check only ``` -| Flag | Description | -| ------------- | ------------------------ | -| `-c, --check` | Check without installing | - --- ## Common Patterns @@ -298,7 +267,7 @@ agentcore update --check # Check only ```bash # Validate and deploy with auto-confirm agentcore validate -agentcore deploy --target production -y --json +agentcore deploy -y --json ``` ### Scripted Project Setup @@ -307,8 +276,7 @@ agentcore deploy --target production -y --json agentcore create --name MyProject --defaults cd MyProject agentcore add memory --name SharedMemory --strategies SEMANTIC -agentcore add target --name dev --account 123456789012 --region us-west-2 -agentcore deploy --target dev -y +agentcore deploy -y ``` ### JSON Output for Automation diff --git a/docs/configuration.md b/docs/configuration.md index 739fa02fb..5eb571ac8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -99,12 +99,6 @@ Main project configuration using a **flat resource model**. Agents, memories, an - `PYTHON_3_12` - `PYTHON_3_13` -**Node.js:** - -- `NODE_18` -- `NODE_20` -- `NODE_22` - --- ## Memory Resource @@ -132,7 +126,6 @@ Main project configuration using a **flat resource model**. Agents, memories, an | `SEMANTIC` | Vector-based similarity search for relevant context | | `SUMMARIZATION` | Compressed conversation history | | `USER_PREFERENCE` | Store user-specific preferences and settings | -| `CUSTOM` | Custom strategy implementation | Strategy configuration: @@ -161,13 +154,14 @@ Strategy configuration: | `type` | Yes | Always `"ApiKeyCredentialProvider"` | | `name` | Yes | Credential name (3-255 chars) | -The actual API key is stored in `.env.local` for local development and in AWS Secrets Manager for deployed environments. +The actual API key is stored in `.env.local` for local development and in AgentCore Identity service for deployed +environments. --- ## aws-targets.json -Array of deployment targets. +Deployment target ```json [ @@ -176,12 +170,6 @@ Array of deployment targets. "description": "Production (us-west-2)", "account": "123456789012", "region": "us-west-2" - }, - { - "name": "dev", - "description": "Development (us-east-1)", - "account": "123456789012", - "region": "us-east-1" } ] ``` @@ -205,9 +193,9 @@ current list. API keys for local development. This file is gitignored. ```bash -OPENAI_API_KEY=sk-... -ANTHROPIC_API_KEY=sk-ant-... -GOOGLE_API_KEY=AI... +AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-... +AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-... +AGENTCORE_CREDENTIAL_{projectName}GEMINI=... ``` Environment variable names should match the credential names in your configuration. diff --git a/docs/frameworks.md b/docs/frameworks.md index fea855235..817562ed8 100644 --- a/docs/frameworks.md +++ b/docs/frameworks.md @@ -93,7 +93,7 @@ agentcore add agent \ 1. **Entrypoint**: Your code must expose an HTTP endpoint that accepts agent invocation requests 2. **Code location**: Directory containing your agent code -3. **Language**: Python, TypeScript, or Other (requires container build) +3. **Language**: Python ### BYO Options @@ -102,7 +102,7 @@ agentcore add agent \ | `--type byo` | Use BYO mode (required) | | `--code-location ` | Directory containing your agent code | | `--entrypoint ` | Entry file (e.g., `main.py` or `index.ts`) | -| `--language ` | `Python`, `TypeScript`, or `Other` | +| `--language ` | `Python` | ## Framework Comparison @@ -112,23 +112,3 @@ agentcore add agent \ | AWS Bedrock native | Yes | No | No | No | | Tool ecosystem | Growing | Extensive | Moderate | Moderate | | Memory integration | Native | Via libs | Via libs | Via libs | - -## Changing Frameworks - -To switch frameworks for an existing project, you'll need to: - -1. Create a new agent with the desired framework: - - ```bash - agentcore add agent --name NewAgent --framework LangChain_LangGraph - ``` - -2. Migrate your agent logic to the new framework's structure - -3. Remove the old agent (optional): - ```bash - agentcore remove agent --name OldAgent - ``` - -Agent framework and model provider are only used during template generation. The generated code can be modified to use -any compatible SDK or model. diff --git a/docs/local-development.md b/docs/local-development.md index 8ff302601..9a8ba1d02 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -51,13 +51,11 @@ The dev server automatically: For non-Bedrock providers, add keys to `agentcore/.env.local`: ```bash -AGENTCORE_IDENTITY_OPENAI=sk-... -AGENTCORE_IDENTITY_ANTHROPIC=sk-ant-... -AGENTCORE_IDENTITY_GEMINI=AI... +AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-... +AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-... +AGENTCORE_CREDENTIAL_{projectName}GEMINI=... ``` -The variable names must match `envVarName` in your identity providers. - ## Debugging ### Log Files @@ -92,9 +90,6 @@ cd app/MyAgent uv sync ``` -**API key not found:** Check that `.env.local` has the correct variable name matching your identity provider's -`envVarName`. - ## Hot Reload The dev server watches for file changes and automatically reloads. Edit your agent code and the changes take effect @@ -102,10 +97,10 @@ immediately. ## Dev vs Deployed Behavior -| Aspect | Local Dev | Deployed | -| ---------- | ------------- | ------------------------ | -| API Keys | `.env.local` | AWS Secrets Manager | -| Memory | Not available | AgentCore Memory service | -| Networking | localhost | VPC/Public | +| Aspect | Local Dev | Deployed | +| ---------- | ------------- | -------------------------- | +| API Keys | `.env.local` | AgentCore Identity service | +| Memory | Not available | AgentCore Memory service | +| Networking | localhost | Public | Memory requires deployment to test fully. For local testing, you can mock these dependencies in your agent code. diff --git a/docs/memory.md b/docs/memory.md index 533a95a43..580dc0703 100644 --- a/docs/memory.md +++ b/docs/memory.md @@ -62,12 +62,12 @@ agentcore deploy ### Adding Memory to an Agent Without Memory -If you created an agent without memory and want to add it later: +If you created an Strands agent without memory and want to integrate it with your agent later: 1. Add a memory to your project: ```bash - agentcore add memory --name MyMemory --strategies SEMANTIC + agentcore add memory --name MyMemory --strategies SEMANTIC,SUMMARIZATION ``` 2. Create the `memory/` directory in your agent: @@ -93,7 +93,7 @@ If you created an agent without memory and want to add it later: retrieval_config = { f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5), - f"/users/{actor_id}/preferences": RetrievalConfig(top_k=3, relevance_score=0.5), + f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5) } return AgentCoreMemorySessionManager( @@ -109,25 +109,44 @@ If you created an agent without memory and want to add it later: 4. Update `main.py` to use the session manager: - ```python - from memory.session import get_memory_session_manager - - @app.entrypoint - async def invoke(payload, context): - session_id = getattr(context, 'session_id', 'default-session') - user_id = getattr(context, 'user_id', 'default-user') - session_manager = get_memory_session_manager(session_id, user_id) - - agent = Agent( - model=load_model(), - session_manager=session_manager, # Add this line - ... - ) - ``` +```python +from memory.session import get_memory_session_manager + +def agent_factory(): + cache = {} + def get_or_create_agent(session_id, user_id): + key = f"{session_id}/{user_id}" + if key not in cache: + # Create an agent for the given session_id and user_id + cache[key] = Agent( + model=load_model(), + session_manager=get_memory_session_manager(session_id, user_id), + system_prompt=""" + You are a helpful assistant. Use tools when appropriate. + """, + tools=tools+[mcp_client] + ) + return cache[key] + return get_or_create_agent +get_or_create_agent = agent_factory() + +@app.entrypoint +async def invoke(payload, context): + session_id = getattr(context, 'session_id', 'default-session') + user_id = getattr(context, 'user_id', 'default-user') + agent = get_or_create_agent(session_id, user_id) + session_manager = get_memory_session_manager(session_id, user_id) + + agent = Agent( + model=load_model(), + session_manager=session_manager, # Add this line + ... + ) +``` 5. Deploy: ```bash - agentcore deploy + agentcore deploy ``` ## Memory Strategies @@ -137,7 +156,6 @@ If you created an agent without memory and want to add it later: | `SEMANTIC` | Vector-based similarity search for relevant context | | `SUMMARIZATION` | Compressed conversation history | | `USER_PREFERENCE` | Store user-specific preferences and settings | -| `CUSTOM` | Custom strategy implementation | You can combine multiple strategies: diff --git a/src/assets/README.md b/src/assets/README.md index 58cd13cc2..d0210021d 100644 --- a/src/assets/README.md +++ b/src/assets/README.md @@ -6,21 +6,21 @@ This project was created with the [AgentCore CLI](https://github.com/aws/agentco ``` . -├── agentcore/ # AgentCore configuration directory -│ ├── agentcore.json # Main project config (agents, memories, credentials) +my-project/ +├── agentcore/ +│ ├── .env.local # API keys (gitignored) +│ ├── agentcore.json # Resource specifications │ ├── aws-targets.json # Deployment targets -│ └── cdk/ # AWS CDK project for deployment -├── app/ # Application code (if agents were created) -└── AGENTS.md # AI coding assistant context +│ └── cdk/ # CDK infrastructure +├── app/ # Application code ``` ## Getting Started ### Prerequisites -- [Node.js](https://nodejs.org/) (v18 or later) -- [AWS CLI](https://aws.amazon.com/cli/) configured with credentials -- [AgentCore CLI](https://github.com/awslabs/amazon-bedrock-agentcore) installed globally +- **Node.js** 20.x or later +- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/)) ### Development @@ -62,7 +62,6 @@ The project uses a **flat resource model** where agents, memories, and credentia | `agentcore remove` | Remove resources | | `agentcore dev` | Run agent locally | | `agentcore deploy` | Deploy to AWS | -| `agentcore destroy` | Tear down deployed resources | | `agentcore status` | Show deployment status | | `agentcore invoke` | Invoke agent (local or deployed) | | `agentcore package` | Package agent artifacts | diff --git a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap index a30735f0e..249b760c6 100644 --- a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap +++ b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap @@ -2686,21 +2686,21 @@ This project was created with the [AgentCore CLI](https://github.com/aws/agentco \`\`\` . -├── agentcore/ # AgentCore configuration directory -│ ├── agentcore.json # Main project config (agents, memories, credentials) +my-project/ +├── agentcore/ +│ ├── .env.local # API keys (gitignored) +│ ├── agentcore.json # Resource specifications │ ├── aws-targets.json # Deployment targets -│ └── cdk/ # AWS CDK project for deployment -├── app/ # Application code (if agents were created) -└── AGENTS.md # AI coding assistant context +│ └── cdk/ # CDK infrastructure +├── app/ # Application code \`\`\` ## Getting Started ### Prerequisites -- [Node.js](https://nodejs.org/) (v18 or later) -- [AWS CLI](https://aws.amazon.com/cli/) configured with credentials -- [AgentCore CLI](https://github.com/awslabs/amazon-bedrock-agentcore) installed globally +- **Node.js** 20.x or later +- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/)) ### Development @@ -2742,7 +2742,6 @@ The project uses a **flat resource model** where agents, memories, and credentia | \`agentcore remove\` | Remove resources | | \`agentcore dev\` | Run agent locally | | \`agentcore deploy\` | Deploy to AWS | -| \`agentcore destroy\` | Tear down deployed resources | | \`agentcore status\` | Show deployment status | | \`agentcore invoke\` | Invoke agent (local or deployed) | | \`agentcore package\` | Package agent artifacts | @@ -2772,12 +2771,10 @@ model** where agents, memories, and credentials are top-level arrays. ## Mental Model -A good mental model for how this project works is a directed graph. We have a set of nodes: agents, memories, -credentials, and future resources supported. There are rules about which nodes can connect to others in what direction. - -Wiring nodes creates an infrastructure and trust relationship but is not enough to complete end-to-end functionality. -For example, to use a memory from an agent, the application code needs to read the memory ID from an environment -variable and construct the appropriate SDK calls. +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). ## Critical Invariants @@ -2788,6 +2785,8 @@ variable and construct the appropriate SDK calls. - **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. ## Directory Structure @@ -2824,9 +2823,9 @@ file maps to a JSON config file and includes validation constraints as comments. ### Common Enum Values -- **BuildType**: \`'CodeZip'\` | \`'Container'\` -- **NetworkMode**: \`'PUBLIC'\` | \`'PRIVATE'\` -- **RuntimeVersion**: \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` | \`'NODE_18'\` | \`'NODE_20'\` | \`'NODE_22'\` +- **BuildType**: \`'CodeZip'\` +- **NetworkMode**: \`'PUBLIC'\` +- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` - **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` ### Supported Frameworks (for template agents) @@ -2839,7 +2838,6 @@ file maps to a JSON config file and includes validation constraints as comments. ### Specific Context Directory pathing to local projects is required for runtimes. Only Python offers a zip based direct code deploy option. -All other programming languages are required to be containerized and provide a path to a \`Dockerfile\` definition. ## Deployment @@ -2856,8 +2854,6 @@ npx cdk synth # Preview CloudFormation template npx cdk deploy # Deploy to AWS \`\`\` -Both CLI and direct deployment have the same source of truth and are safe to be substituted interchangeably. - ## Editing Schemas When modifying JSON config files: diff --git a/src/assets/agents/AGENTS.md b/src/assets/agents/AGENTS.md index 1a8ee68e1..35f1b7d24 100644 --- a/src/assets/agents/AGENTS.md +++ b/src/assets/agents/AGENTS.md @@ -8,12 +8,10 @@ model** where agents, memories, and credentials are top-level arrays. ## Mental Model -A good mental model for how this project works is a directed graph. We have a set of nodes: agents, memories, -credentials, and future resources supported. There are rules about which nodes can connect to others in what direction. - -Wiring nodes creates an infrastructure and trust relationship but is not enough to complete end-to-end functionality. -For example, to use a memory from an agent, the application code needs to read the memory ID from an environment -variable and construct the appropriate SDK calls. +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). ## Critical Invariants @@ -24,6 +22,8 @@ variable and construct the appropriate SDK calls. - **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. ## Directory Structure @@ -60,9 +60,9 @@ file maps to a JSON config file and includes validation constraints as comments. ### Common Enum Values -- **BuildType**: `'CodeZip'` | `'Container'` -- **NetworkMode**: `'PUBLIC'` | `'PRIVATE'` -- **RuntimeVersion**: `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'` +- **BuildType**: `'CodeZip'` +- **NetworkMode**: `'PUBLIC'` +- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` ### Supported Frameworks (for template agents) @@ -75,7 +75,6 @@ file maps to a JSON config file and includes validation constraints as comments. ### Specific Context Directory pathing to local projects is required for runtimes. Only Python offers a zip based direct code deploy option. -All other programming languages are required to be containerized and provide a path to a `Dockerfile` definition. ## Deployment @@ -92,8 +91,6 @@ npx cdk synth # Preview CloudFormation template npx cdk deploy # Deploy to AWS ``` -Both CLI and direct deployment have the same source of truth and are safe to be substituted interchangeably. - ## Editing Schemas When modifying JSON config files: