External Channel Gateway

This service is a separate Channel Gateway that sits in front of the Agent Framework backend.

It has its own runtime mode, independent from the backend input mode.

Runtime modes

CHANNEL_GATEWAY_RUNTIME_MODE=adapter

adapter means this service receives channel-specific payloads and translates them into GatewayRequest before calling the Agent Framework backend.

CHANNEL_GATEWAY_RUNTIME_MODE=proxy

proxy means this service accepts only an already-built GatewayRequest at /gateway/message and forwards it after validation.

Recommended enterprise setup

In channel_gateway/.env:

CHANNEL_GATEWAY_RUNTIME_MODE=adapter
AGENT_FRAMEWORK_BASE_URL=http://localhost:8000
DEFAULT_TENANT_ID=default
DEFAULT_AGENT_ID=telecom_contas

In agent_template_backend/.env:

FRAMEWORK_CHANNEL_INPUT_MODE=external

This means:

channel_gateway:7000 = understands channel payloads and builds GatewayRequest
backend:8000         = accepts only GatewayRequest and does not parse native channel payloads

Run

cd channel_gateway
cp .env.example .env
uvicorn app.main:app --host 0.0.0.0 --port 7000

Test web adapter endpoint

curl -s -X POST "http://localhost:7000/channels/web/message" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero consultar minha fatura",
    "session_id": "external-gw-test-001",
    "user_id": "user-external-001",
    "message_id": "msg-external-001",
    "customer_key": "11999999999",
    "contract_key": "3000131180",
    "interaction_key": "301953872",
    "session_key": "external-gw-test-001"
  }' | jq

Test proxy mode

Set:

CHANNEL_GATEWAY_RUNTIME_MODE=proxy

Then call:

curl -s -X POST "http://localhost:7000/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": "proxy-test-001"
    }
  }' | jq

Important distinction

Do not use CHANNEL_GATEWAY_MODE=external to mean “this service is external”.

Use:

CHANNEL_GATEWAY_RUNTIME_MODE=adapter

for the external gateway service that owns adapters.