FRAMEWORK_CHANNEL_INPUT_MODE

This backend setting controls what kind of channel input the Agent Framework backend accepts.

It replaces the ambiguous use of CHANNEL_GATEWAY_MODE inside the backend.

Values

FRAMEWORK_CHANNEL_INPUT_MODE=embedded

The backend may use internal channel adapters to interpret simple/native channel payloads. This is useful for demos, labs, local frontend, curl tests, and simple environments.

FRAMEWORK_CHANNEL_INPUT_MODE=external

The backend accepts only a normalized GatewayRequest produced by an external Channel Gateway. It does not parse native WhatsApp, Voice, Teams, or other channel payloads.

Recommended enterprise setup

In the external channel gateway service:

CHANNEL_GATEWAY_RUNTIME_MODE=adapter

In this backend:

FRAMEWORK_CHANNEL_INPUT_MODE=external

Flow:

External channel / browser / customer adapter
  ↓
channel_gateway:7000
  CHANNEL_GATEWAY_RUNTIME_MODE=adapter
  ↓ GatewayRequest
agent_template_backend:8000
  FRAMEWORK_CHANNEL_INPUT_MODE=external
  ↓
LangGraph / Agents / MCP / Guardrails

Valid direct request to backend in external mode

curl -s -X POST "http://localhost:8000/gateway/message" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "web",
    "tenant_id": "default",
    "agent_id": "telecom_contas",
    "payload": {
      "message": "Quero consultar minha fatura",
      "session_id": "backend-external-ok-001"
    }
  }' | jq

Invalid direct request to backend in external mode

curl -i -s -X POST "http://localhost:8000/gateway/message" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero consultar minha fatura",
    "session_id": "raw-payload-error-001"
  }'

Expected result: HTTP 422.

Legacy compatibility

CHANNEL_GATEWAY_MODE is still present as a legacy alias for older environments, but new deployments should use:

FRAMEWORK_CHANNEL_INPUT_MODE=embedded|external

2.0 KiB Raw Blame History