0Pricing
AI Agents · Aula

Aplicação de políticas às ações dos agentes

Verificações de políticas antes das ações, listas de permissões e bloqueios e regras de políticas dinâmicas.

Aplicação de políticas às ações dos agentes é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

O que é a aplicação de políticas do agente?

A aplicação de políticas é o mecanismo de bloqueio em tempo de execução que funciona antes de cada ação do agente para decidir se ela é permitida. Sem esse mecanismo, a única restrição do agente é o seguimento das instruções do LLM — que pode ser contornado ou interpretado incorretamente.

A aplicação deve ocorrer fora do LLM, na sua infraestrutura.

O padrão de verificação prévia à ação

Antes de executar qualquer ferramenta, chame can_agent_do(action, context). Essa função é o único ponto de aplicação — todo caminho até a execução de uma ação passa por ela.

def can_agent_do(action: str, context: dict) -> tuple[bool, str]:
    '''
    Returns (allowed: bool, reason: str).
    Context includes: user_id, agent_id, session_id, parameters, timestamp.
    '''
    # 1. Check denylist first (fast path for obvious violations)
    if action in DENIED_ACTIONS:
        return False, f'Action "{action}" is on the global denylist'

    # 2. Check allowlist
    if action not in ALLOWED_ACTIONS:
        return False, f'Action "{action}" is not on the allowlist'

    # 3. Context-specific checks
    return check_context_policy(action, context)

Definindo listas de permissões e listas de bloqueios

A lista de permissões enumera todas as ações que o agente tem autorização para executar. Qualquer item que não esteja na lista é bloqueado por padrão. A lista de bloqueios acrescenta uma camada extra de segurança para ações que nunca devem ser permitidas, independentemente do contexto.

# Allowlist: tools the agent can use
ALLOWED_ACTIONS = {
    'web_search',
    'read_file',
    'write_file',
    'send_email',
    'create_calendar_event',
    'query_database',
    'execute_python_sandbox',
    'fetch_url',
    'create_ticket'
}

# Denylist: actions that are always blocked, regardless of context
DENIED_ACTIONS = {
    'delete_all_records',
    'export_entire_database',
    'send_mass_email',
    'modify_system_config',
    'create_admin_user',
    'disable_audit_logging'
}

if __name__ == '__main__':
    for action in ('web_search', 'send_mass_email'):
        print(f"{action}: allowed={action in ALLOWED_ACTIONS} denied={action in DENIED_ACTIONS}")

Verificações de políticas específicas ao contexto

Além de listas simples de permissão e bloqueio, as políticas geralmente dependem do contexto: quem é o usuário, qual é a função dele, que horas são e qual é o recurso-alvo? Essas são verificações específicas ao contexto.

from datetime import datetime, timezone

def check_context_policy(action: str, context: dict) -> tuple[bool, str]:
    user_id   = context.get('user_id', '')
    params    = context.get('parameters', {})
    user_role = context.get('user_role', 'user')

    # send_email: only agents with email_sender role
    if action == 'send_email':
        if user_role not in ('email_agent', 'admin'):
            return False, f'Role "{user_role}" cannot send emails'
        recipient = params.get('to', '')
        if not recipient.endswith('@trusted-domain.com'):
            return False, 'Email recipient must be in @trusted-domain.com'

    # write_file: path restrictions
    if action == 'write_file':
        path = params.get('path', '')
        if not path.startswith('/tmp/') and not path.startswith('/workspace/'):
            return False, f'File writes outside /tmp/ and /workspace/ are not allowed'

    return True, 'Permitted'

if __name__ == '__main__':
    ctx = {'user_id': 'u1', 'user_role': 'user',
           'parameters': {'to': 'someone@gmail.com'}}
    print('send_email as user:', check_context_policy('send_email', ctx))

    ctx2 = {'user_id': 'u1', 'user_role': 'user',
            'parameters': {'path': '/etc/passwd'}}
    print('write_file outside sandbox:', check_context_policy('write_file', ctx2))

Políticas dinâmicas de um mecanismo de políticas

Políticas codificadas diretamente são difíceis de atualizar em produção. Use um mecanismo de políticas (como OPA — Agente de Políticas Abertas) para avaliar políticas definidas como dados, não como código. As políticas podem ser atualizadas sem reimplantar o agente.

import requests

OPA_URL = 'http://localhost:8181/v1/data/agent/allow'

