fix(sdk): enforce UUID agent IDs (#9)

* fix(sdk): enforce UUID agent IDs

Validate agent_id as UUID in SDK (fail fast) and remove UUID5 fallback so server conflicts surface. Update docs/examples/tests/UI fixtures to use UUIDs and add validation test.

* fix(tests): avoid init agent UUID conflicts

Use unique init agent names in SDK integration tests and let ruff normalize import order after UUID validation changes.

* test(sdk): add UUID validation coverage

Add unit and behavioral tests for UUID validation helpers, fail-fast SDK agent_id handling, and init() conflict surfacing to improve coverage of the new UUID enforcement.

* Fix ui ci

Author: lan17

docs/REFERENCE.md

@@ -501,7 +501,7 @@ import agent_control
 
 agent_control.init(
     agent_name="my-agent",           # Required: human-readable name
-    agent_id="my-agent-v1",          # Required: unique identifier
+    agent_id="550e8400-e29b-41d4-a716-446655440000",  # Required: UUID
     server_url="http://localhost:8000",  # Optional: defaults to env var
     steps=[                          # Optional: register available steps
         {

examples/README.md

@@ -92,7 +92,10 @@ import agent_control
 from agent_control import control, ControlViolationError
 
 # Initialize agent (connects to server, loads policy)
-agent_control.init(agent_name="my-bot", agent_id="bot-123")
+agent_control.init(
+    agent_name="my-bot",
+    agent_id="550e8400-e29b-41d4-a716-446655440000",
+)
 
 # Apply the agent's assigned policy
 @control()

examples/agent_control_demo/demo_agent.py

@@ -44,7 +44,7 @@
 
 # Configuration
 AGENT_NAME = "demo-chatbot"
-AGENT_ID = "demo-chatbot-v1"
+AGENT_ID = "672e50df-af4c-429f-965a-3d7f8262302f"
 SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
 
 
@@ -258,4 +258,3 @@ async def run_demo():
 
 if __name__ == "__main__":
     asyncio.run(run_demo())
-

examples/agent_control_demo/setup_controls.py

@@ -34,7 +34,7 @@
 
 # Configuration
 AGENT_NAME = "demo-chatbot"
-AGENT_ID = "demo-chatbot-v1"
+AGENT_ID = "672e50df-af4c-429f-965a-3d7f8262302f"
 SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
 
 
@@ -44,9 +44,8 @@ async def create_agent(client: AgentControlClient) -> str:
     print("STEP 1: Creating Agent")
     print("=" * 60)
 
-    # Generate a deterministic UUID from the agent ID
-    import uuid
-    agent_uuid = uuid.uuid5(uuid.NAMESPACE_DNS, AGENT_ID)
+    # Use the provided UUID for the agent
+    agent_uuid = UUID(AGENT_ID)
 
     try:
         response = await client.http_client.post(
@@ -440,9 +439,8 @@ async def main():
             print("  cd server && make run")
             return
 
-        # Generate agent UUID
-        import uuid
-        agent_uuid = str(uuid.uuid5(uuid.NAMESPACE_DNS, AGENT_ID))
+        # Use the provided UUID for verification
+        agent_uuid = AGENT_ID
 
         # If verify-only mode, just run verification
         if args.verify_only:

examples/agent_control_demo/update_controls.py

@@ -19,15 +19,13 @@
 import asyncio
 import os
 import sys
-import uuid
-
 # Add the SDK to path for development
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../../sdks/python/src"))
 
 from agent_control import AgentControlClient
 
 # Configuration
-AGENT_ID = "demo-chatbot-v1"
+AGENT_ID = "672e50df-af4c-429f-965a-3d7f8262302f"
 SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
 
 
@@ -156,8 +154,8 @@ async def main():
     parser.add_argument("--status", action="store_true", help="Show current status")
     args = parser.parse_args()
 
-    # Generate agent UUID
-    agent_uuid = str(uuid.uuid5(uuid.NAMESPACE_DNS, AGENT_ID))
+    # Use the provided UUID
+    agent_uuid = AGENT_ID
 
     print("\n" + "=" * 60)
     print("AGENT CONTROL DEMO: Update Controls")

examples/crewai/content_agent_protection.py

@@ -45,7 +45,7 @@
 # It's a dependency of agent_control so should be available
 
 # --- Configuration ---
-AGENT_ID = "support-crew-demo"
+AGENT_ID = "989d84f0-9afe-4fb2-9e9e-e9d076271e29"
 AGENT_NAME = "Customer Support Crew"
 AGENT_DESCRIPTION = "Customer support crew with PII protection and access controls"
 

examples/crewai/setup_content_controls.py

@@ -10,19 +10,19 @@
 
 import asyncio
 import os
-import uuid
+from uuid import UUID
 
 from agent_control import Agent, AgentControlClient, agents, controls, policies
 
-AGENT_ID = "support-crew-demo"
+AGENT_ID = "989d84f0-9afe-4fb2-9e9e-e9d076271e29"
 SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
 
 
 async def setup_content_controls():
     """Create PII protection and unauthorized access controls, policy, and assign to agent."""
     async with AgentControlClient(base_url=SERVER_URL) as client:
         # 1. Register Agent
-        agent_uuid = uuid.uuid5(uuid.NAMESPACE_DNS, AGENT_ID)
+        agent_uuid = UUID(AGENT_ID)
 
         agent = Agent(
             agent_id=agent_uuid,

examples/customer_support_agent/README.md

@@ -161,7 +161,7 @@ import agent_control
 
 agent_control.init(
     agent_name="Customer Support Agent",
-    agent_id="customer-support-agent",
+    agent_id="646d5dea-c2e6-4453-b446-7035482b38e4",
     agent_description="AI-powered customer support assistant",
 )
 ```

examples/customer_support_agent/demo.sh

@@ -222,9 +222,9 @@ setup_demo_controls() {
     python setup_demo_controls.py
 }
 
-# Generate UUID5 from agent ID (matches Python's uuid.uuid5(uuid.NAMESPACE_DNS, agent_id))
+# Agent UUID used by the demo (must match support_agent.py)
 get_agent_uuid() {
-    python3 -c "import uuid; print(uuid.uuid5(uuid.NAMESPACE_DNS, 'customer-support-agent'))"
+    echo "646d5dea-c2e6-4453-b446-7035482b38e4"
 }
 
 show_observability_stats() {

examples/customer_support_agent/run_demo.py

@@ -54,16 +54,13 @@
 # Add parent directory to path for imports
 sys.path.insert(0, str(__file__).rsplit("/", 2)[0])
 
-# Agent ID used in support_agent.py
-AGENT_ID = "customer-support-agent"
+# Agent UUID used in support_agent.py
+AGENT_ID = "646d5dea-c2e6-4453-b446-7035482b38e4"
 
 
 async def reset_agent():
     """Reset the agent by removing its policy (which disconnects all controls)."""
-    import uuid
-
-    # Generate the same UUID5 that the SDK generates
-    agent_uuid = str(uuid.uuid5(uuid.NAMESPACE_DNS, AGENT_ID))
+    agent_uuid = AGENT_ID
     server_url = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
 
     logger.info(f"Resetting agent '{AGENT_ID}' (UUID: {agent_uuid})")