Passa al contenuto principale

AgentCore Telegram Akira Setup

Prerequisiti​

  • Backend Akira deployato con /mcp/* raggiungibile da AgentCore.
  • infra/roles/management/files/agentcore-akira-plugin.yml deployato in /opt/akira/agentcore/config/akira-plugin.yml.
  • Gruppo Telegram dedicato akira-noc creato da un admin NOC.

Generazione MCP token​

Genera un token plain e il relativo hash Argon2id su una macchina fidata:

export TOKEN="$(openssl rand -base64 48)"
uv run python - <<'PY'
import os
from akira_backend.core.passwords import hash_password

print(hash_password(os.environ["TOKEN"]))
PY

Inserisci l'hash in DB:

INSERT INTO mcp_api_tokens (name, token_hash, scopes, expires_at)
VALUES (
  'agentcore-prod',
  '<argon2_hash>',
  ARRAY['mcp.tools.call'],
  '2027-05-21'::timestamp
)
ON CONFLICT (name) DO UPDATE
SET token_hash = EXCLUDED.token_hash,
    scopes = EXCLUDED.scopes,
    expires_at = EXCLUDED.expires_at,
    revoked_at = NULL;

Salva solo il token plain in Ansible Vault:

vault_agentcore_mcp_token: "<plain-token>"

Configurazione Telegram​

  1. Crea il gruppo Telegram akira-noc.
  2. Aggiungi il bot AgentCore al gruppo.
  3. Recupera gli user ID Telegram degli operatori autorizzati.
  4. Aggiorna Ansible Vault:
vault_agentcore_telegram_token: "<bot-token>"
vault_agentcore_telegram_allowed_user_ids:
  - 123456789
  - 987654321
  1. Esegui il deploy management:
ansible-playbook -i infra/inventory infra/playbooks/deploy_management.yml --limit mgmt

Smoke Test​

Nel gruppo akira-noc:

/start

Risultato atteso: AgentCore risponde con benvenuto e comandi disponibili.

Saldo TestCo?

Risultato atteso: AgentCore chiama /mcp/call/get_company_balance con Authorization: Bearer <AGENTCORE_AKIRA_MCP_TOKEN> e restituisce saldo con valuta.

Ricarica TestCo EUR 100

Risultato atteso:

  1. AgentCore chiede conferma all'utente.
  2. Dopo conferma chiama POST /mcp/confirmations.
  3. Ripete la write con X-Confirmation-Token.
  4. Il backend ritorna 200 OK e l'audit log usa actor agentcore:<user_id>.

Troubleshooting​

  • 401 missing_mcp_api_token: il container non passa AGENTCORE_AKIRA_MCP_TOKEN come Bearer token verso /mcp/*.
  • 403 invalid_mcp_api_token: token plain in vault non corrisponde all'hash DB, token scaduto, revocato o privo scope mcp.tools.call.
  • 428 confirmation_required: comportamento atteso per write tool senza X-Confirmation-Token.
  • LLM quota exhausted: AgentCore deve rispondere service unavailable e non ritentare automaticamente operazioni write.