Módulo de Entrada HTTP

🌐 Outros idiomas

English

中文简体

Español

Português

日本語

Deutsch

---

O módulo de Entrada HTTP fornece um servidor webhook que permite que sistemas externos invoquem agentes Symbiont através de requisições HTTP. Este módulo permite integração com serviços externos, webhooks e APIs expondo agentes através de endpoints HTTP.

Visão Geral

O módulo de Entrada HTTP consiste em:

• Servidor HTTP: Um servidor web baseado em Axum que escuta requisições HTTP recebidas
• Autenticação: Suporte para autenticação baseada em Bearer token e JWT
• Roteamento de Requisições: Regras de roteamento flexíveis para direcionar requisições para agentes específicos
• Controle de Resposta: Formatação de resposta configurável e códigos de status
• Recursos de Segurança: Suporte CORS, limites de tamanho de requisição e registro de auditoria
• Gerenciamento de Concorrência: Limitação de taxa de requisições integrada e controle de concorrência

O módulo é compilado condicionalmente com a flag de recurso http-input e integra-se perfeitamente com o runtime de agentes Symbiont.

Configuração

O módulo de Entrada HTTP é configurado usando a estrutura HttpInputConfig:

Configuração Básica

use symbiont_runtime::http_input::HttpInputConfig;
use symbiont_runtime::types::AgentId;

let config = HttpInputConfig {
    bind_address: "0.0.0.0".to_string(),
    port: 8081,
    path: "/webhook".to_string(),
    agent: AgentId::from_str("webhook_handler")?,
    // ... other fields
    ..Default::default()
};

Campos de Configuração

Campo	Tipo	Padrão	Descrição
bind_address	String	"0.0.0.0"	Endereço IP para vincular o servidor HTTP
port	u16	8081	Número da porta para escutar
path	String	"/webhook"	Endpoint de caminho HTTP
agent	AgentId	Novo ID	Agente padrão para invocar para requisições
auth_header	Option<String>	None	Bearer token para autenticação
jwt_public_key_path	Option<String>	None	Caminho para arquivo de chave pública JWT
max_body_bytes	usize	65536	Tamanho máximo do corpo da requisição (64 KB)
concurrency	usize	10	Máximo de requisições concorrentes
routing_rules	Option<Vec<AgentRoutingRule>>	None	Regras de roteamento de requisições
response_control	Option<ResponseControlConfig>	None	Configuração de formatação de resposta
forward_headers	Vec<String>	[]	Cabeçalhos para encaminhar aos agentes
cors_enabled	bool	false	Habilitar suporte CORS
audit_enabled	bool	true	Habilitar registro de auditoria de requisições

Regras de Roteamento de Agentes

Rotear requisições para diferentes agentes baseado nas características da requisição:

use symbiont_runtime::http_input::{AgentRoutingRule, RouteMatch};

let routing_rules = vec![
    AgentRoutingRule {
        condition: RouteMatch::PathPrefix("/api/github".to_string()),
        agent: AgentId::from_str("github_handler")?,
    },
    AgentRoutingRule {
        condition: RouteMatch::HeaderEquals("X-Source".to_string(), "slack".to_string()),
        agent: AgentId::from_str("slack_handler")?,
    },
    AgentRoutingRule {
        condition: RouteMatch::JsonFieldEquals("source".to_string(), "twilio".to_string()),
        agent: AgentId::from_str("sms_handler")?,
    },
];

Controle de Resposta

Personalizar respostas HTTP com ResponseControlConfig:

use symbiont_runtime::http_input::ResponseControlConfig;

let response_control = ResponseControlConfig {
    default_status: 200,
    agent_output_to_json: true,
    error_status: 500,
    echo_input_on_error: false,
};

Recursos de Segurança

Autenticação

O módulo de Entrada HTTP suporta múltiplos métodos de autenticação:

Autenticação com Bearer Token

Configurar um bearer token estático:

let config = HttpInputConfig {
    auth_header: Some("Bearer your-secret-token".to_string()),
    ..Default::default()
};

Integração com Armazenamento de Segredos

Usar referências de segredos para segurança aprimorada:

let config = HttpInputConfig {
    auth_header: Some("vault://webhook/auth_token".to_string()),
    ..Default::default()
};

Autenticação JWT

Configurar autenticação baseada em JWT:

let config = HttpInputConfig {
    jwt_public_key_path: Some("/path/to/jwt/public.key".to_string()),
    ..Default::default()
};

Controles de Segurança

• Limites de Tamanho de Requisição: Tamanho máximo configurável do corpo previne esgotamento de recursos
• Limites de Concorrência: Semáforo integrado controla processamento de requisições concorrentes
• Suporte CORS: Cabeçalhos CORS opcionais para aplicações baseadas em navegador
• Registro de Auditoria: Registro estruturado de todas as requisições recebidas quando habilitado
• Resolução de Segredos: Integração com Vault e armazenamentos de segredos baseados em arquivo