def opa_policy_check(action: str, context: dict) -> tuple[bool, str]:
    payload = {
        'input': {
            'action':   action,
            'user_id':  context.get('user_id'),
            'role':     context.get('user_role', 'user'),
            'params':   context.get('parameters', {}),
            'time_utc': datetime.now(timezone.utc).isoformat()
        }
    }
    try:
        resp = requests.post(OPA_URL, json=payload, timeout=0.5)
        result = resp.json().get('result', {})
        allowed = result.get('allow', False)
        reason  = result.get('reason', 'Policy decision')
        return allowed, reason
    except Exception as e:
        # Fail closed: deny if policy engine is unreachable
        return False, f'Policy engine unavailable: {e}'

Falha fechada versus falha aberta

Quando o mecanismo de políticas está indisponível, há duas opções:

  • Falha fechada: negar todas as ações. É seguro, mas o agente para de funcionar.
  • Falha aberta: permitir todas as ações. O agente continua funcionando, mas a política não é aplicada.

Para agentes sensíveis à segurança, use sempre a falha fechada. Para agentes de produtividade com ações de baixo risco, a falha aberta pode ser aceitável.

FAIL_CLOSED = True  # Configure per agent

def safe_policy_check(action: str, context: dict) -> tuple[bool, str]:
    try:
        return can_agent_do(action, context)
    except Exception as e:
        if FAIL_CLOSED:
            return False, f'Policy check failed (fail-closed): {e}'
        else:
            # Log the failure but allow the action
            import logging
            logging.warning('Policy check error (fail-open): %s', e)
            return True, 'Policy check bypassed due to error (fail-open)'

Limitando a frequência das ações

A aplicação de políticas pode incluir limites de frequência: pode ser permitido que um agente envie e-mails, mas somente 5 por sessão. Se o limite for excedido, a ação será negada.

from collections import defaultdict
import time

action_counts: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
action_window_start: dict[str, float] = defaultdict(float)

ACTION_RATE_LIMITS = {
    'send_email':   {'limit': 5,  'window_secs': 3600},  # 5/hour
    'write_file':   {'limit': 50, 'window_secs': 300},
    'web_search':   {'limit': 20, 'window_secs': 60}
}

def check_rate_limit(action: str, session_id: str) -> tuple[bool, str]:
    limit_config = ACTION_RATE_LIMITS.get(action)
    if not limit_config:
        return True, 'No rate limit defined'

    window = limit_config['window_secs']
    now = time.time()
    key = f'{session_id}:{action}'

    if now - action_window_start[key] > window:
        action_counts[key] = defaultdict(int)
        action_window_start[key] = now

    action_counts[key]['count'] += 1
    if action_counts[key]['count'] > limit_config['limit']:
        return False, f'Rate limit exceeded: {action} ({limit_config["limit"]}/{window}s)'
    return True, 'Within rate limit'

if __name__ == '__main__':
    for i in range(6):
        allowed, reason = check_rate_limit('send_email', 'session-1')
    print(f'After 6 send_email calls: allowed={allowed}, reason={reason}')

Registro de violações de políticas

Cada negação de política deve ser registrada com o contexto completo. Esses registros são o primeiro lugar a consultar ao depurar um comportamento inesperado do agente ou investigar um incidente de segurança.

import logging, json, time

policy_logger = logging.getLogger('agent.policy')

def enforced_action(agent_id: str, user_id: str, action: str,
                    context: dict, audit_log) -> tuple[bool, str]:
    allowed, reason = safe_policy_check(action, context)

    log_entry = {
        'ts':       time.time(),
        'agent_id': agent_id,
        'user_id':  user_id,
        'action':   action,
        'allowed':  allowed,
        'reason':   reason,
        'params':   context.get('parameters', {})
    }

    if allowed:
        policy_logger.info('ALLOWED %s', json.dumps(log_entry))
    else:
        policy_logger.warning('DENIED %s', json.dumps(log_entry))

    audit_log.append(
        agent_id, user_id,
        f'POLICY_{"ALLOW" if allowed else "DENY"}',
        {'action': action},
        {'allowed': allowed, 'reason': reason},
        context.get('session_id', '')
    )
    return allowed, reason

Delimitação de recursos

Mesmo para ações permitidas, delimite os recursos que o agente pode acessar. Um agente que processa os documentos do usuário A não deve conseguir ler os arquivos do usuário B, mesmo que read_file esteja na lista de permissões.

