multica-ai/multica · error

ambiguous agent %q; matches: %s

Error message

ambiguous agent %q; matches:
%s

What it means

resolveAgent does case-insensitive substring matching, so a short query can match several agents. When more than one agent name contains the query string, the CLI refuses to guess and lists every match with its truncated UUID so the user can disambiguate.

Source

Thrown at server/cmd/multica/cmd_autopilot.go:811

	var matches []match
	for _, a := range agents {
		aName := strVal(a, "name")
		if strings.Contains(strings.ToLower(aName), nameLower) {
			matches = append(matches, match{ID: strVal(a, "id"), Name: aName})
		}
	}

	switch len(matches) {
	case 0:
		return "", fmt.Errorf("no agent found matching %q", nameOrID)
	case 1:
		return matches[0].ID, nil
	default:
		var parts []string
		for _, m := range matches {
			parts = append(parts, fmt.Sprintf("  %q (%s)", m.Name, truncateID(m.ID)))
		}
		return "", fmt.Errorf("ambiguous agent %q; matches:\n%s", nameOrID, strings.Join(parts, "\n"))
	}
}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Use a longer, unique substring of the intended agent's name from the printed match list.
2. Or use the exact UUID shown next to the intended match (e.g. the full form of the truncated ID).

Example fix

# before: ambiguous
multica autopilot trigger create --name t1 --agent bot
# after
multica autopilot trigger create --name t1 --agent review-bot

# refuse ambiguous names before invoking the CLI
count=$(multica api get "/api/agents?workspace_id=$WS" | jq --arg n "$AGENT" '[.[] | select((.name | ascii_downcase | contains($n | ascii_downcase)))] | length')
[ "$count" -eq 1 ] || { echo "agent '$AGENT' matched $count agents; use a UUID" >&2; exit 2; }

When it happens

Trigger: `--agent bot` when the workspace has 'triage-bot', 'review-bot', and 'deploy-bot'; any prefix like 'a' matching many agent names.

Common situations: Naming schemes that share a common suffix/prefix; auto-generated agent names with a shared stem; abbreviating names in scripts.

Related errors

• no agent found matching %q
• list agents: %w
• get agent: %w
• --name is required
• --runtime-id is required

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/d0ccadd8a7a0724f. Report an issue: GitHub.