atendentepro 0.6.3__py3-none-any.whl → 0.6.4__py3-none-any.whl

atendentepro/__init__.py

@@ -80,6 +80,11 @@ from atendentepro.models import (
     InterviewOutput,
     KnowledgeToolResult,
     GuardrailValidationOutput,
+    # Access filtering
+    UserContext,
+    AccessFilter,
+    FilteredPromptSection,
+    FilteredTool,
 )
 
 # Agents
@@ -185,6 +190,11 @@ __all__ = [
     "InterviewOutput",
     "KnowledgeToolResult",
     "GuardrailValidationOutput",
+    # Access filtering
+    "UserContext",
+    "AccessFilter",
+    "FilteredPromptSection",
+    "FilteredTool",
     # Agents
     "create_triage_agent",
     "create_flow_agent",

atendentepro/models/__init__.py

@@ -1,7 +1,13 @@
 # -*- coding: utf-8 -*-
 """Models module for AtendentePro library."""
 
-from .context import ContextNote
+from .context import (
+    ContextNote,
+    UserContext,
+    AccessFilter,
+    FilteredPromptSection,
+    FilteredTool,
+)
 from .outputs import (
     FlowTopic,
     FlowOutput,
@@ -11,7 +17,14 @@ from .outputs import (
 )
 
 __all__ = [
+    # Context models
     "ContextNote",
+    # Access filtering models
+    "UserContext",
+    "AccessFilter",
+    "FilteredPromptSection",
+    "FilteredTool",
+    # Output models
     "FlowTopic",
     "FlowOutput",
     "InterviewOutput",

atendentepro/models/context.py

@@ -3,6 +3,9 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass, field as dataclass_field
+from typing import Any, Callable, Dict, List, Optional
+
 from pydantic import BaseModel, Field
 
 
@@ -19,3 +22,161 @@ class ContextNote(BaseModel):
         description="Resumos estruturados gerados por agentes anteriores para orientar próximos handoffs.",
     )
 
+
+# =============================================================================
+# ACCESS FILTERING MODELS
+# =============================================================================
+
+@dataclass
+class UserContext:
+    """
+    User context for access filtering.
+    
+    Contains user identification and role information used to filter
+    access to agents, prompts, and tools.
+    
+    Attributes:
+        user_id: Unique user identifier
+        role: User role (e.g., "admin", "cliente", "vendedor")
+        metadata: Additional user metadata
+        
+    Example:
+        >>> user = UserContext(
+        ...     user_id="user123",
+        ...     role="vendedor",
+        ...     metadata={"department": "sales", "level": 2}
+        ... )
+    """
+    user_id: Optional[str] = None
+    role: Optional[str] = None
+    metadata: Dict[str, Any] = dataclass_field(default_factory=dict)
+
+
+@dataclass
+class AccessFilter:
+    """
+    Filter for controlling access to agents, prompts, and tools.
+    
+    Supports both whitelist (allowed_*) and blacklist (denied_*) patterns.
+    User-level filters take precedence over role-level filters.
+    
+    Attributes:
+        allowed_roles: If set, only these roles can access
+        denied_roles: If set, these roles cannot access
+        allowed_users: If set, only these users can access (overrides role)
+        denied_users: If set, these users cannot access (overrides role)
+        
+    Example:
+        >>> # Only admin and manager can access
+        >>> filter1 = AccessFilter(allowed_roles=["admin", "gerente"])
+        >>> 
+        >>> # Everyone except clients
+        >>> filter2 = AccessFilter(denied_roles=["cliente"])
+        >>> 
+        >>> # Specific premium users
+        >>> filter3 = AccessFilter(allowed_users=["premium_user_1", "premium_user_2"])
+    """
+    allowed_roles: Optional[List[str]] = None
+    denied_roles: Optional[List[str]] = None
+    allowed_users: Optional[List[str]] = None
+    denied_users: Optional[List[str]] = None
+    
+    def is_allowed(self, ctx: Optional[UserContext]) -> bool:
+        """
+        Check if user/role has access.
+        
+        Evaluation order:
+        1. If no context provided, allow (no filter applied)
+        2. Check denied_users (if user is denied, block)
+        3. Check allowed_users (if set and user not in list, block)
+        4. Check denied_roles (if role is denied, block)
+        5. Check allowed_roles (if set and role not in list, block)
+        6. Allow by default
+        
+        Args:
+            ctx: User context to check
+            
+        Returns:
+            True if access is allowed, False otherwise
+        """
+        if ctx is None:
+            return True  # No context = no filter
+        
+        # User-level checks (highest priority)
+        if self.denied_users and ctx.user_id in self.denied_users:
+            return False
+        if self.allowed_users:
+            if ctx.user_id in self.allowed_users:
+                return True  # Explicitly allowed user
+            # If allowed_users is set but user not in list, check roles
+            # unless no role filters are set
+            if not self.allowed_roles and not self.denied_roles:
+                return False
+        
+        # Role-level checks
+        if self.denied_roles and ctx.role in self.denied_roles:
+            return False
+        if self.allowed_roles and ctx.role not in self.allowed_roles:
+            return False
+        
+        return True  # No filter matched = allow
+
+
+@dataclass
+class FilteredPromptSection:
+    """
+    Conditional prompt section that appears based on access filter.
+    
+    Allows adding role/user-specific instructions to agent prompts.
+    
+    Attributes:
+        content: The prompt content to add
+        filter: Access filter determining when to include this section
+        
+    Example:
+        >>> # Section for admins only
+        >>> admin_section = FilteredPromptSection(
+        ...     content="## Admin Tools\\nYou can delete users and manage permissions.",
+        ...     filter=AccessFilter(allowed_roles=["admin"])
+        ... )
+    """
+    content: str
+    filter: AccessFilter
+    
+    def get_content_if_allowed(self, ctx: Optional[UserContext]) -> str:
+        """Return content if user has access, empty string otherwise."""
+        if self.filter.is_allowed(ctx):
+            return self.content
+        return ""
+
+
+@dataclass
+class FilteredTool:
+    """
+    Tool with access filter.
+    
+    Wraps a function_tool with an access filter to control who can use it.
+    
+    Attributes:
+        tool: The function_tool callable
+        filter: Access filter determining who can use this tool
+        
+    Example:
+        >>> @function_tool
+        ... def delete_user(user_id: str) -> str:
+        ...     return f"User {user_id} deleted"
+        >>> 
+        >>> admin_tool = FilteredTool(
+        ...     tool=delete_user,
+        ...     filter=AccessFilter(allowed_roles=["admin"])
+        ... )
+    """
+    tool: Callable
+    filter: AccessFilter
+    
+    def get_tool_if_allowed(self, ctx: Optional[UserContext]) -> Optional[Callable]:
+        """Return tool if user has access, None otherwise."""
+        if self.filter.is_allowed(ctx):
+            return self.tool
+        return None
+

atendentepro/network.py

@@ -122,6 +122,15 @@ from atendentepro.templates import (
     load_knowledge_config,
     load_confirmation_config,
     load_onboarding_config,
+    load_access_config,
+    AccessConfig,
+    AccessFilterConfig,
+)
+from atendentepro.models import (
+    UserContext,
+    AccessFilter,
+    FilteredPromptSection,
+    FilteredTool,
 )
 
 
@@ -202,6 +211,11 @@ def create_standard_network(
     # Single reply mode (auto-return to triage after one response)
     global_single_reply: bool = False,
     single_reply_agents: Optional[Dict[str, bool]] = None,
+    # Access filtering (role/user based)
+    user_context: Optional[UserContext] = None,
+    agent_filters: Optional[Dict[str, AccessFilter]] = None,
+    conditional_prompts: Optional[Dict[str, List[FilteredPromptSection]]] = None,
+    filtered_tools: Optional[Dict[str, List[FilteredTool]]] = None,
 ) -> AgentNetwork:
     """
     Create a standard agent network with proper handoff configuration.
@@ -241,6 +255,10 @@ def create_standard_network(
         agent_styles: Dict mapping agent names to specific styles (overrides global).
         global_single_reply: If True, all agents respond once then transfer to triage.
         single_reply_agents: Dict mapping agent names to single_reply mode (overrides global).
+        user_context: User context for access filtering (user_id, role, metadata).
+        agent_filters: Dict mapping agent names to AccessFilter (controls agent access).
+        conditional_prompts: Dict mapping agent names to list of FilteredPromptSection.
+        filtered_tools: Dict mapping agent names to list of FilteredTool.
         
     Returns:
         Configured AgentNetwork instance.
@@ -256,15 +274,27 @@ def create_standard_network(
             include_knowledge=False,
         )
         
-        # Create minimal network (only Triage, Flow, Interview, Answer)
+        # Create network with role-based access filtering
+        from atendentepro import UserContext, AccessFilter, FilteredPromptSection
+        
+        user = UserContext(user_id="user123", role="vendedor")
+        
         network = create_standard_network(
             templates_root=Path("templates"),
             client="my_client",
-            include_knowledge=False,
-            include_confirmation=False,
-            include_usage=False,
-            include_escalation=False,
-            include_feedback=False,
+            user_context=user,
+            agent_filters={
+                "knowledge": AccessFilter(allowed_roles=["admin", "vendedor"]),
+                "escalation": AccessFilter(denied_roles=["cliente"]),
+            },
+            conditional_prompts={
+                "knowledge": [
+                    FilteredPromptSection(
+                        content="\\n## Descontos\\nVocê pode oferecer até 15% de desconto.",
+                        filter=AccessFilter(allowed_roles=["vendedor"]),
+                    ),
+                ],
+            },
         )
         
         # Create network with custom communication style
@@ -276,23 +306,6 @@ def create_standard_network(
                 language_style="formal",
                 response_length="moderado",
             ),
-            agent_styles={
-                "escalation": AgentStyle(
-                    tone="empático e acolhedor",
-                    custom_rules="Demonstre compreensão pela situação.",
-                ),
-            },
-        )
-        
-        # Create network with single reply mode for specific agents
-        network = create_standard_network(
-            templates_root=Path("templates"),
-            client="my_client",
-            global_single_reply=False,  # Not all agents
-            single_reply_agents={
-                "knowledge": True,   # Knowledge responds once
-                "confirmation": True, # Confirmation responds once
-            },
         )
     """
     # Verificar licença
@@ -301,6 +314,79 @@ def create_standard_network(
     # Configure template manager
     manager = configure_template_manager(templates_root, default_client=client)
     
+    # Load access config from YAML if not provided via code
+    yaml_access_config = None
+    try:
+        yaml_access_config = load_access_config(client)
+    except FileNotFoundError:
+        pass
+    
+    # Helper function to check if agent is allowed for user
+    def is_agent_allowed(agent_name: str) -> bool:
+        """Check if agent should be included based on user context."""
+        if user_context is None:
+            return True  # No filtering if no user context
+        
+        # Code-level filter takes precedence
+        if agent_filters and agent_name in agent_filters:
+            return agent_filters[agent_name].is_allowed(user_context)
+        
+        # Fall back to YAML config
+        if yaml_access_config:
+            yaml_filter = yaml_access_config.get_agent_filter(agent_name)
+            if yaml_filter:
+                # Convert AccessFilterConfig to AccessFilter
+                access_filter = AccessFilter(
+                    allowed_roles=yaml_filter.allowed_roles,
+                    denied_roles=yaml_filter.denied_roles,
+                    allowed_users=yaml_filter.allowed_users,
+                    denied_users=yaml_filter.denied_users,
+                )
+                return access_filter.is_allowed(user_context)
+        
+        return True  # No filter = allowed
+    
+    # Helper function to get conditional prompts for agent
+    def get_conditional_prompts_for_agent(agent_name: str) -> str:
+        """Get all allowed conditional prompt sections for an agent."""
+        sections = []
+        
+        # Code-level prompts take precedence
+        if conditional_prompts and agent_name in conditional_prompts:
+            for section in conditional_prompts[agent_name]:
+                content = section.get_content_if_allowed(user_context)
+                if content:
+                    sections.append(content)
+        
+        # Add YAML-level prompts
+        if yaml_access_config:
+            for prompt_cfg in yaml_access_config.get_conditional_prompts(agent_name):
+                # Convert to AccessFilter and check
+                access_filter = AccessFilter(
+                    allowed_roles=prompt_cfg.filter.allowed_roles,
+                    denied_roles=prompt_cfg.filter.denied_roles,
+                    allowed_users=prompt_cfg.filter.allowed_users,
+                    denied_users=prompt_cfg.filter.denied_users,
+                )
+                if access_filter.is_allowed(user_context):
+                    sections.append(prompt_cfg.content)
+        
+        return "\n".join(sections)
+    
+    # Helper function to get filtered tools for agent
+    def get_filtered_tools_for_agent(agent_name: str, base_tools: List) -> List:
+        """Get tools filtered by user context."""
+        result_tools = list(base_tools) if base_tools else []
+        
+        # Add code-level filtered tools
+        if filtered_tools and agent_name in filtered_tools:
+            for ft in filtered_tools[agent_name]:
+                tool = ft.get_tool_if_allowed(user_context)
+                if tool:
+                    result_tools.append(tool)
+        
+        return result_tools
+    
     # Load configurations
     try:
         flow_config = load_flow_config(client)
@@ -381,47 +467,54 @@ def create_standard_network(
         # Fall back to global setting
         return global_single_reply
     
+    # Helper to build full style instructions with conditional prompts
+    def get_full_instructions(agent_name: str) -> str:
+        """Get style + conditional prompt instructions for an agent."""
+        style = get_style_for_agent(agent_name)
+        conditional = get_conditional_prompts_for_agent(agent_name)
+        return f"{style}{conditional}" if conditional else style
+    
     # Create agents without handoffs first
     # Triage is always created (entry point)
     triage = create_triage_agent(
         keywords_text=triage_keywords,
         guardrails=get_guardrails_for_agent("Triage Agent", templates_root),
-        style_instructions=get_style_for_agent("triage"),
+        style_instructions=get_full_instructions("triage"),
     )
     
-    # Create optional agents based on include flags
+    # Create optional agents based on include flags AND access filters
     flow = None
-    if include_flow:
+    if include_flow and is_agent_allowed("flow"):
         flow = create_flow_agent(
             flow_template=flow_template,
             flow_keywords=flow_keywords,
             guardrails=get_guardrails_for_agent("Flow Agent", templates_root),
-            style_instructions=get_style_for_agent("flow"),
+            style_instructions=get_full_instructions("flow"),
             single_reply=get_single_reply_for_agent("flow"),
         )
     
     interview = None
-    if include_interview:
+    if include_interview and is_agent_allowed("interview"):
         interview = create_interview_agent(
             interview_template=flow_template,
             interview_questions=interview_questions,
-            tools=tools.get("interview", []),
+            tools=get_filtered_tools_for_agent("interview", tools.get("interview", [])),
             guardrails=get_guardrails_for_agent("Interview Agent", templates_root),
-            style_instructions=get_style_for_agent("interview"),
+            style_instructions=get_full_instructions("interview"),
             single_reply=get_single_reply_for_agent("interview"),
         )
     
     answer = None
-    if include_answer:
+    if include_answer and is_agent_allowed("answer"):
         answer = create_answer_agent(
             answer_template="",
             guardrails=get_guardrails_for_agent("Answer Agent", templates_root),
-            style_instructions=get_style_for_agent("answer"),
+            style_instructions=get_full_instructions("answer"),
             single_reply=get_single_reply_for_agent("answer"),
         )
     
     knowledge = None
-    if include_knowledge:
+    if include_knowledge and is_agent_allowed("knowledge"):
         knowledge = create_knowledge_agent(
             knowledge_about=knowledge_about,
             knowledge_template=knowledge_template,
@@ -429,52 +522,52 @@ def create_standard_network(
             embeddings_path=embeddings_path,
             data_sources_description=data_sources_description,
             include_rag_tool=has_embeddings,
-            tools=tools.get("knowledge", []),
+            tools=get_filtered_tools_for_agent("knowledge", tools.get("knowledge", [])),
             guardrails=get_guardrails_for_agent("Knowledge Agent", templates_root),
-            style_instructions=get_style_for_agent("knowledge"),
+            style_instructions=get_full_instructions("knowledge"),
             single_reply=get_single_reply_for_agent("knowledge"),
         )
     
     confirmation = None
-    if include_confirmation:
+    if include_confirmation and is_agent_allowed("confirmation"):
         confirmation = create_confirmation_agent(
             confirmation_about=confirmation_about,
             confirmation_template=confirmation_template,
             confirmation_format=confirmation_format,
             guardrails=get_guardrails_for_agent("Confirmation Agent", templates_root),
-            style_instructions=get_style_for_agent("confirmation"),
+            style_instructions=get_full_instructions("confirmation"),
             single_reply=get_single_reply_for_agent("confirmation"),
         )
     
     usage = None
-    if include_usage:
+    if include_usage and is_agent_allowed("usage"):
         usage = create_usage_agent(
             guardrails=get_guardrails_for_agent("Usage Agent", templates_root),
-            style_instructions=get_style_for_agent("usage"),
+            style_instructions=get_full_instructions("usage"),
             single_reply=get_single_reply_for_agent("usage"),
         )
     
-    # Create escalation agent if requested
+    # Create escalation agent if requested and allowed
     escalation = None
-    if include_escalation:
+    if include_escalation and is_agent_allowed("escalation"):
         escalation = create_escalation_agent(
             escalation_channels=escalation_channels,
-            tools=tools.get("escalation", []),
+            tools=get_filtered_tools_for_agent("escalation", tools.get("escalation", [])),
             guardrails=get_guardrails_for_agent("Escalation Agent", templates_root),
-            style_instructions=get_style_for_agent("escalation"),
+            style_instructions=get_full_instructions("escalation"),
             single_reply=get_single_reply_for_agent("escalation"),
         )
     
-    # Create feedback agent if requested
+    # Create feedback agent if requested and allowed
     feedback = None
-    if include_feedback:
+    if include_feedback and is_agent_allowed("feedback"):
         feedback = create_feedback_agent(
             protocol_prefix=feedback_protocol_prefix,
             email_brand_color=feedback_brand_color,
             email_brand_name=feedback_brand_name,
-            tools=tools.get("feedback", []),
+            tools=get_filtered_tools_for_agent("feedback", tools.get("feedback", [])),
             guardrails=get_guardrails_for_agent("Feedback Agent", templates_root),
-            style_instructions=get_style_for_agent("feedback"),
+            style_instructions=get_full_instructions("feedback"),
             single_reply=get_single_reply_for_agent("feedback"),
         )
     
@@ -566,7 +659,7 @@ def create_standard_network(
     )
     
     # Add onboarding if requested
-    if include_onboarding:
+    if include_onboarding and is_agent_allowed("onboarding"):
         try:
             onboarding_config = load_onboarding_config(client)
             from atendentepro.prompts.onboarding import OnboardingField as PromptField
@@ -584,9 +677,9 @@ def create_standard_network(
         
         onboarding = create_onboarding_agent(
             required_fields=fields,
-            tools=tools.get("onboarding", []),
+            tools=get_filtered_tools_for_agent("onboarding", tools.get("onboarding", [])),
             guardrails=get_guardrails_for_agent("Onboarding Agent", templates_root),
-            style_instructions=get_style_for_agent("onboarding"),
+            style_instructions=get_full_instructions("onboarding"),
             single_reply=get_single_reply_for_agent("onboarding"),
         )
         

atendentepro/templates/__init__.py

@@ -16,6 +16,7 @@ from .manager import (
     load_onboarding_config,
     load_style_config,
     load_single_reply_config,
+    load_access_config,
     FlowConfig,
     InterviewConfig,
     TriageConfig,
@@ -25,6 +26,9 @@ from .manager import (
     StyleConfig,
     AgentStyleConfig,
     SingleReplyConfig,
+    AccessConfig,
+    AccessFilterConfig,
+    ConditionalPromptConfig,
     DataSourceConfig,
     DataSourceColumn,
     DocumentConfig,
@@ -45,6 +49,7 @@ __all__ = [
     "load_onboarding_config",
     "load_style_config",
     "load_single_reply_config",
+    "load_access_config",
     "FlowConfig",
     "InterviewConfig",
     "TriageConfig",
@@ -54,6 +59,9 @@ __all__ = [
     "StyleConfig",
     "AgentStyleConfig",
     "SingleReplyConfig",
+    "AccessConfig",
+    "AccessFilterConfig",
+    "ConditionalPromptConfig",
     "DataSourceConfig",
     "DataSourceColumn",
     "DocumentConfig",

atendentepro/templates/manager.py

@@ -434,6 +434,133 @@ class SingleReplyConfig(BaseModel):
         return self.global_enabled
 
 
+# =============================================================================
+# ACCESS FILTER CONFIGURATION (Role/User based access control)
+# =============================================================================
+
+class AccessFilterConfig(BaseModel):
+    """Configuration for a single access filter."""
+    
+    allowed_roles: Optional[List[str]] = None
+    denied_roles: Optional[List[str]] = None
+    allowed_users: Optional[List[str]] = None
+    denied_users: Optional[List[str]] = None
+
+
+class ConditionalPromptConfig(BaseModel):
+    """Configuration for a conditional prompt section."""
+    
+    content: str = ""
+    filter: AccessFilterConfig = Field(default_factory=AccessFilterConfig)
+
+
+class AccessConfig(BaseModel):
+    """
+    Configuration model for role/user based access control.
+    
+    Allows controlling access to agents, prompts, and tools based on
+    user identity or role. Supports both whitelist and blacklist patterns.
+    
+    Example YAML:
+        # Filter entire agents by role
+        agent_filters:
+          knowledge:
+            allowed_roles: ["admin", "vendedor"]
+          escalation:
+            denied_roles: ["cliente"]
+        
+        # Conditional prompt sections
+        conditional_prompts:
+          knowledge:
+            - content: |
+                ## Admin Tools
+                You have access to admin features.
+              filter:
+                allowed_roles: ["admin"]
+            - content: |
+                ## Sales Tools
+                You can offer up to 15% discount.
+              filter:
+                allowed_roles: ["vendedor"]
+        
+        # Tool access control
+        tool_access:
+          delete_user:
+            allowed_roles: ["admin"]
+          approve_discount:
+            allowed_roles: ["gerente", "admin"]
+    """
+    
+    agent_filters: Dict[str, AccessFilterConfig] = Field(default_factory=dict)
+    conditional_prompts: Dict[str, List[ConditionalPromptConfig]] = Field(default_factory=dict)
+    tool_access: Dict[str, AccessFilterConfig] = Field(default_factory=dict)
+    
+    @classmethod
+    @lru_cache(maxsize=4)
+    def load(cls, path: Path) -> "AccessConfig":
+        """Load access configuration from YAML file."""
+        if not path.exists():
+            raise FileNotFoundError(f"Access config not found at {path}")
+        
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        
+        # Parse agent filters
+        agent_filters = {}
+        for agent_name, filter_data in data.get("agent_filters", {}).items():
+            agent_filters[agent_name] = AccessFilterConfig(
+                allowed_roles=filter_data.get("allowed_roles"),
+                denied_roles=filter_data.get("denied_roles"),
+                allowed_users=filter_data.get("allowed_users"),
+                denied_users=filter_data.get("denied_users"),
+            )
+        
+        # Parse conditional prompts
+        conditional_prompts = {}
+        for agent_name, prompts_data in data.get("conditional_prompts", {}).items():
+            prompts_list = []
+            for prompt_data in prompts_data:
+                filter_data = prompt_data.get("filter", {})
+                prompts_list.append(ConditionalPromptConfig(
+                    content=prompt_data.get("content", ""),
+                    filter=AccessFilterConfig(
+                        allowed_roles=filter_data.get("allowed_roles"),
+                        denied_roles=filter_data.get("denied_roles"),
+                        allowed_users=filter_data.get("allowed_users"),
+                        denied_users=filter_data.get("denied_users"),
+                    ),
+                ))
+            conditional_prompts[agent_name] = prompts_list
+        
+        # Parse tool access
+        tool_access = {}
+        for tool_name, filter_data in data.get("tool_access", {}).items():
+            tool_access[tool_name] = AccessFilterConfig(
+                allowed_roles=filter_data.get("allowed_roles"),
+                denied_roles=filter_data.get("denied_roles"),
+                allowed_users=filter_data.get("allowed_users"),
+                denied_users=filter_data.get("denied_users"),
+            )
+        
+        return cls(
+            agent_filters=agent_filters,
+            conditional_prompts=conditional_prompts,
+            tool_access=tool_access,
+        )
+    
+    def get_agent_filter(self, agent_name: str) -> Optional[AccessFilterConfig]:
+        """Get access filter for a specific agent."""
+        return self.agent_filters.get(agent_name)
+    
+    def get_conditional_prompts(self, agent_name: str) -> List[ConditionalPromptConfig]:
+        """Get conditional prompts for a specific agent."""
+        return self.conditional_prompts.get(agent_name, [])
+    
+    def get_tool_filter(self, tool_name: str) -> Optional[AccessFilterConfig]:
+        """Get access filter for a specific tool."""
+        return self.tool_access.get(tool_name)
+
+
 class OnboardingConfig(BaseModel):
     """Configuration model for Onboarding Agent."""
     
@@ -562,6 +689,11 @@ class TemplateManager:
         folder = self.get_template_folder(client)
         return SingleReplyConfig.load(folder / "single_reply_config.yaml")
     
+    def load_access_config(self, client: Optional[str] = None) -> AccessConfig:
+        """Load access configuration for the specified client."""
+        folder = self.get_template_folder(client)
+        return AccessConfig.load(folder / "access_config.yaml")
+    
     def clear_caches(self) -> None:
         """Clear all configuration caches."""
         FlowConfig.load.cache_clear()
@@ -572,6 +704,7 @@ class TemplateManager:
         OnboardingConfig.load.cache_clear()
         StyleConfig.load.cache_clear()
         SingleReplyConfig.load.cache_clear()
+        AccessConfig.load.cache_clear()
 
 
 def get_template_manager() -> TemplateManager:
@@ -670,3 +803,8 @@ def load_single_reply_config(client: Optional[str] = None) -> SingleReplyConfig:
     """Load single reply configuration for the specified client."""
     return get_template_manager().load_single_reply_config(client)
 
+
+def load_access_config(client: Optional[str] = None) -> AccessConfig:
+    """Load access configuration for the specified client."""
+    return get_template_manager().load_access_config(client)
+

{atendentepro-0.6.3.dist-info → atendentepro-0.6.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.6.3
+Version: 0.6.4
 Summary: Framework de orquestração de agentes IA com tom e estilo customizáveis. Integra documentos (RAG), APIs e bancos de dados em uma plataforma inteligente multi-agente.
 Author-email: BeMonkAI <contato@monkai.com.br>
 Maintainer-email: BeMonkAI <contato@monkai.com.br>
@@ -95,6 +95,7 @@ Plataforma que unifica múltiplos agentes especializados para resolver demandas
 - [Fluxo de Handoffs](#-fluxo-de-handoffs)
 - [Estilo de Comunicação](#-estilo-de-comunicação-agentstyle)
 - [Single Reply Mode](#-single-reply-mode)
+- [Filtros de Acesso](#-filtros-de-acesso-roleuser)
 - [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
 
@@ -712,80 +713,328 @@ agents:
 
 O **Single Reply Mode** permite configurar agentes para responderem apenas uma vez e automaticamente transferirem de volta para o Triage. Isso evita que a conversa fique "presa" em um agente específico.
 
+📂 **Exemplos completos**: [docs/examples/single_reply/](docs/examples/single_reply/)
+
 ### Quando Usar
 
-- **Chatbots de alto volume**: Respostas rápidas e independentes
-- **Consultas simples**: Uma pergunta = uma resposta
-- **Evitar loops**: Impedir que usuários fiquem presos em um agente
+| Cenário | Recomendação |
+|---------|--------------|
+| **Chatbots de alto volume** | ✅ Ativar para respostas rápidas |
+| **FAQ simples** | ✅ Knowledge com single_reply |
+| **Coleta de dados** | ❌ Interview precisa múltiplas interações |
+| **Onboarding** | ❌ Precisa guiar o usuário em etapas |
+| **Confirmações** | ✅ Confirma e volta ao Triage |
 
-### Via Código
+### Exemplo 1: FAQ Bot (Via Código)
+
+Chatbot otimizado para perguntas frequentes:
 
 ```python
 from pathlib import Path
 from atendentepro import create_standard_network
 
-# Ativar para TODOS os agentes
+# FAQ Bot: Knowledge e Answer respondem uma vez
 network = create_standard_network(
     templates_root=Path("./meu_cliente"),
     client="config",
-    global_single_reply=True,  # Todos respondem uma vez
+    global_single_reply=False,
+    single_reply_agents={
+        "knowledge": True,  # FAQ: responde e volta
+        "answer": True,     # Perguntas gerais: responde e volta
+        "flow": True,       # Menu: apresenta e volta
+    },
 )
+```
+
+### Exemplo 2: Bot de Leads (Via Código)
 
-# Ativar apenas para agentes específicos
+Bot que coleta dados mas responde dúvidas rapidamente:
+
+```python
 network = create_standard_network(
     templates_root=Path("./meu_cliente"),
     client="config",
     global_single_reply=False,
     single_reply_agents={
-        "knowledge": True,      # Knowledge responde uma vez
-        "confirmation": True,   # Confirmation responde uma vez
-        "answer": True,         # Answer responde uma vez
-        # interview: False      # Interview pode ter múltiplas interações
+        # Interview PRECISA de múltiplas interações para coletar dados
+        "interview": False,
+        
+        # Outros agentes podem ser rápidos
+        "knowledge": True,    # Tira dúvidas sobre produto
+        "answer": True,       # Responde perguntas
+        "confirmation": True, # Confirma cadastro
     },
 )
 ```
 
+### Exemplo 3: Ativar para TODOS os agentes
+
+```python
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    global_single_reply=True,  # Todos respondem uma vez
+)
+```
+
 ### Via YAML (single_reply_config.yaml)
 
 Crie o arquivo `single_reply_config.yaml` na pasta do cliente:
 
 ```yaml
-# Global: aplica a todos os agentes
+# Global: se true, TODOS os agentes respondem apenas uma vez
 global: false
 
-# Configuração por agente
+# Configuração por agente (sobrescreve global)
 agents:
-  # Agentes que respondem uma vez
-  knowledge: true
-  confirmation: true
-  answer: true
+  # Agentes de consulta: respondem uma vez
+  knowledge: true      # FAQ: responde e volta
+  answer: true         # Perguntas: responde e volta
+  confirmation: true   # Confirma e volta
+  usage: true          # Explica uso e volta
+  
+  # Agentes de coleta: múltiplas interações
+  interview: false     # Precisa coletar dados
+  onboarding: false    # Precisa guiar usuário
   
-  # Agentes que precisam de múltiplas interações
-  interview: false
-  flow: false
-  onboarding: false
+  # Opcionais
+  flow: true           # Menu: apresenta e volta
+  escalation: true     # Registra e volta
+  feedback: true       # Coleta feedback e volta
 ```
 
-### Comportamento
+### Fluxo Visual
 
-Quando `single_reply=True`:
+**Com single_reply=True:**
 
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (responde uma vez)
-                            ↓
-                       [Triage] ← (retorno automático)
+[Usuário: "Qual o preço?"]
+         ↓
+    [Triage] → detecta consulta
+         ↓
+  [Knowledge] → responde: "R$ 99,90"
+         ↓
+    [Triage] ← retorno AUTOMÁTICO
+         ↓
+[Usuário: "E a entrega?"]
+         ↓
+    [Triage] → nova análise (ciclo reinicia)
+```
+
+**Com single_reply=False (padrão):**
+
 ```
+[Usuário: "Qual o preço?"]
+         ↓
+    [Triage] → detecta consulta
+         ↓
+  [Knowledge] → responde: "R$ 99,90"
+         ↓
+[Usuário: "E a entrega?"]
+         ↓
+  [Knowledge] → continua no mesmo agente
+         ↓
+[Usuário: "Quero falar com humano"]
+         ↓
+  [Knowledge] → handoff para Escalation
+```
+
+### Configuração Recomendada
+
+Para a maioria dos casos de uso:
+
+```yaml
+global: false
+
+agents:
+  knowledge: true      # FAQ
+  answer: true         # Perguntas gerais
+  confirmation: true   # Confirmações
+  
+  interview: false     # Coleta de dados
+  onboarding: false    # Guia de usuário
+```
+
+---
+
+## 🔐 Filtros de Acesso (Role/User)
+
+O sistema de **Filtros de Acesso** permite controlar quais agentes, prompts e tools estão disponíveis para cada usuário ou role (função).
+
+📂 **Exemplos completos**: [docs/examples/access_filters/](docs/examples/access_filters/)
+
+### Quando Usar
+
+| Cenário | Solução |
+|---------|---------|
+| **Multi-tenant** | Diferentes clientes veem diferentes agentes |
+| **Níveis de acesso** | Admin vê mais opções que cliente |
+| **Segurança** | Dados sensíveis só para roles específicas |
+| **Personalização** | Diferentes instruções por departamento |
+
+### Níveis de Filtragem
+
+1. **Agentes**: Habilitar/desabilitar agentes inteiros
+2. **Prompts**: Adicionar seções condicionais aos prompts
+3. **Tools**: Habilitar/desabilitar tools específicas
+
+### Exemplo 1: Filtros de Agente (Via Código)
+
+```python
+from pathlib import Path
+from atendentepro import (
+    create_standard_network,
+    UserContext,
+    AccessFilter,
+)
+
+# Usuário com role de vendedor
+user = UserContext(user_id="vendedor_123", role="vendedor")
+
+# Filtros de agente
+agent_filters = {
+    # Feedback só para admin
+    "feedback": AccessFilter(allowed_roles=["admin"]),
+    # Escalation para todos exceto clientes
+    "escalation": AccessFilter(denied_roles=["cliente"]),
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    agent_filters=agent_filters,
+)
+```
+
+### Exemplo 2: Prompts Condicionais
+
+Adicione instruções específicas baseadas na role:
+
+```python
+from atendentepro import FilteredPromptSection
+
+conditional_prompts = {
+    "knowledge": [
+        # Seção para vendedores
+        FilteredPromptSection(
+            content="\\n## Descontos\\nVocê pode oferecer até 15% de desconto.",
+            filter=AccessFilter(allowed_roles=["vendedor"]),
+        ),
+        # Seção para admin
+        FilteredPromptSection(
+            content="\\n## Admin\\nVocê tem acesso total ao sistema.",
+            filter=AccessFilter(allowed_roles=["admin"]),
+        ),
+    ],
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    conditional_prompts=conditional_prompts,
+)
+```
+
+### Exemplo 3: Tools Filtradas
+
+```python
+from atendentepro import FilteredTool
+from agents import function_tool
+
+@function_tool
+def deletar_cliente(cliente_id: str) -> str:
+    """Remove um cliente do sistema."""
+    return f"Cliente {cliente_id} removido"
+
+filtered_tools = {
+    "knowledge": [
+        FilteredTool(
+            tool=deletar_cliente,
+            filter=AccessFilter(allowed_roles=["admin"]),  # Só admin
+        ),
+    ],
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    filtered_tools=filtered_tools,
+)
+```
+
+### Via YAML (access_config.yaml)
+
+```yaml
+# Filtros de agente
+agent_filters:
+  feedback:
+    allowed_roles: ["admin"]
+  escalation:
+    denied_roles: ["cliente"]
+
+# Prompts condicionais
+conditional_prompts:
+  knowledge:
+    - content: |
+        ## Capacidades de Vendedor
+        Você pode oferecer até 15% de desconto.
+      filter:
+        allowed_roles: ["vendedor"]
+
+# Acesso a tools
+tool_access:
+  deletar_cliente:
+    allowed_roles: ["admin"]
+```
+
+### Tipos de Filtro
+
+| Tipo | Descrição | Exemplo |
+|------|-----------|---------|
+| `allowed_roles` | Whitelist de roles | `["admin", "gerente"]` |
+| `denied_roles` | Blacklist de roles | `["cliente"]` |
+| `allowed_users` | Whitelist de usuários | `["user_vip_1"]` |
+| `denied_users` | Blacklist de usuários | `["user_bloqueado"]` |
+
+### Prioridade de Avaliação
+
+1. `denied_users` - Se usuário está negado, **bloqueia**
+2. `allowed_users` - Se lista existe e usuário está nela, **permite**
+3. `denied_roles` - Se role está negada, **bloqueia**
+4. `allowed_roles` - Se lista existe e role não está nela, **bloqueia**
+5. **Permite por padrão** - Se nenhum filtro matched
 
-Quando `single_reply=False` (padrão):
+### Fluxo Visual
 
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (pode continuar)
-                            ↕
-                       [Usuário]
+┌────────────────────────────────────────────────┐
+│         Requisição: role="vendedor"            │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│              FILTRO DE AGENTES                 │
+│  Knowledge: ✅ (vendedor allowed)              │
+│  Escalation: ✅ (vendedor not denied)          │
+│  Feedback: ❌ (only admin)                     │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│             FILTRO DE PROMPTS                  │
+│  Knowledge recebe: "## Descontos..."           │
+│  (seção condicional para vendedor)             │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│              FILTRO DE TOOLS                   │
+│  consultar_comissao: ✅                        │
+│  deletar_cliente: ❌ (only admin)              │
+└────────────────────────────────────────────────┘
 ```
 
 ---

{atendentepro-0.6.3.dist-info → atendentepro-0.6.4.dist-info}/RECORD

@@ -1,7 +1,7 @@
 atendentepro/README.md,sha256=TAXl5GRjhSwz_I-Dx_eN5JOIcUxuE_dz31iMZ_-OnRY,45390
-atendentepro/__init__.py,sha256=CDK61bxE18NYvLeswIoQWLarw2_xJAOEb2yONsQ2CqQ,5606
+atendentepro/__init__.py,sha256=ZIN7Nrrx04b5mq4YovL3wk6O6oTY659uffZOI9rYNbE,5820
 atendentepro/license.py,sha256=rlPtysXNqAzEQkP2VjUAVu_nMndhPgfKv1yN2ruUYVI,17570
-atendentepro/network.py,sha256=QEWgvNEWNkr1-xHd54dIdfFIgGJsRLBgQpuaDnQXknM,24124
+atendentepro/network.py,sha256=RmNrdf-78qWjlzxB7B8Awa-fJ7ZPQi5iQHZuHBPgVpo,28900
 atendentepro/agents/__init__.py,sha256=OcPhG1Dp6xe49B5YIti4HVmaZDoDIrFLfRa8GmI4jpQ,1638
 atendentepro/agents/answer.py,sha256=S6wTchNSTMc0h6d89A4jAzoqecFPVqHUrr55-rCM-p4,2494
 atendentepro/agents/confirmation.py,sha256=bQmIiDaxaCDIWJ3Fxz8h3AHW4kHhwbWSmyLX4y3dtls,2900
@@ -17,8 +17,8 @@ atendentepro/config/__init__.py,sha256=LQZbEz9AVGnO8xCG_rI9GmyFQun5HQqo8hJkkm-d_
 atendentepro/config/settings.py,sha256=Z1texEtO76Rrt-wPyEXM3FyujDE75r8HbEEJClzFOvk,4762
 atendentepro/guardrails/__init__.py,sha256=lCSI4RbQeIOya8k1wIADoxz9gYySDtUtOv-JiXisvyQ,454
 atendentepro/guardrails/manager.py,sha256=KeyQkIfyPYuHIbuCPP-N4y2R3AJ6n2thkEO_avDgY7M,14053
-atendentepro/models/__init__.py,sha256=eUMq0Lw21PGItGliKHxFDeETIqOVqEwkXVOjgJPM5I0,390
-atendentepro/models/context.py,sha256=1WsoHEtXodgfd5JyZDZctV_2uabNq_XAKv0HKmWb-G8,543
+atendentepro/models/__init__.py,sha256=H0l-WKYAW60hiU4uyVtteWRnH7l-8_WbVq-j5VqTNXM,638
+atendentepro/models/context.py,sha256=M_5RSsiT0C5C4D_NtLfUYj9mPRtqk4Wdn5SiwH91uXg,5931
 atendentepro/models/outputs.py,sha256=B573co699DhK0TSpqOHUykUOnBVa2Ool4rnNEO-xmUA,3270
 atendentepro/prompts/__init__.py,sha256=pks7i00GXGM9J3UnZyCn4dDVLb4C8xSJ_yWAvpK3OM4,1390
 atendentepro/prompts/answer.py,sha256=0VBKRzOXXlxg0IfIq1Et0XlDpX3akKASNb9NY_pesuM,3916
@@ -30,14 +30,14 @@ atendentepro/prompts/interview.py,sha256=9zVGA8zSmm6pBx2i1LPGNJIPuLlz7PZKRJE_PC6
 atendentepro/prompts/knowledge.py,sha256=B3BOyAvzQlwAkR51gc-B6XbQLtwIZlwGP1ofhZ4cFbk,4644
 atendentepro/prompts/onboarding.py,sha256=78fSIh2ifsGeoav8DV41_jnyU157c0dtggJujcDvW4U,6093
 atendentepro/prompts/triage.py,sha256=bSdEVheGy03r5P6MQuv7NwhN2_wrt0mK80F9f_LskRU,1283
-atendentepro/templates/__init__.py,sha256=Xc3yTQcdUbzKphbOYEAefhV1v9FzLas_WzuphYVpk_0,1377
-atendentepro/templates/manager.py,sha256=VHnu2dxWA6TR07QjJtsDZIRkwIjq-zGoIDysul7WMkE,23347
+atendentepro/templates/__init__.py,sha256=zV1CP2K7_WD219NXl-daTC3Iq8P9sQ7XLmxPEVI2NZg,1575
+atendentepro/templates/manager.py,sha256=s2ezeyEboeMxdcb6oOADQRAm0ikB8Ru4fYC87gfctU0,28819
 atendentepro/utils/__init__.py,sha256=WCJ6_btsLaI6xxHXvNHNue-nKrXWTKscNZGTToQiJ8A,833
 atendentepro/utils/openai_client.py,sha256=R0ns7SU36vTgploq14-QJMTke1pPxcAXlENDeoHU0L4,4552
 atendentepro/utils/tracing.py,sha256=kpTPw1PF4rR1qq1RyBnAaPIQIJRka4RF8MfG_JrRJ7U,8486
-atendentepro-0.6.3.dist-info/licenses/LICENSE,sha256=TF6CdXxePoT9DXtPnCejiU5mUwWzrFzd1iyWJyoMauA,983
-atendentepro-0.6.3.dist-info/METADATA,sha256=ijYMZnbksuX5O7ao9bA0deK6gI5eYM3jtE2S_hd2WOE,27835
-atendentepro-0.6.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-atendentepro-0.6.3.dist-info/entry_points.txt,sha256=OP0upzqJF3MLS6VX-M-5BfUwx5YLJO2sJ3YBAp4e6yI,89
-atendentepro-0.6.3.dist-info/top_level.txt,sha256=BFasD4SMmgDUmWKlTIZ1PeuukoRBhyiMIz8umKWVCcs,13
-atendentepro-0.6.3.dist-info/RECORD,,
+atendentepro-0.6.4.dist-info/licenses/LICENSE,sha256=TF6CdXxePoT9DXtPnCejiU5mUwWzrFzd1iyWJyoMauA,983
+atendentepro-0.6.4.dist-info/METADATA,sha256=hjjY6FTN3Ht4v_05KO-raxRQkZEuWAxV4ACLtWTnCEs,35702
+atendentepro-0.6.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+atendentepro-0.6.4.dist-info/entry_points.txt,sha256=OP0upzqJF3MLS6VX-M-5BfUwx5YLJO2sJ3YBAp4e6yI,89
+atendentepro-0.6.4.dist-info/top_level.txt,sha256=BFasD4SMmgDUmWKlTIZ1PeuukoRBhyiMIz8umKWVCcs,13
+atendentepro-0.6.4.dist-info/RECORD,,