Compile-time error when forgetting the agent_implementation annotation

sdks/rust/AGENTS.md

@@ -124,6 +124,11 @@ impl MyAgent for MyAgentImpl {
 }
 ```
 
+Every implementation of an `#[agent_definition]` trait must be annotated with
+`#[agent_implementation]`, including test or mock implementations. If the
+attribute is forgotten, the compiler reports a missing hidden trait item named
+`agent_implementation_annotation`; add `#[agent_implementation]` to the impl.
+
 ## Integration with Main Repository
 
 This SDK is part of the main Golem repository but is **not built by `cargo make build`**. When changes affect core functionality, test with the full Golem test suite:

sdks/rust/README.md

@@ -10,3 +10,12 @@ the [transaction API](https://learn.golem.cloud/docs/transaction-api).
 ## golem-rust-macro
 
 The `golem-rust-macro` crate contains Rust derivation macros for working with Golem's `ValueAndType` types.
+
+## Agent implementations
+
+Traits annotated with `#[agent_definition]` must be implemented with
+`#[agent_implementation]`. A plain `impl AgentTrait for Type` now fails during
+`cargo check` with a missing hidden item named
+`agent_implementation_annotation`, which points to the forgotten annotation.
+The post-build `discover-agent-types` check remains the fallback for detecting
+agent definitions that have no implementation anywhere.

sdks/rust/golem-rust-macro/src/agentic/agent_definition_impl.rs

@@ -105,10 +105,17 @@ pub fn agent_definition_impl(attrs: TokenStream, item: TokenStream) -> TokenStre
 
             let load_snapshot_item = get_load_snapshot_item();
             let save_snapshot_item = get_save_snapshot_item();
+            let agent_type_name_item =
+                get_agent_type_name_item(&agent_definition_trait.ident.to_string());
+            let agent_implementation_annotation_item = get_agent_implementation_annotation_item();
 
             agent_definition_trait.items.push(load_snapshot_item);
             agent_definition_trait.items.push(save_snapshot_item);
             agent_definition_trait.items.push(registration_function);
+            agent_definition_trait.items.push(agent_type_name_item);
+            agent_definition_trait
+                .items
+                .push(agent_implementation_annotation_item);
 
             AgentConfigAttrRemover.visit_item_trait_mut(&mut agent_definition_trait);
 
@@ -141,6 +148,22 @@ fn get_save_snapshot_item() -> syn::TraitItem {
     }
 }
 
+fn get_agent_implementation_annotation_item() -> syn::TraitItem {
+    syn::parse_quote! {
+        #[doc(hidden)]
+        fn agent_implementation_annotation() where Self: Sized;
+    }
+}
+
+fn get_agent_type_name_item(agent_type_name: &str) -> syn::TraitItem {
+    syn::parse_quote! {
+        #[doc(hidden)]
+        fn __golem_agent_type_name() -> &'static str where Self: Sized {
+            #agent_type_name
+        }
+    }
+}
+
 struct AgentTypeWithRemoteClient {
     agent_type: proc_macro2::TokenStream,
     remote_client: proc_macro2::TokenStream,