Agent Configuration

All configuration is managed via environment variables, loaded from .env using pydantic-settings.

Required Variables

Variable	Description	Default
`ZIADA_API_URL`	Base URL of the ZiadaPOS Go API	`http://localhost:8080/api/v1`
`ZIADA_IDENTIFIER`	Owner's login email or phone	-
`ZIADA_PASSWORD`	Owner's login password	-

AI Agent (ask tool)

Variable	Description	Default
`NGAMIA_API_KEY`	Ngamia AI gateway API key	-
`NGAMIA_BASE_URL`	AI gateway URL	`https://api.ngamia.cc/v1`
`NGAMIA_MODEL`	Model to use	`openai/gpt-4o-mini`
`AGENT_MAX_STEPS`	Max tool-calling rounds per ask	`8`
`AGENT_TIMEOUT_SECONDS`	LLM call timeout	`120`

SMS (SendAfrica)

Variable	Description	Default
`SENDAFRICA_API_KEY`	SendAfrica API key (`SA-...`)	-
`SENDAFRICA_SENDER_ID`	Sender ID on SMS	`SendAfrika`
`SENDAFRICA_BASE_URL`	API base URL	`https://api.sendafrica.online`

Email (MailAfrica)

Variable	Description	Default
`MAILAFRICA_API_KEY`	MailAfrica API key (`MAIL_...`)	-
`MAILAFRICA_FROM_DOMAIN`	Verified sending domain	-
`MAILAFRICA_FROM_ADDRESS`	Sender email	-
`MAILAFRICA_FROM_NAME`	Display name	`ZiadaPOS`
`MAILAFRICA_BASE_URL`	API base URL	`https://api.mailafrica.online`

Transport & Server

Variable	Description	Default
`MCP_TRANSPORT`	`http` or `stdio`	`http`
`MCP_HOST`	Bind address	`0.0.0.0`
`MCP_PORT`	Bind port	`8081`
`LOG_LEVEL`	Logging level	`INFO`

Optional

Variable	Description	Default
`ZIADA_STORE_ID`	Force a specific store UUID	`""`

Example .env

# Required
ZIADA_API_URL=http://localhost:8080/api/v1
ZIADA_IDENTIFIER=+255712345678
ZIADA_PASSWORD=your_password
 
# AI Agent
NGAMIA_API_KEY=your_key_here
NGAMIA_BASE_URL=https://api.ngamia.cc/v1
NGAMIA_MODEL=openai/gpt-4o-mini
AGENT_MAX_STEPS=8
AGENT_TIMEOUT_SECONDS=120
 
# SMS
SENDAFRICA_API_KEY=SA-your_key
SENDAFRICA_SENDER_ID=ZiadaPOS
 
# Email
MAILAFRICA_API_KEY=MAIL-your_key
MAILAFRICA_FROM_DOMAIN=ziadapos.com
MAILAFRICA_FROM_ADDRESS=noreply@ziadapos.com
MAILAFRICA_FROM_NAME=ZiadaPOS
 
# Transport
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8081
LOG_LEVEL=INFO

Configuration Singleton

The get_settings() function in config.py returns a cached Settings instance. It's an @lru_cache-decorated factory that ensures a single instance is used throughout the application.

Domain Reference Deployment