def check_resource_scope(action: str, context: dict) -> tuple[bool, str]:
    user_id  = context.get('user_id', '')
    params   = context.get('parameters', {})

    if action == 'read_file':
        path = params.get('path', '')
        # Each user's files must be under their own namespace
        if not path.startswith(f'/workspace/{user_id}/'):
            return False, (
                f'User {user_id} cannot read files outside '
                f'/workspace/{user_id}/'
            )

    if action == 'query_database':
        table = params.get('table', '')
        allowed_tables = {'products', 'public_docs', f'user_{user_id}_data'}
        if table not in allowed_tables:
            return False, f'Table "{table}" not in scope for user {user_id}'

    return True, 'Resource scope check passed'

if __name__ == '__main__':
    ctx = {'user_id': 'u1', 'parameters': {'path': '/workspace/u2/secret.txt'}}
    print('Cross-user file read:', check_resource_scope('read_file', ctx))

    ctx2 = {'user_id': 'u1', 'parameters': {'path': '/workspace/u1/notes.txt'}}
    print('Own file read:      ', check_resource_scope('read_file', ctx2))

Testando regras de políticas

As regras de políticas são código — elas precisam ser testadas. Escreva testes unitários para cada regra, garantindo que as negações e permissões funcionem corretamente e que casos extremos não criem brechas acidentais nas políticas.

def test_policy_rules():
    # Denylist blocks unconditionally
    ok, msg = can_agent_do('delete_all_records', {'user_role': 'admin'})
    assert not ok, 'Denylist should block even for admin'

    # Email requires trusted domain
    ok, msg = can_agent_do('send_email', {
        'user_role': 'email_agent',
        'parameters': {'to': 'attacker@evil.com'}
    })
    assert not ok, 'Should block untrusted email recipient'

    # File write outside allowed paths
    ok, msg = can_agent_do('write_file', {
        'user_role': 'user',
        'parameters': {'path': '/etc/crontab'}
    })
    assert not ok, 'Should block write to /etc/'

    print('All policy tests passed')

test_policy_rules()

Armazenando em cache as decisões de políticas

Chamar o mecanismo de políticas para cada ação individual acrescenta latência, especialmente ao usar um serviço OPA externo. Armazene em cache as decisões recentes para pares (ação, resumo_do_contexto) com um TTL curto, reduzindo as comunicações de ida e volta.

import hashlib, time

policy_cache: dict[str, dict] = {}
POLICY_CACHE_TTL = 10  # seconds — short TTL so policy updates take effect quickly

def cached_policy_check(action: str, context: dict) -> tuple[bool, str]:
    ctx_hash = hashlib.md5(
        f'{action}:{context.get("user_id")}:{context.get("user_role")}'
        .encode()
    ).hexdigest()
    key = f'{action}:{ctx_hash}'
    entry = policy_cache.get(key)
    if entry and time.time() - entry['ts'] < POLICY_CACHE_TTL:
        return entry['result']
    result = can_agent_do(action, context)
    policy_cache[key] = {'result': result, 'ts': time.time()}
    return result

Qual é a abordagem de falha fechada para a aplicação de políticas?

A decisão entre falha fechada e falha aberta é um compromisso fundamental de segurança para qualquer sistema de aplicação de políticas. Saber quando cada abordagem é apropriada é um conceito central de governança.

Recapitulação da aplicação de políticas

A aplicação de políticas de agentes usa: uma verificação prévia à ação como único mecanismo de bloqueio, listas de permissões + listas de bloqueios para decisões básicas, regras específicas ao contexto para delimitação de recursos e verificações de funções, um mecanismo de políticas dinâmico (OPA) para regras atualizáveis, limites de frequência por ação e por sessão e padrões de falha fechada para agentes críticos para a segurança.

Perguntas Frequentes

A aula “Aplicação de políticas às ações dos agentes” é grátis?

Sim — o texto completo de “Aplicação de políticas às ações dos agentes” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Aplicação de políticas às ações dos agentes”?

Verificações de políticas antes das ações, listas de permissões e bloqueios e regras de políticas dinâmicas. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Aplicação de políticas às ações dos agentes”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Registro imutável de ações dos agentes
  2. Aplicação de políticas às ações dos agentes
  3. Conformidade regulatória: GDPR e SOC2
  4. Portões de aprovação com participação humana
← Voltar para AI Agents