feat: add schema to agent (#2440)

---------

Co-authored-by: Brandon Kiser <[email protected]>

Author: chaynabors

crates/chat-cli/src/cli/agent/mod.rs

@@ -120,6 +120,8 @@ pub enum AgentConfigError {
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 #[schemars(description = "An Agent is a declarative way of configuring a given instance of q chat.")]
 pub struct Agent {
+    #[serde(rename = "$schema", default = "default_schema")]
+    pub schema: String,
     /// Name of the agent
     pub name: String,
     /// This field is not model facing and is mostly here for users to discern between agents
@@ -166,6 +168,7 @@ pub struct Agent {
 impl Default for Agent {
     fn default() -> Self {
         Self {
+            schema: default_schema(),
             name: DEFAULT_AGENT_NAME.to_string(),
             description: Some("Default agent".to_string()),
             prompt: Default::default(),
@@ -766,6 +769,10 @@ async fn load_agents_from_entries(
     res
 }
 
+fn default_schema() -> String {
+    "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json".into()
+}
+
 #[cfg(test)]
 fn validate_agent_name(name: &str) -> eyre::Result<()> {
     // Check if name is empty

crates/chat-cli/src/cli/agent/root_command_args.rs

@@ -368,5 +368,15 @@ mod tests {
                 })
             })
         );
+        assert_parse!(
+            ["agent", "create", "-n", "some_agent", "--from", "some_old_agent"],
+            RootSubcommand::Agent(AgentArgs {
+                cmd: Some(AgentSubcommands::Create {
+                    name: "some_agent".to_string(),
+                    directory: None,
+                    from: Some("some_old_agent".to_string())
+                })
+            })
+        );
     }
 }

crates/chat-cli/src/cli/mcp.rs

@@ -550,7 +550,7 @@ mod tests {
     }
 
     #[test]
-    fn test_mcp_subcomman_add() {
+    fn test_mcp_subcommand_add() {
         assert_parse!(
             [
                 "mcp",

docs/agent-format.md

@@ -26,8 +26,6 @@ The `name` field specifies the name of the agent. This is used for identificatio
 }
 ```
 
-Note: While this field can be included in the configuration file, it will be overridden by the filename when the agent is loaded.
-
 ## Description Field
 
 The `description` field provides a description of what the agent does. This is primarily for human readability and helps users distinguish between different agents.

schemas/agent-v1.json

@@ -3,6 +3,21 @@
   "title": "Agent",
   "description": "An Agent is a declarative way of configuring a given instance of q chat.",
   "type": "object",
+  "definitions": {
+    "hookCommands": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "description": "The command to run when the hook is triggered",
+            "type": "string"
+          }
+        },
+        "required": ["command"]
+      }
+    }
+  },
   "properties": {
     "$schema": {
       "description": "The schema to use for validating the agent",
@@ -14,12 +29,18 @@
     },
     "description": {
       "description": "This field is not model facing and is mostly here for users to discern between agents",
-      "type": ["string", "null"],
+      "type": [
+        "string",
+        "null"
+      ],
       "default": null
     },
     "prompt": {
       "description": "The intention for this field is to provide high level context to the\nagent. This should be seen as the same category of context as a system prompt.",
-      "type": ["string", "null"],
+      "type": [
+        "string",
+        "null"
+      ],
       "default": null
     },
     "mcpServers": {
@@ -42,7 +63,10 @@
           },
           "env": {
             "description": "A list of environment variables to run the command with",
-            "type": ["object", "null"],
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             }
@@ -60,7 +84,9 @@
             "default": false
           }
         },
-        "required": ["command"]
+        "required": [
+          "command"
+        ]
       },
       "default": {}
     },
@@ -106,17 +132,12 @@
     "hooks": {
       "description": "Commands to run when a chat session is created",
       "type": "object",
-      "additionalProperties": {
-        "type": "array",
-        "items": {
-          "type": "object",
-          "properties": {
-            "command": {
-              "description": "The command to run when the hook is triggered",
-              "type": "string"
-            }
-          },
-          "required": ["command"]
+      "properties": {
+        "userPromptSubmit": {
+          "$ref": "#/definitions/hookCommands"
+        },
+        "agentSpawn": {
+          "$ref": "#/definitions/hookCommands"
         }
       },
       "default": {}
@@ -141,5 +162,7 @@
     }
   },
   "additionalProperties": false,
-  "required": ["name"]
+  "required": [
+    "name"
+  ]
 }