Exemplo de Uso

Iniciando o Servidor de Entrada HTTP

use symbiont_runtime::http_input::{HttpInputConfig, start_http_input};
use symbiont_runtime::secrets::SecretsConfig;
use std::sync::Arc;

// Configurar o servidor de entrada HTTP
let config = HttpInputConfig {
    bind_address: "127.0.0.1".to_string(),
    port: 8081,
    path: "/webhook".to_string(),
    agent: AgentId::from_str("webhook_handler")?,
    auth_header: Some("Bearer secret-token".to_string()),
    audit_enabled: true,
    cors_enabled: true,
    ..Default::default()
};

// Opcional: Configurar segredos
let secrets_config = SecretsConfig::default();

// Iniciar o servidor
start_http_input(config, Some(runtime), Some(secrets_config)).await?;

Exemplo de Definição de Agente

Criar um agente manipulador de webhook em webhook_handler.dsl:

agent webhook_handler(body: JSON) -> Maybe<Alert> {
    capabilities = ["http_input", "event_processing", "alerting"]
    memory = "ephemeral"
    privacy = "strict"

    policy webhook_guard {
        allow: use("llm") if body.source == "slack" || body.user.ends_with("@company.com")
        allow: publish("topic://alerts") if body.type == "security_alert"
        audit: all_operations
    }

    with context = {} {
        if body.type == "security_alert" {
            alert = {
                "summary": body.message,
                "source": body.source,
                "level": body.severity,
                "user": body.user
            }
            publish("topic://alerts", alert)
            return alert
        }

        return None
    }
}

Exemplo de Requisição HTTP

Enviar uma requisição webhook para acionar o agente:

curl -X POST http://localhost:8081/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret-token" \
  -d '{
    "type": "security_alert",
    "message": "Suspicious login detected",
    "source": "slack",
    "severity": "high",
    "user": "admin@company.com"
  }'

Resposta Esperada

O servidor retorna uma resposta JSON com a saída do agente:

{
  "status": "invoked",
  "agent_id": "webhook_handler",
  "timestamp": "2024-01-15T10:30:00Z"
}

Padrões de Integração

Endpoints de Webhook

Configurar diferentes agentes para diferentes fontes de webhook:

let routing_rules = vec![
    AgentRoutingRule {
        condition: RouteMatch::HeaderEquals("X-GitHub-Event".to_string(), "push".to_string()),
        agent: AgentId::from_str("github_push_handler")?,
    },
    AgentRoutingRule {
        condition: RouteMatch::JsonFieldEquals("source".to_string(), "stripe".to_string()),
        agent: AgentId::from_str("payment_processor")?,
    },
];

Integração com Gateway de API

Usar como serviço backend atrás de um gateway de API:

let config = HttpInputConfig {
    bind_address: "0.0.0.0".to_string(),
    port: 8081,
    path: "/api/webhook".to_string(),
    cors_enabled: true,
    forward_headers: vec![
        "X-Forwarded-For".to_string(),
        "X-Request-ID".to_string(),
    ],
    ..Default::default()
};

Endpoint de Verificação de Saúde

O servidor automaticamente fornece capacidades de verificação de saúde para balanceadores de carga e sistemas de monitoramento.

Tratamento de Erros

O módulo de Entrada HTTP fornece tratamento de erros abrangente:

• Erros de Autenticação: Retorna 401 Unauthorized para tokens inválidos
• Limitação de Taxa: Retorna 429 Too Many Requests quando limites de concorrência são excedidos
• Erros de Payload: Retorna 400 Bad Request para JSON malformado
• Erros de Agente: Retorna status de erro configurável com detalhes do erro
• Erros do Servidor: Retorna 500 Internal Server Error para falhas de runtime

Monitoramento e Observabilidade

Registro de Auditoria

Quando audit_enabled é true, o módulo registra informações estruturadas sobre todas as requisições:

INFO HTTP Input: Received request with 5 headers
INFO Would invoke agent webhook_handler with input data

Integração de Métricas

O módulo integra-se com o sistema de métricas do runtime Symbiont para fornecer:

• Contagem e taxa de requisições
• Distribuições de tempo de resposta
• Taxas de erro por tipo
• Contagens de conexões ativas
• Utilização de concorrência

Melhores Práticas

1. Segurança: Sempre usar autenticação em ambientes de produção
2. Limitação de Taxa: Configurar limites de concorrência apropriados baseados na sua infraestrutura
3. Monitoramento: Habilitar registro de auditoria e integrar com sua stack de monitoramento
4. Tratamento de Erros: Configurar respostas de erro apropriadas para seu caso de uso
5. Design de Agentes: Projetar agentes para lidar com formatos de entrada específicos de webhook
6. Limites de Recursos: Definir limites razoáveis de tamanho de corpo para prevenir esgotamento de recursos

Veja Também

• Guia de Introdução
• Guia DSL
• Referência da API
• Documentação do Runtime de Agentes