Agent mute — models & tools FAQ

Operators and SEs often report: “The agent won’t use Jira / ticketing / observability tools” or “Chat starts then dies immediately.” Those symptoms usually share the same two gates — registered models that resolve, and integrations that actually attach tools — not a mysterious tool-router bug.

ELI5: Before Aiden can pick up a toolbox, it needs a working brain (LLM) and the toolbox must be clipped to the agent’s belt. A persona that mentions Jira is not enough.

Quick matrix

What you see	Likely cause	First check
Chat fails in ~1s; no tool calls	Tenant model refs missing / unresolvable	`GET /guild/api/v1/models?orgId=…` then `POST /guild/api/v1/models/{name}/test?orgId=…`
Logs: `Building orchestrator` with `tools: 0`	No integrations (or tools) attached to the agent	Agent `integrations` / foundation wiring
Logs: `Skipping model ref with missing scoped row` / `no valid models resolved from 0 registry rows`	Agent `model_names` point at names not registered in this org/tenant	Re-apply `aios-foundation` / register models in UI
Persona mentions Jira but no `jira_*` tools	Integration not on the agent (or Mode 1/2 reachability)	Agent detail + integration attach
Apply green, agent mute, tools missing	Broader wiring — see SE silence skill	Credentials, models, stage bindings, skills sync

FAQ

Why didn’t the agent call Jira (or another) integration?

Usually one of these, in order:

Orchestrator never became runnable — every model_names entry failed to resolve in the tenant registry. Chat aborts with a CONFIG_ERROR before any tool call.
Tools count is zero — the agent record has no usable tools at build time (tools: 0 in Guild logs). Persona text that says “you have access to Jira” does not attach MCP tools.
Integration attached but unreachable — Mode mismatch, empty vault secret, sidecar/image pull, or remote-runner not healthy. Fix after models + attach are green.

What’s the easiest way to prove LLMs work?

Use Aiden OS’s live model probe. It performs a short generation with the stored provider credentials — same path as the “Test model” button in LLM settings.

Confirm the model exists in the tenant.
Probe it by name.
Confirm the agent’s model_names list only names that exist and probe clean.

Is there a fetch / curl API?

Yes. While logged into the Aiden UI, open DevTools → Console and use same-origin fetch (cookies apply). From a terminal, use a bearer token against the tenant base URL.

Two things trip people up on every call below:

Prefix with /guild. On a tenant host the Guild API is served at {BASE}/guild/api/v1/…. Bare /api/v1/… only works when you talk to the Guild worker directly (port 8081) and 404s through the tenant edge.
Pass orgId. Models, agents, and integrations are scoped per workspace. Without orgId=<org-id> the request resolves in your personal namespace, so a model registered in the workspace looks missing (404) even though the agent can see it. Use the same workspace ID the agent runs under — it is the orgId in the UI URL, and matches project_id on the sg provider / GUILD_PROJECT_ID in scripts.

Browser console (logged into Aiden UI)

// Scope every call to the workspace the agent runs under.
// Drop the orgId param only if the agent lives in your personal namespace.
const ORG = '<org-id>'
const api = (path) =>
  '/guild/api/v1' + path + (path.includes('?') ? '&' : '?') + 'orgId=' + encodeURIComponent(ORG)

// List registered models
await (await fetch(api('/models'))).json()

// List model providers
await (await fetch(api('/model-providers'))).json()

// Live-probe one registered model (replace NAME)
await (await fetch(api('/models/' + encodeURIComponent('NAME') + '/test'), {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
})).json()

// Probe every model_name on an agent (replace AGENT)
const agent = await (await fetch(api('/agents/' + encodeURIComponent('AGENT')))).json()
const names = agent.model_names || agent.modelNames || []
for (const name of names) {
  const res = await fetch(api('/models/' + encodeURIComponent(name) + '/test'), {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
  })
  console.log(name, res.status, await res.json().catch(() => res.statusText))
}

// Agent attach surface + health
await (await fetch(api('/agents/' + encodeURIComponent('AGENT')))).json()
await (await fetch(api('/agents/' + encodeURIComponent('AGENT') + '/health'))).json()

If the relative path 404s from the page you are on, prepend the tenant host:

const BASE = 'https://<tenant-host>'
await (await fetch(BASE + api('/models'), { credentials: 'include' })).json()

How to read the probe

HTTP	Meaning
200 + `success: true`	Credentials + `model_id` work
404	Model name not registered at the scope you asked for — either it is missing in this org/tenant (classic “missing scoped row”), or `orgId` is wrong/omitted so the lookup hit your personal namespace
400	Registered, but provider/secret/`model_id` failed the live call

GET /guild/api/v1/agents/{name}/health mainly checks that configured secrets resolve. Prefer POST /guild/api/v1/models/{name}/test for real LLM connectivity.

curl (token auth)

BASE='https://<tenant-host>'
TOKEN='<aiden-token>'
ORG='<org-id>'   # workspace the agent runs under; omit for the personal namespace

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/guild/api/v1/models?orgId=$ORG" | jq .

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE/guild/api/v1/models/<model-name>/test?orgId=$ORG" | jq .

# Optional: probe without registering
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE/guild/api/v1/models/test?orgId=$ORG" \
  -d '{"provider_name":"<provider>","model_id":"<provider-model-id>"}' | jq .

Guild log signatures (no customer data needed)

When reviewing Guild server logs around a failed chat:

Log	Interpretation
`Building orchestrator` … `"tools":0`	Agent built with no tools — integrations not attached (or not discovering tools)
`Skipping model ref with missing scoped row`	Named model missing at the agent’s org/tenant scope
`Failed to resolve scoped model refs for agent` / `no valid models resolved from 0 registry rows`	Hard fail: no usable LLM — chat cannot run tools
`Activity error` … `CONFIG_ERROR` … `orchestrator build`	Same as above; not a Jira/MCP invoke bug
Repeated `unable to find workflow type: EnrichExecutionWorkflow`	Separate Temporal registration / Langfuse enrichment issue — does not explain missing tool calls

Fix order (minimal)

GET /guild/api/v1/models?orgId=… — every name in the agent’s model_names appears (scoped to the agent’s workspace).
POST /guild/api/v1/models/{name}/test?orgId=… — each name returns 200.
Agent record — integrations lists the ticketing / observability integration; re-check after apply.
Re-chat — confirm Guild logs show tools > 0 on Building orchestrator.
Only then dig into vault secrets, sidecar images, or remote-runner Mode 2.

Terraform path: re-apply aios-foundation (or Bedrock) so module.foundation.model_names matches what agents pin; attach integrations via the relevant aios-integration-* module and agent integrations / bindings.

Job	Skill / doc
Apply green but chat mute	`.cursor/skills/troubleshoot-agent-silence`
Integration Mode 1 vs 2	`.cursor/skills/wire-integration-and-reachability`
Skills mentioned but not loadable	Skills sync