Appendix: Agent-worker Configuration

Agent-worker configuration#

.ait/agent-workers.json declares named messaging workers for one AIT Repository. RC.8 supports telegram, line, discord, and slack. The default location can be overridden with AIT_AGENT_CONFIG_PATH.

Read ait-agent-worker: Messaging and Reply Runtime first for the executable's role, complete command surface, message-to-reply path, transport modes, native Codex provider, runtime admission, and security limits. This appendix is the field-by-field authoring reference.

Canonical document shape#

{
  "version": 1,
  "workers": {
    "telegram/support": {
      "kind": "telegram",
      "name": "support",
      "mode": "poll",
      "username": "support_bot",
      "env_path": ".ait/agent-runtime/telegram.env",
      "request_timeout_seconds": 30,
      "local_reply": {
        "model": "gpt-5.4-mini",
        "reasoning_effort": "low",
        "sandbox": "workspace-write",
        "turn_timeout_seconds": 300
      }
    }
  }
}

The author file is the direct version plus workers object shown above. An internal diagnostic projection may wrap it as config; do not write that wrapper into the repository file.

Worker keys use exact <kind>/<name> form. The kind and name must be nonempty, the name must not contain /, and an explicit kind must match the key. version is integer 1 for the current contract. Invalid normalization issues cause worker startup to fail closed.

Common worker fields#

The runtime target is derived from .ait/config.json: solo_local runs locally; a remote workflow requires a valid default remote URL. The Repository default_model supplies the Telegram model fallback when no worker model is set.

Credential sources and precedence#

Credential fields must be nonempty strings. Resolution order is:

1. the worker entry;
2. the current process environment;
3. the worker env_path file.

Other behavior fields come from the worker entry or their compiled default; the env file does not override them. Environment files accept KEY=VALUE lines, blank lines, # comments, and one matching pair of single or double quotes around a value. They are not shell scripts.

Keep secrets out of a committed manifest. Prefer an owner-readable env file or the process environment, and use the exact variable names in the environment appendix.

local_reply#

Unknown fields in this nested object are rejected.

Sandbox choice is an execution boundary, not a messaging preference. Grant only the access required by the worker's Repository task.

Telegram fields#

LINE fields#

Discord fields#

The selected worker command determines whether public_key, bot_token, or both are required for that service mode.

Slack fields#

The selected Slack command determines whether socket credentials or an HTTP signing secret is mandatory.

Verification#

Use the agent-worker inspection and launch commands from the complete CLI reference. Diagnostic output reports only whether credentials are set; it does not print their values. Test webhook listeners on loopback before exposing them through a trusted reverse proxy.