agent-claw: automated task changes
This commit is contained in:
daniel
141
agentclaw/AGENTS.md
Normal file
141
agentclaw/AGENTS.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# AgentCore Project
|
||||
|
||||
This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application.
|
||||
|
||||
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, 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 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
|
||||
|
||||
```
|
||||
myProject/
|
||||
├── AGENTS.md # This file — AI coding assistant context
|
||||
├── agentcore/
|
||||
│ ├── agentcore.json # Main project config (AgentCoreProjectSpec)
|
||||
│ ├── 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
|
||||
│ │ └── 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 (`@regex`, `@min`, `@max`).
|
||||
|
||||
| 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 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'` | `'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 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** — Bedrock, Anthropic, OpenAI, Gemini
|
||||
- **LangChain/LangGraph** — Bedrock, Anthropic, OpenAI, Gemini
|
||||
- **GoogleADK** — Gemini
|
||||
- **OpenAI Agents** — OpenAI
|
||||
- **Autogen** — Bedrock, Anthropic, OpenAI, Gemini
|
||||
|
||||
### Protocols
|
||||
|
||||
- **HTTP** — Standard HTTP agent endpoint
|
||||
- **MCP** — Model Context Protocol server
|
||||
- **A2A** — Agent-to-Agent protocol (Google A2A)
|
||||
|
||||
## Deployment
|
||||
|
||||
Deployments are orchestrated through the CLI:
|
||||
|
||||
```bash
|
||||
agentcore deploy # Synthesizes CDK and deploys to AWS
|
||||
agentcore status # Shows deployment status
|
||||
```
|
||||
|
||||
Alternatively, deploy directly via CDK:
|
||||
|
||||
```bash
|
||||
cd agentcore/cdk
|
||||
npm install
|
||||
npx cdk synth
|
||||
npx cdk deploy
|
||||
```
|
||||
|
||||
## Editing Schemas
|
||||
|
||||
When modifying JSON config files:
|
||||
|
||||
1. Read the corresponding `agentcore/.llm-context/*.ts` file for type definitions
|
||||
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` to verify changes
|
||||
|
||||
## CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `agentcore create` | Create a new project |
|
||||
| `agentcore add <resource>` | Add agent, memory, credential, gateway, evaluator, policy |
|
||||
| `agentcore remove <resource>` | 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 |
|
||||
Reference in New Issue
Block a user