feat(schema): add description field to agent configuration

docs/commands.md

@@ -68,6 +68,7 @@ agentcore create \
 | Flag                      | Description                                                                                                    |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `--name <name>`           | Project name (alphanumeric, starts with letter, max 23 chars)                                                  |
+| `--description <desc>`    | Description for the agent created with the project (max 4096 chars)                                            |
 | `--defaults`              | Use defaults (Python, Strands, Bedrock, no memory)                                                             |
 | `--no-agent`              | Skip agent creation                                                                                            |
 | `--type <type>`           | `create` (default) or `import`                                                                                 |
@@ -196,6 +197,7 @@ agentcore add agent \
 | Flag                      | Description                                                                                                                       |
 | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | `--name <name>`           | Agent name (alphanumeric + underscores, starts with letter, max 48 chars)                                                         |
+| `--description <desc>`    | Agent description (max 4096 chars)                                                                                                |
 | `--type <type>`           | `create` (default), `byo`, or `import`                                                                                            |
 | `--build <type>`          | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md))                                                  |
 | `--language <lang>`       | `Python` (create); `Python`, `TypeScript`, `Other` (BYO)                                                                          |

docs/configuration.md

@@ -184,6 +184,7 @@ on the next deployment.
 {
   "type": "AgentCoreRuntime",
   "name": "MyAgent",
+  "description": "A helpful assistant agent",
   "build": "CodeZip",
   "entrypoint": "main.py",
   "codeLocation": "app/MyAgent/",
@@ -200,6 +201,7 @@ on the next deployment.
 | ----------------- | -------- | -------------------------------------------------- |
 | `type`            | Yes      | Always `"AgentCoreRuntime"`                        |
 | `name`            | Yes      | Agent name (1-48 chars, alphanumeric + underscore) |
+| `description`     | No       | Agent description (max 4096 chars)                 |
 | `build`           | Yes      | `"CodeZip"` or `"Container"`                       |
 | `entrypoint`      | Yes      | Entry file (e.g., `main.py` or `main.py:handler`)  |
 | `codeLocation`    | Yes      | Directory containing agent code                    |

schemas/agentcore.schema.v1.json

@@ -47,6 +47,11 @@
             "maxLength": 48,
             "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,47}$"
           },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          },
           "build": {
             "type": "string",
             "enum": ["CodeZip", "Container"]

src/cli/commands/add/types.ts

@@ -12,6 +12,7 @@ import type { VpcOptions } from '../shared/vpc-utils';
 // Agent types
 export interface AddAgentOptions extends VpcOptions {
   name?: string;
+  description?: string;
   type?: 'create' | 'byo' | 'import';
   build?: string;
   language?: TargetLanguage;

src/cli/commands/create/action.ts

@@ -106,6 +106,7 @@ type MemoryOption = 'none' | 'shortTerm' | 'longAndShortTerm';
 
 export interface CreateWithAgentOptions {
   name: string;
+  description?: string;
   cwd: string;
   type?: 'create' | 'import';
   buildType?: BuildType;
@@ -132,6 +133,7 @@ export interface CreateWithAgentOptions {
 export async function createProjectWithAgent(options: CreateWithAgentOptions): Promise<CreateResult> {
   const {
     name,
+    description,
     cwd,
     buildType,
     language,
@@ -176,6 +178,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
       onProgress?.('Import agent from Bedrock', 'start');
       const importResult = await executeImportAgent({
         name,
+        description,
         framework: framework ?? 'Strands',
         memory,
         bedrockRegion: options.region,
@@ -212,6 +215,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
 
     const generateConfig = {
       projectName: agentName,
+      description,
       buildType: buildType ?? ('CodeZip' as BuildType),
       sdk: resolvedFramework,
       modelProvider: resolvedModelProvider,

src/cli/commands/create/command.tsx

@@ -122,6 +122,7 @@ async function handleCreateCLI(options: CreateOptions): Promise<void> {
     ? await createProject({ name: options.name!, cwd, skipGit: options.skipGit, onProgress })
     : await createProjectWithAgent({
         name: options.name!,
+        description: options.description,
         cwd,
         type: options.type as 'create' | 'import' | undefined,
         buildType: (options.build as BuildType) ?? 'CodeZip',
@@ -160,6 +161,7 @@ export const registerCreate = (program: Command) => {
     .command('create')
     .description(COMMAND_DESCRIPTIONS.create)
     .option('--name <name>', 'Project name (start with letter, alphanumeric only, max 23 chars) [non-interactive]')
+    .option('--description <description>', 'Agent description (max 4096 chars) [non-interactive]')
     .option('--no-agent', 'Skip agent creation [non-interactive]')
     .option('--defaults', 'Use defaults (Python, Strands, Bedrock, no memory) [non-interactive]')
     .option('--build <type>', 'Build type: CodeZip or Container (default: CodeZip) [non-interactive]')

src/cli/commands/create/types.ts

@@ -2,6 +2,7 @@ import type { VpcOptions } from '../shared/vpc-utils';
 
 export interface CreateOptions extends VpcOptions {
   name?: string;
+  description?: string;
   agent?: boolean;
   defaults?: boolean;
   type?: string;

src/cli/operations/agent/generate/schema-mapper.ts

@@ -114,6 +114,7 @@ export function mapGenerateConfigToAgent(config: GenerateConfig): AgentEnvSpec {
 
   return {
     name: config.projectName,
+    ...(config.description && { description: config.description }),
     build: config.buildType ?? 'CodeZip',
     entrypoint: DEFAULT_PYTHON_ENTRYPOINT as FilePath,
     codeLocation: codeLocation as DirectoryPath,

src/cli/operations/agent/import/index.ts

@@ -21,6 +21,7 @@ import { dirname, join } from 'path';
 
 export interface ExecuteImportAgentParams {
   name: string;
+  description?: string;
   framework: SDKFramework;
   memory: MemoryOption;
   bedrockRegion: string;
@@ -38,6 +39,7 @@ export async function executeImportAgent(
 ): Promise<AddResult<{ agentName: string; agentPath: string }>> {
   const {
     name,
+    description,
     framework,
     memory,
     bedrockRegion,
@@ -88,6 +90,7 @@ export async function executeImportAgent(
     // 5. Write agent to project config (reuse existing write-agent-to-project)
     const generateConfig = {
       projectName: name,
+      description,
       buildType: 'CodeZip' as const,
       sdk: framework,
       modelProvider: 'Bedrock' as const,

src/cli/primitives/AgentPrimitive.tsx

@@ -43,6 +43,7 @@ import { dirname, join } from 'path';
  */
 export interface AddAgentOptions extends VpcOptions {
   name: string;
+  description?: string;
   type: 'create' | 'byo' | 'import';
   buildType: BuildType;
   language: TargetLanguage;
@@ -200,6 +201,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
         '--name <name>',
         'Agent name (start with letter, alphanumeric + underscores, max 48 chars) [non-interactive]'
       )
+      .option('--description <description>', 'Agent description (max 4096 chars) [non-interactive]')
       .option('--type <type>', 'Agent type: create, byo, or import [non-interactive]', 'create')
       .option('--build <type>', 'Build type: CodeZip or Container (default: CodeZip) [non-interactive]')
       .option('--language <lang>', 'Language: Python (create), or Python/TypeScript/Other (BYO) [non-interactive]')
@@ -260,6 +262,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
 
           const result = await this.add({
             name: cliOptions.name!,
+            description: cliOptions.description,
             type: cliOptions.type ?? 'create',
             buildType: (cliOptions.build as BuildType) ?? 'CodeZip',
             language: cliOptions.language!,
@@ -343,6 +346,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
 
     const generateConfig: GenerateConfig = {
       projectName: options.name,
+      description: options.description,
       buildType: options.buildType,
       sdk: options.framework,
       modelProvider: options.modelProvider,
@@ -442,6 +446,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
   ): Promise<AddResult<{ agentName: string; agentPath?: string }>> {
     return executeImportAgent({
       name: options.name,
+      description: options.description,
       framework: options.framework,
       memory: options.memory ?? 'none',
       bedrockRegion: options.bedrockRegion!,
@@ -507,6 +512,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
 
     const agent: AgentEnvSpec = {
       name: options.name,
+      ...(options.description && { description: options.description }),
       build: options.buildType,
       entrypoint: (options.entrypoint ?? 'main.py') as FilePath,
       codeLocation: codeLocation as DirectoryPath,

src/cli/tui/screens/generate/types.ts

@@ -37,6 +37,7 @@ export type { BuildType, ModelProvider, ProtocolMode, SDKFramework, TargetLangua
 
 export interface GenerateConfig {
   projectName: string;
+  description?: string;
   buildType: BuildType;
   protocol: ProtocolMode;
   sdk: SDKFramework;

src/schema/schemas/agent-env.ts

@@ -178,6 +178,7 @@ export type LifecycleConfiguration = z.infer<typeof LifecycleConfigurationSchema
 export const AgentEnvSpecSchema = z
   .object({
     name: AgentNameSchema,
+    description: z.string().min(1).max(4096).optional(),
     build: BuildTypeSchema,
     entrypoint: EntrypointSchema,
     codeLocation: DirectoryPathSchema,